0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 ms copyright to
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a . In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d sing:.**.** M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 nd not evil..**
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 May you find
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 forgiveness for
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 give others..**
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 aking more than
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43 rograms. If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69 ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 s file, then it
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20 ite, is subject
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53 grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74 e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 erimental". Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64 s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20 to SQLite. We
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 e changes.** to
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65 erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20 r changes if.**
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20 experience from
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64 use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63 " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65 hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67 ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74 e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69 ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68 m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66 is file. This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65 ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61 suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 me of this file
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74 under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69 ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65 .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69 r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20 s file (such as
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65 inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29 version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73 and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65 name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20 3.h" as.** part
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29 cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e 69 $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 34 35 38 20 32 30 30 39 2f 30 n,v 1.458 2009/0
05f0: 36 2f 31 39 20 32 32 3a 35 30 3a 33 31 20 64 72 6/19 22:50:31 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 35 "3.6.15
0e90: 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ".#define SQLITE
0ea0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 _VERSION_NUMBER
0eb0: 20 33 30 30 36 30 31 35 0a 0a 2f 2a 0a 2a 2a 20 3006015../*.**
0ec0: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 CAPI3REF: Run-Ti
0ed0: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 me Library Versi
0ee0: 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 on Numbers {H100
0ef0: 32 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 20 20} <S60100>.**
0f00: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 KEYWORDS: sqlite
0f10: 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3_version.**.**
0f20: 54 68 65 73 65 20 66 65 61 74 75 72 65 73 20 70 These features p
0f30: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 rovide the same
0f40: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 information as t
0f50: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 he [SQLITE_VERSI
0f60: 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 ON].** and [SQLI
0f70: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
0f80: 52 5d 20 23 64 65 66 69 6e 65 73 20 69 6e 20 74 R] #defines in t
0f90: 68 65 20 68 65 61 64 65 72 2c 20 62 75 74 20 61 he header, but a
0fa0: 72 65 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a re associated.**
0fb0: 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 with the librar
0fc0: 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 y instead of the
0fd0: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 43 header file. C
0fe0: 61 75 74 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d autious programm
0ff0: 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63 ers might.** inc
1000: 6c 75 64 65 20 61 20 63 68 65 63 6b 20 69 6e 20 lude a check in
1010: 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f their applicatio
1020: 6e 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 n to verify that
1030: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 .** sqlite3_libv
1040: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 ersion_number()
1050: 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 always returns t
1060: 68 65 20 76 61 6c 75 65 0a 2a 2a 20 5b 53 51 4c he value.** [SQL
1070: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
1080: 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ER]..**.** The s
1090: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
10a0: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 n() function ret
10b0: 75 72 6e 73 20 74 68 65 20 73 61 6d 65 20 69 6e urns the same in
10c0: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a formation as is.
10d0: 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 ** in the sqlite
10e0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 3_version[] stri
10f0: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 ng constant. Th
1100: 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 e function is pr
1110: 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73 ovided.** for us
1120: 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 e in DLLs since
1130: 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c DLL users usuall
1140: 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 64 69 y do not have di
1150: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 rect access to s
1160: 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e tring.** constan
1170: 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c ts within the DL
1180: 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 L..**.** Require
1190: 6d 65 6e 74 73 3a 20 5b 48 31 30 30 32 31 5d 20 ments: [H10021]
11a0: 5b 48 31 30 30 32 32 5d 20 5b 48 31 30 30 32 33 [H10022] [H10023
11b0: 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 ].*/.SQLITE_EXTE
11c0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 RN const char sq
11d0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b lite3_version[];
11e0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
11f0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
1200: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 void);.int sqlit
1210: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 e3_libversion_nu
1220: 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a mber(void);../*.
1230: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 ** CAPI3REF: Tes
1240: 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 t To See If The
1250: 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 65 61 Library Is Threa
1260: 64 73 61 66 65 20 7b 48 31 30 31 30 30 7d 20 3c dsafe {H10100} <
1270: 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 S60100>.**.** SQ
1280: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 Lite can be comp
1290: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 iled with or wit
12a0: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 hout mutexes. W
12b0: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 hen.** the [SQLI
12c0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 TE_THREADSAFE] C
12d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
12e0: 63 72 6f 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 cro 1 or 2, mute
12f0: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c xes.** are enabl
1300: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 ed and SQLite is
1310: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 threadsafe. Wh
1320: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 en the.** [SQLIT
1330: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 E_THREADSAFE] ma
1340: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 cro is 0, .** th
1350: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d e mutexes are om
1360: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 itted. Without
1370: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 the mutexes, it
1380: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 is not safe.** t
1390: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e o use SQLite con
13a0: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d currently from m
13b0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 ore than one thr
13c0: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c ead..**.** Enabl
13d0: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 ing mutexes incu
13e0: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 rs a measurable
13f0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 performance pena
1400: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 lty..** So if sp
1410: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 eed is of utmost
1420: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 importance, it
1430: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 makes sense to d
1440: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 isable.** the mu
1450: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 texes. But for
1460: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 maximum safety,
1470: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 mutexes should b
1480: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 e enabled..** Th
1490: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 e default behavi
14a0: 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 or is for mutexe
14b0: 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e s to be enabled.
14c0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
14d0: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
14e0: 64 20 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74 d by a program t
14f0: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 o make sure that
1500: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 the.** version
1510: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 of SQLite that i
1520: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 t is linking aga
1530: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 inst was compile
1540: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 d with.** the de
1550: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 sired setting of
1560: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
1570: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a EADSAFE] macro..
1580: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
1590: 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 face only report
15a0: 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 s on the compile
15b0: 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 -time mutex sett
15c0: 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 ing.** of the [S
15d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
15e0: 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 ] flag. If SQLi
15f0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
1600: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 ith.** SQLITE_TH
1610: 52 45 41 44 53 41 46 45 3d 31 20 74 68 65 6e 20 READSAFE=1 then
1620: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 mutexes are enab
1630: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 led by default b
1640: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c ut.** can be ful
1650: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 ly or partially
1660: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 disabled using a
1670: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
1680: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 3_config()].** w
1690: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 ith the verbs [S
16a0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
16b0: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c GLETHREAD], [SQL
16c0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
16d0: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b THREAD],.** or [
16e0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
16f0: 54 45 58 5d 2e 20 20 54 68 65 20 72 65 74 75 72 TEX]. The retur
1700: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 n value of this
1710: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a function shows.*
1720: 2a 20 6f 6e 6c 79 20 74 68 65 20 64 65 66 61 75 * only the defau
1730: 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 lt compile-time
1740: 73 65 74 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79 setting, not any
1750: 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 run-time change
1760: 73 0a 2a 2a 20 74 6f 20 74 68 61 74 20 73 65 74 s.** to that set
1770: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 ting..**.** See
1780: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d the [threading m
1790: 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 ode] documentati
17a0: 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 on for additiona
17b0: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
17c0: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
17d0: 73 3a 20 5b 48 31 30 31 30 31 5d 20 5b 48 31 30 s: [H10101] [H10
17e0: 31 30 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 102].*/.int sqli
17f0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 te3_threadsafe(v
1800: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 oid);../*.** CAP
1810: 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 I3REF: Database
1820: 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c Connection Handl
1830: 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 30 32 e {H12000} <S402
1840: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 00>.** KEYWORDS:
1850: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 {database conne
1860: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 ction} {database
1870: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a connections}.**
1880: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 .** Each open SQ
1890: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 Lite database is
18a0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
18b0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
18c0: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 instance of.** t
18d0: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 he opaque struct
18e0: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 ure named "sqlit
18f0: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 e3". It is usef
1900: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 ul to think of a
1910: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 n sqlite3.** poi
1920: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 nter as an objec
1930: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 t. The [sqlite3
1940: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
1950: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e e3_open16()], an
1960: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 d.** [sqlite3_op
1970: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 en_v2()] interfa
1980: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 ces are its cons
1990: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 tructors, and [s
19a0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a qlite3_close()].
19b0: 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 72 75 ** is its destru
19c0: 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65 ctor. There are
19d0: 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 many other inte
19e0: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a rfaces (such as.
19f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
1a00: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
1a10: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
1a20: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b ion()], and.** [
1a30: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
1a40: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 eout()] to name
1a50: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 but three) that
1a60: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 are methods on a
1a70: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a n.** sqlite3 obj
1a80: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ect..*/.typedef
1a90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 struct sqlite3 s
1aa0: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 qlite3;../*.** C
1ab0: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 API3REF: 64-Bit
1ac0: 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b 48 Integer Types {H
1ad0: 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 10200} <S10110>.
1ae0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
1af0: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 ite_int64 sqlite
1b00: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 _uint64.**.** Be
1b10: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e cause there is n
1b20: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d o cross-platform
1b30: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 way to specify
1b40: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 64-bit integer t
1b50: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 ypes.** SQLite i
1b60: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 ncludes typedefs
1b70: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e for 64-bit sign
1b80: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 ed and unsigned
1b90: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 integers..**.**
1ba0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 The sqlite3_int6
1bb0: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 4 and sqlite3_ui
1bc0: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65 nt64 are the pre
1bd0: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69 ferred type defi
1be0: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 nitions..** The
1bf0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 sqlite_int64 and
1c00: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 sqlite_uint64 t
1c10: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 ypes are support
1c20: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ed for backwards
1c30: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 .** compatibilit
1c40: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 y only..**.** Re
1c50: 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 quirements: [H10
1c60: 32 30 31 5d 20 5b 48 31 30 32 30 32 5d 0a 2a 2f 201] [H10202].*/
1c70: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 .#ifdef SQLITE_I
1c80: 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 NT64_TYPE. type
1c90: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 def SQLITE_INT64
1ca0: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 _TYPE sqlite_int
1cb0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 64;. typedef un
1cc0: 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e signed SQLITE_IN
1cd0: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f T64_TYPE sqlite_
1ce0: 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 uint64;.#elif de
1cf0: 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 fined(_MSC_VER)
1d00: 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 || defined(__BOR
1d10: 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 LANDC__). typed
1d20: 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 ef __int64 sqlit
1d30: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 e_int64;. typed
1d40: 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e ef unsigned __in
1d50: 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 t64 sqlite_uint6
1d60: 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 4;.#else. typed
1d70: 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 ef long long int
1d80: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 sqlite_int64;.
1d90: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 typedef unsigne
1da0: 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 d long long int
1db0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 sqlite_uint64;.#
1dc0: 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 endif.typedef sq
1dd0: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 lite_int64 sqlit
1de0: 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 e3_int64;.typede
1df0: 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 f sqlite_uint64
1e00: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a sqlite3_uint64;.
1e10: 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c ./*.** If compil
1e20: 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 ing for a proces
1e30: 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 sor that lacks f
1e40: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 loating point su
1e50: 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 pport,.** substi
1e60: 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 tute integer for
1e70: 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e floating-point.
1e80: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 .*/.#ifdef SQLIT
1e90: 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f E_OMIT_FLOATING_
1ea0: 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 POINT.# define d
1eb0: 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e ouble sqlite3_in
1ec0: 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a t64.#endif../*.*
1ed0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 * CAPI3REF: Clos
1ee0: 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 ing A Database C
1ef0: 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 onnection {H1201
1f00: 30 7d 20 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 0} <S30100><S402
1f10: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 00>.**.** This r
1f20: 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64 65 outine is the de
1f30: 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 structor for the
1f40: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
1f50: 74 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 t..**.** Applica
1f60: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 tions should [sq
1f70: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c lite3_finalize |
1f80: 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b finalize] all [
1f90: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1fa0: 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c nts].** and [sql
1fb0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 ite3_blob_close
1fc0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c | close] all [BL
1fd0: 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f OB handles] asso
1fe0: 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 ciated with.** t
1ff0: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a he [sqlite3] obj
2000: 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 ect prior to att
2010: 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 empting to close
2020: 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 the object..**
2030: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 The [sqlite3_nex
2040: 74 5f 73 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 t_stmt()] interf
2050: 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ace can be used
2060: 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a to locate all.**
2070: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2080: 6d 65 6e 74 73 5d 20 61 73 73 6f 63 69 61 74 65 ments] associate
2090: 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 d with a [databa
20a0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
20b0: 66 20 64 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 f desired..** Ty
20c0: 70 69 63 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 pical code might
20d0: 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a look like this:
20e0: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
20f0: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 te><pre>.** sqli
2100: 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b te3_stmt *pStmt;
2110: 0a 2a 2a 20 77 68 69 6c 65 28 20 28 70 53 74 6d .** while( (pStm
2120: 74 20 3d 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 t = sqlite3_next
2130: 5f 73 74 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 _stmt(db, 0))!=0
2140: 20 29 7b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 ){.**
2150: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2160: 28 70 53 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a (pStmt);.** }.**
2170: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
2180: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 ote>.**.** If [s
2190: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 qlite3_close()]
21a0: 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 is invoked while
21b0: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
21c0: 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 s open,.** the t
21d0: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 ransaction is au
21e0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c tomatically roll
21f0: 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 ed back..**.** T
2200: 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 he C parameter t
2210: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 o [sqlite3_close
2220: 28 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 (C)] must be eit
2230: 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f her a NULL.** po
2240: 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c inter or an [sql
2250: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 ite3] object poi
2260: 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a nter obtained.**
2270: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f from [sqlite3_o
2280: 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
2290: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a _open16()], or.*
22a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f * [sqlite3_open_
22b0: 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 v2()], and not p
22c0: 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 reviously closed
22d0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
22e0: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 30 31 31 ents:.** [H12011
22f0: 5d 20 5b 48 31 32 30 31 32 5d 20 5b 48 31 32 30 ] [H12012] [H120
2300: 31 33 5d 20 5b 48 31 32 30 31 34 5d 20 5b 48 31 13] [H12014] [H1
2310: 32 30 31 35 5d 20 5b 48 31 32 30 31 39 5d 0a 2a 2015] [H12019].*
2320: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c /.int sqlite3_cl
2330: 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a ose(sqlite3 *);.
2340: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 ./*.** The type
2350: 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 for a callback f
2360: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 unction..** This
2370: 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 is legacy and d
2380: 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 eprecated. It i
2390: 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 s included for h
23a0: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d istorical.** com
23b0: 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 patibility and i
23c0: 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 s not documented
23d0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 ..*/.typedef int
23e0: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 (*sqlite3_callb
23f0: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 ack)(void*,int,c
2400: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a har**, char**);.
2410: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2420: 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 One-Step Query
2430: 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 Execution Interf
2440: 61 63 65 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 ace {H12100} <S1
2450: 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0000>.**.** The
2460: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
2470: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f nterface is a co
2480: 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 nvenient way of
2490: 72 75 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d running one or m
24a0: 6f 72 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ore.** SQL state
24b0: 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20 68 61 ments without ha
24c0: 76 69 6e 67 20 74 6f 20 77 72 69 74 65 20 61 20 ving to write a
24d0: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 lot of C code.
24e0: 54 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 The UTF-8 encode
24f0: 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 d.** SQL stateme
2500: 6e 74 73 20 61 72 65 20 70 61 73 73 65 64 20 69 nts are passed i
2510: 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 n as the second
2520: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
2530: 69 74 65 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 ite3_exec()..**
2540: 54 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 61 The statements a
2550: 72 65 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 re evaluated one
2560: 20 62 79 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 by one until ei
2570: 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 ther an error or
2580: 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 72 75 70 74 .** an interrupt
2590: 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c is encountered,
25a0: 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 79 20 61 or until they a
25b0: 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 re all done. Th
25c0: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 0a e 3rd parameter.
25d0: 2a 2a 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 ** is an optiona
25e0: 6c 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 l callback that
25f0: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 is invoked once
2600: 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 for each row of
2610: 61 6e 79 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 any query.** res
2620: 75 6c 74 73 20 70 72 6f 64 75 63 65 64 20 62 79 ults produced by
2630: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
2640: 6e 74 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 nts. The 5th pa
2650: 72 61 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 rameter tells wh
2660: 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 ere.** to write
2670: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 any error messag
2680: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 es..**.** The er
2690: 72 6f 72 20 6d 65 73 73 61 67 65 20 70 61 73 73 ror message pass
26a0: 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 ed back through
26b0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 the 5th paramete
26c0: 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 r is held.** in
26d0: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
26e0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
26f0: 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f lloc()]. To avo
2700: 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b id a memory leak
2710: 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 ,.** the calling
2720: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
2730: 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 uld call [sqlite
2740: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 3_free()] on any
2750: 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 error.** messag
2760: 65 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 e returned throu
2770: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d gh the 5th param
2780: 65 74 65 72 20 77 68 65 6e 20 69 74 20 68 61 73 eter when it has
2790: 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a finished using.
27a0: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 ** the error mes
27b0: 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 sage..**.** If t
27c0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
27d0: 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 in the 2nd para
27e0: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 meter is NULL or
27f0: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
2800: 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20 .** or a string
2810: 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 containing only
2820: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 20 63 whitespace and c
2830: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f omments, then no
2840: 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e SQL.** statemen
2850: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 ts are evaluated
2860: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 and the databas
2870: 65 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 e is not changed
2880: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
2890: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 te3_exec() inter
28a0: 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e face is implemen
28b0: 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a ted in terms of.
28c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
28d0: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
28e0: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 te3_step()], and
28f0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
2900: 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 ze()]..** The sq
2910: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72 6f 75 lite3_exec() rou
2920: 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e tine does nothin
2930: 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 g to the databas
2940: 65 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 e that cannot be
2950: 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c done.** by [sql
2960: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2970: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 )], [sqlite3_ste
2980: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 p()], and [sqlit
2990: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a e3_finalize()]..
29a0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
29b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
29c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6d 75 lite3_exec()] mu
29d0: 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64 20 61 st be an valid a
29e0: 6e 64 20 6f 70 65 6e 0a 2a 2a 20 5b 64 61 74 61 nd open.** [data
29f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
2a00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 61 74 61 ..**.** The data
2a10: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2a20: 6d 75 73 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 must not be clos
2a30: 65 64 20 77 68 69 6c 65 0a 2a 2a 20 5b 73 71 6c ed while.** [sql
2a40: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 ite3_exec()] is
2a50: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 running..**.** T
2a60: 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 he calling funct
2a70: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 5b ion should use [
2a80: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
2a90: 74 6f 20 66 72 65 65 0a 2a 2a 20 74 68 65 20 6d to free.** the m
2aa0: 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d emory that *errm
2ab0: 73 67 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 sg is left point
2ac0: 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 ing at once the
2ad0: 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 error.** message
2ae0: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 is no longer ne
2af0: 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eded..**.** The
2b00: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 SQL statement te
2b10: 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 xt in the 2nd pa
2b20: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
2b30: 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 6d te3_exec()].** m
2b40: 75 73 74 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 ust remain uncha
2b50: 6e 67 65 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 nged while [sqli
2b60: 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 te3_exec()] is r
2b70: 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 unning..**.** Re
2b80: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
2b90: 48 31 32 31 30 31 5d 20 5b 48 31 32 31 30 32 5d H12101] [H12102]
2ba0: 20 5b 48 31 32 31 30 34 5d 20 5b 48 31 32 31 30 [H12104] [H1210
2bb0: 35 5d 20 5b 48 31 32 31 30 37 5d 20 5b 48 31 32 5] [H12107] [H12
2bc0: 31 31 30 5d 20 5b 48 31 32 31 31 33 5d 20 5b 48 110] [H12113] [H
2bd0: 31 32 31 31 36 5d 0a 2a 2a 20 5b 48 31 32 31 31 12116].** [H1211
2be0: 39 5d 20 5b 48 31 32 31 32 32 5d 20 5b 48 31 32 9] [H12122] [H12
2bf0: 31 32 35 5d 20 5b 48 31 32 31 33 31 5d 20 5b 48 125] [H12131] [H
2c00: 31 32 31 33 34 5d 20 5b 48 31 32 31 33 37 5d 20 12134] [H12137]
2c10: 5b 48 31 32 31 33 38 5d 0a 2a 2f 0a 69 6e 74 20 [H12138].*/.int
2c20: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 sqlite3_exec(.
2c30: 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 sqlite3*,
2c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2c50: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e /* An
2c60: 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a open database *
2c70: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
2c80: 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 sql,
2c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
2ca0: 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c * SQL to be eval
2cb0: 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 uated */. int (
2cc0: 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a *callback)(void*
2cd0: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 ,int,char**,char
2ce0: 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 **), /* Callbac
2cf0: 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 k function */.
2d00: 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 void *,
2d10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2d20: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 /* 1s
2d30: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 t argument to ca
2d40: 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 llback */. char
2d50: 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 **errmsg
2d60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2d70: 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 /* Error
2d80: 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 msg written here
2d90: 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
2da0: 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 PI3REF: Result C
2db0: 6f 64 65 73 20 7b 48 31 30 32 31 30 7d 20 3c 53 odes {H10210} <S
2dc0: 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 10700>.** KEYWOR
2dd0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 DS: SQLITE_OK {e
2de0: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f rror code} {erro
2df0: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 r codes}.** KEYW
2e00: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f ORDS: {result co
2e10: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 de} {result code
2e20: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 s}.**.** Many SQ
2e30: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 Lite functions r
2e40: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 eturn an integer
2e50: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f result code fro
2e60: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a m the set shown.
2e70: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72 ** here in order
2e80: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75 to indicates su
2e90: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 ccess or failure
2ea0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f ..**.** New erro
2eb0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 r codes may be a
2ec0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 dded in future v
2ed0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
2ee0: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 e..**.** See als
2ef0: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 o: [SQLITE_IOERR
2f00: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 _READ | extended
2f10: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a result codes].*
2f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2f30: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 _OK 0
2f40: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 /* Successful
2f50: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 result */./* beg
2f60: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d inning-of-error-
2f70: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 codes */.#define
2f80: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 SQLITE_ERROR
2f90: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 1 /* SQL
2fa0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 error or missing
2fb0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 database */.#de
2fc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
2fd0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 RNAL 2 /*
2fe0: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 Internal logic e
2ff0: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a rror in SQLite *
3000: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3010: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 _PERM 3
3020: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d /* Access perm
3030: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f ission denied */
3040: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3050: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 ABORT 4
3060: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 /* Callback rou
3070: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 tine requested a
3080: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 n abort */.#defi
3090: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 ne SQLITE_BUSY
30a0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 5 /* Th
30b0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
30c0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 is locked */.#de
30d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
30e0: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 ED 6 /*
30f0: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 A table in the d
3100: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 atabase is locke
3110: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
3120: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 ITE_NOMEM
3130: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 7 /* A malloc
3140: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 () failed */.#de
3150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
3160: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 ONLY 8 /*
3170: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 Attempt to write
3180: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 a readonly data
3190: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 base */.#define
31a0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
31b0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 9 /* Opera
31c0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 tion terminated
31d0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 by sqlite3_inter
31e0: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 rupt()*/.#define
31f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 SQLITE_IOERR
3200: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 10 /* Some
3210: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f kind of disk I/
3220: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 O error occurred
3230: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
3240: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 TE_CORRUPT 1
3250: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 1 /* The datab
3260: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 ase disk image i
3270: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 s malformed */.#
3280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
3290: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f TFOUND 12 /
32a0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c * NOT USED. Tabl
32b0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 e or record not
32c0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 found */.#define
32d0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 SQLITE_FULL
32e0: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 13 /* Inse
32f0: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 rtion failed bec
3300: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 ause database is
3310: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 full */.#define
3320: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e SQLITE_CANTOPEN
3330: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 14 /* Unab
3340: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 le to open the d
3350: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a atabase file */.
3360: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 #define SQLITE_P
3370: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 ROTOCOL 15
3380: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 /* NOT USED. Dat
3390: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f abase lock proto
33a0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 col error */.#de
33b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 fine SQLITE_EMPT
33c0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 Y 16 /*
33d0: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 Database is empt
33e0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
33f0: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 ITE_SCHEMA
3400: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 17 /* The data
3410: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e base schema chan
3420: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ged */.#define S
3430: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 QLITE_TOOBIG
3440: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 18 /* String
3450: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 or BLOB exceeds
3460: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 size limit */.#
3470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
3480: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f NSTRAINT 19 /
3490: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 * Abort due to c
34a0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 onstraint violat
34b0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ion */.#define S
34c0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 QLITE_MISMATCH
34d0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 20 /* Data t
34e0: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a ype mismatch */.
34f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
3500: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 ISUSE 21
3510: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 /* Library used
3520: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 incorrectly */.#
3530: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
3540: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f LFS 22 /
3550: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 * Uses OS featur
3560: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 es not supported
3570: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 on host */.#def
3580: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 ine SQLITE_AUTH
3590: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 23 /* A
35a0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e uthorization den
35b0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ied */.#define S
35c0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 QLITE_FORMAT
35d0: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 24 /* Auxili
35e0: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 ary database for
35f0: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 mat error */.#de
3600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 fine SQLITE_RANG
3610: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 E 25 /*
3620: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 2nd parameter to
3630: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 sqlite3_bind ou
3640: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 t of range */.#d
3650: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 efine SQLITE_NOT
3660: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a ADB 26 /*
3670: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 File opened tha
3680: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 t is not a datab
3690: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 ase file */.#def
36a0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 ine SQLITE_ROW
36b0: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 100 /* s
36c0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 qlite3_step() ha
36d0: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 s another row re
36e0: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ady */.#define S
36f0: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 QLITE_DONE
3700: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 101 /* sqlite
3710: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 3_step() has fin
3720: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 ished executing
3730: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 */./* end-of-err
3740: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a or-codes */../*.
3750: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 ** CAPI3REF: Ext
3760: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 ended Result Cod
3770: 65 73 20 7b 48 31 30 32 32 30 7d 20 3c 53 31 30 es {H10220} <S10
3780: 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 700>.** KEYWORDS
3790: 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f : {extended erro
37a0: 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 r code} {extende
37b0: 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a d error codes}.*
37c0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 * KEYWORDS: {ext
37d0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
37e0: 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 e} {extended res
37f0: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a ult codes}.**.**
3800: 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 In its default
3810: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 configuration, S
3820: 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e QLite API routin
3830: 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 es return one of
3840: 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 26 integer.** [
3850: 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 SQLITE_OK | resu
3860: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 lt codes]. Howe
3870: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 ver, experience
3880: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d has shown that m
3890: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 any of.** these
38a0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
38b0: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 too coarse-grai
38c0: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f ned. They do no
38d0: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 t provide as.**
38e0: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e much information
38f0: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 about problems
3900: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d as programmers m
3910: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 ight like. In a
3920: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 n effort to.** a
3930: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 ddress this, new
3940: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 er versions of S
3950: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 QLite (version 3
3960: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 .3.8 and later)
3970: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f include.** suppo
3980: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 rt for additiona
3990: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 l result codes t
39a0: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 hat provide more
39b0: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d detailed inform
39c0: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 ation.** about e
39d0: 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e rrors. The exten
39e0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
39f0: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 are enabled or
3a00: 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 disabled.** on a
3a10: 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f per database co
3a20: 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 nnection basis u
3a30: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c sing the.** [sql
3a40: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 ite3_extended_re
3a50: 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 sult_codes()] AP
3a60: 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 I..**.** Some of
3a70: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 the available e
3a80: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
3a90: 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 odes are listed
3aa0: 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 here..** One may
3ab0: 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 expect the numb
3ac0: 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 er of extended r
3ad0: 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c esult codes will
3ae0: 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 be expand.** ov
3af0: 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 er time. Softwa
3b00: 72 65 20 74 68 61 74 20 75 73 65 73 20 65 78 74 re that uses ext
3b10: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
3b20: 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 es should expect
3b30: 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 .** to see new r
3b40: 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 esult codes in f
3b50: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
3b60: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
3b70: 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 The SQLITE_OK re
3b80: 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e sult code will n
3b90: 65 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 ever be extended
3ba0: 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 . It will alway
3bb0: 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 s.** be exactly
3bc0: 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 zero..*/.#define
3bd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 SQLITE_IOERR_RE
3be0: 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AD
3bf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
3c00: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
3c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f SQLITE_IOERR_SHO
3c20: 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 RT_READ (
3c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
3c40: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
3c50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 QLITE_IOERR_WRIT
3c60: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 E (S
3c70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 QLITE_IOERR | (3
3c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
3c90: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 LITE_IOERR_FSYNC
3ca0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
3cb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c LITE_IOERR | (4<
3cc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
3cd0: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 ITE_IOERR_DIR_FS
3ce0: 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c YNC (SQL
3cf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c ITE_IOERR | (5<<
3d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
3d10: 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 TE_IOERR_TRUNCAT
3d20: 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 E (SQLI
3d30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 TE_IOERR | (6<<8
3d40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
3d50: 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 E_IOERR_FSTAT
3d60: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
3d70: 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 E_IOERR | (7<<8)
3d80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
3d90: 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 _IOERR_UNLOCK
3da0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
3db0: 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 _IOERR | (8<<8))
3dc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3dd0: 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 IOERR_RDLOCK
3de0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
3df0: 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a IOERR | (9<<8)).
3e00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3e10: 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 OERR_DELETE
3e20: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3e30: 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a OERR | (10<<8)).
3e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3e50: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 OERR_BLOCKED
3e60: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3e70: 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a OERR | (11<<8)).
3e80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3e90: 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 OERR_NOMEM
3ea0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3eb0: 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a OERR | (12<<8)).
3ec0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3ed0: 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 OERR_ACCESS
3ee0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3ef0: 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a OERR | (13<<8)).
3f00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3f10: 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 OERR_CHECKRESERV
3f20: 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 EDLOCK (SQLITE_I
3f30: 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a OERR | (14<<8)).
3f40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3f50: 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 OERR_LOCK
3f60: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3f70: 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a OERR | (15<<8)).
3f80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3f90: 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 OERR_CLOSE
3fa0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3fb0: 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a OERR | (16<<8)).
3fc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3fd0: 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 OERR_DIR_CLOSE
3fe0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3ff0: 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a OERR | (17<<8)).
4000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
4010: 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 OCKED_SHAREDCACH
4020: 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c E (SQLITE_L
4030: 4f 43 4b 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 OCKED | (1<<8) )
4040: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
4050: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 : Flags For File
4060: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 Open Operations
4070: 20 7b 48 31 30 32 33 30 7d 20 3c 48 31 31 31 32 {H10230} <H1112
4080: 30 3e 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 0> <H12700>.**.*
4090: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 * These bit valu
40a0: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 es are intended
40b0: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a for use in the.*
40c0: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 * 3rd parameter
40d0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
40e0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 open_v2()] inter
40f0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 face and.** in t
4100: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
4110: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 to the xOpen me
4120: 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b thod of the.** [
4130: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
4140: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ect..*/.#define
4150: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
4160: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 ONLY 0x0
4170: 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 0000001 /* Ok f
4180: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
4190: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 v2() */.#define
41a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
41b0: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 WRITE 0x0
41c0: 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 0000002 /* Ok f
41d0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
41e0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 v2() */.#define
41f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
4200: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 TE 0x0
4210: 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 0000004 /* Ok f
4220: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
4230: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 v2() */.#define
4240: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
4250: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 TEONCLOSE 0x0
4260: 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 0000008 /* VFS
4270: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
4280: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
4290: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 USIVE 0x0
42a0: 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 0000010 /* VFS
42b0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
42c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e SQLITE_OPEN_MAIN
42d0: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 _DB 0x0
42e0: 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 0000100 /* VFS
42f0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
4300: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
4310: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 _DB 0x0
4320: 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 0000200 /* VFS
4330: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
4340: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e SQLITE_OPEN_TRAN
4350: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 SIENT_DB 0x0
4360: 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 0000400 /* VFS
4370: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
4380: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e SQLITE_OPEN_MAIN
4390: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 _JOURNAL 0x0
43a0: 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 0000800 /* VFS
43b0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
43c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
43d0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 _JOURNAL 0x0
43e0: 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 0001000 /* VFS
43f0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
4400: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a SQLITE_OPEN_SUBJ
4410: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 OURNAL 0x0
4420: 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 0002000 /* VFS
4430: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
4440: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 SQLITE_OPEN_MAST
4450: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 ER_JOURNAL 0x0
4460: 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 0004000 /* VFS
4470: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
4480: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
4490: 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 TEX 0x0
44a0: 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 0008000 /* Ok f
44b0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
44c0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 v2() */.#define
44d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c SQLITE_OPEN_FULL
44e0: 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 MUTEX 0x0
44f0: 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 0010000 /* Ok f
4500: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
4510: 76 32 28 29 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 v2() */../*.** C
4520: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 API3REF: Device
4530: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 Characteristics
4540: 7b 48 31 30 32 34 30 7d 20 3c 48 31 31 31 32 30 {H10240} <H11120
4550: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 >.**.** The xDev
4560: 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 iceCapabilities
4570: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 method of the [s
4580: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
4590: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 s].** object ret
45a0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 urns an integer
45b0: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f which is a vecto
45c0: 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a r of the these.*
45d0: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 * bit values exp
45e0: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 ressing I/O char
45f0: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 acteristics of t
4600: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a he mass storage.
4610: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 ** device that h
4620: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 olds the file th
4630: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f at the [sqlite3_
4640: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 io_methods].** r
4650: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 efers to..**.**
4660: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
4670: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
4680: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 means that all
4690: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 writes of.** any
46a0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 size are atomic
46b0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
46c0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 CAP_ATOMICnnn va
46d0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 lues.** mean tha
46e0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 t writes of bloc
46f0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 ks that are nnn
4700: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e bytes in size an
4710: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 d.** are aligned
4720: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 to an address w
4730: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 hich is an integ
4740: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a er multiple of.*
4750: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 * nnn are atomic
4760: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
4770: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
4780: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 value means.** t
4790: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 hat when data is
47a0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 appended to a f
47b0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 ile, the data is
47c0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 appended.** fir
47d0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 st then the size
47e0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 of the file is
47f0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 extended, never
4800: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 the other.** way
4810: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 around. The SQ
4820: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
4830: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d NTIAL property m
4840: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 eans that.** inf
4850: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 ormation is writ
4860: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 ten to disk in t
4870: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 he same order as
4880: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 calls.** to xWr
4890: 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e ite()..*/.#defin
48a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
48b0: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 TOMIC 0
48c0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e x00000001.#defin
48d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
48e0: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 TOMIC512 0
48f0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e x00000002.#defin
4900: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4910: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 TOMIC1K 0
4920: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e x00000004.#defin
4930: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4940: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 TOMIC2K 0
4950: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e x00000008.#defin
4960: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4970: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 TOMIC4K 0
4980: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e x00000010.#defin
4990: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
49a0: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 TOMIC8K 0
49b0: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e x00000020.#defin
49c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
49d0: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 TOMIC16K 0
49e0: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e x00000040.#defin
49f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4a00: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 TOMIC32K 0
4a10: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e x00000080.#defin
4a20: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4a30: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 TOMIC64K 0
4a40: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e x00000100.#defin
4a50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
4a60: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 AFE_APPEND 0
4a70: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e x00000200.#defin
4a80: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
4a90: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 EQUENTIAL 0
4aa0: 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a x00000400../*.**
4ab0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 CAPI3REF: File
4ac0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b Locking Levels {
4ad0: 48 31 30 32 35 30 7d 20 3c 48 31 31 31 32 30 3e H10250} <H11120>
4ae0: 20 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 <H11310>.**.**
4af0: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 SQLite uses one
4b00: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 of these integer
4b10: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 values as the s
4b20: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e econd.** argumen
4b30: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 t to calls it ma
4b40: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b kes to the xLock
4b50: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 () and xUnlock()
4b60: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 methods.** of a
4b70: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 n [sqlite3_io_me
4b80: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a thods] object..*
4b90: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4ba0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 _LOCK_NONE
4bb0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
4bc0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
4bd0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
4be0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 e SQLITE_LOCK_RE
4bf0: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 SERVED 2.#d
4c00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
4c10: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 K_PENDING
4c20: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
4c30: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 _LOCK_EXCLUSIVE
4c40: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 4../*.** CAP
4c50: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 I3REF: Synchroni
4c60: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 zation Type Flag
4c70: 73 20 7b 48 31 30 32 36 30 7d 20 3c 48 31 31 31 s {H10260} <H111
4c80: 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 20>.**.** When S
4c90: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 QLite invokes th
4ca0: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 e xSync() method
4cb0: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 of an.** [sqlit
4cc0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
4cd0: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 bject it uses a
4ce0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a combination of.*
4cf0: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 * these integer
4d00: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 values as the se
4d10: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a cond argument..*
4d20: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 *.** When the SQ
4d30: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e LITE_SYNC_DATAON
4d40: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c LY flag is used,
4d50: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 it means that t
4d60: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 he.** sync opera
4d70: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 tion only needs
4d80: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f to flush data to
4d90: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 mass storage.
4da0: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 Inode.** informa
4db0: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 tion need not be
4dc0: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 flushed. If the
4dd0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 lower four bits
4de0: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 of the flag.**
4df0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e equal SQLITE_SYN
4e00: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d C_NORMAL, that m
4e10: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d eans to use norm
4e20: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e al fsync() seman
4e30: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 tics..** If the
4e40: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 lower four bits
4e50: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e equal SQLITE_SYN
4e60: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 C_FULL, that mea
4e70: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 ns.** to use Mac
4e80: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c OS X style full
4e90: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 sync instead of
4ea0: 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 fsync()..*/.#def
4eb0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ine SQLITE_SYNC_
4ec0: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 NORMAL 0x
4ed0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 00002.#define SQ
4ee0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 LITE_SYNC_FULL
4ef0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 0x00003.
4f00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
4f10: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 YNC_DATAONLY
4f20: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 0x00010../*.**
4f30: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e CAPI3REF: OS In
4f40: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c terface Open Fil
4f50: 65 20 48 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 e Handle {H11110
4f60: 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a } <S20110>.**.**
4f70: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c An [sqlite3_fil
4f80: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 e] object repres
4f90: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c ents an open fil
4fa0: 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 e in the OS.** i
4fb0: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20 nterface layer.
4fc0: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 Individual OS i
4fd0: 6e 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 nterface impleme
4fe0: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a ntations will.**
4ff0: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 want to subclas
5000: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 s this object by
5010: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 appending addit
5020: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 ional fields.**
5030: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 for their own us
5040: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 e. The pMethods
5050: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e entry is a poin
5060: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 ter to an.** [sq
5070: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
5080: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 ] object that de
5090: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f fines methods fo
50a0: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 r performing.**
50b0: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f I/O operations o
50c0: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e n the open file.
50d0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
50e0: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 ct sqlite3_file
50f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 sqlite3_file;.st
5100: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c ruct sqlite3_fil
5110: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 e {. const stru
5120: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ct sqlite3_io_me
5130: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b thods *pMethods;
5140: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 /* Methods for
5150: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f an open file */
5160: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
5170: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
5180: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d e File Virtual M
5190: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 ethods Object {H
51a0: 31 31 31 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 11120} <S20110>.
51b0: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 **.** Every file
51c0: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b opened by the [
51d0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 sqlite3_vfs] xOp
51e0: 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 en method popula
51f0: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 tes an.** [sqlit
5200: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 e3_file] object
5210: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e (or, more common
5220: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f ly, a subclass o
5230: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
5240: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 3_file] object)
5250: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 with a pointer t
5260: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
5270: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a this object..**
5280: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 This object def
5290: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 ines the methods
52a0: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d used to perform
52b0: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 various operati
52c0: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 ons.** against t
52d0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 he open file rep
52e0: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 resented by the
52f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
5300: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 bject..**.** If
5310: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 the xOpen method
5320: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 sets the sqlite
5330: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 3_file.pMethods
5340: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 element .** to a
5350: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 non-NULL pointe
5360: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 r, then the sqli
5370: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 te3_io_methods.x
5380: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 Close method.**
5390: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 may be invoked e
53a0: 76 65 6e 20 69 66 20 74 68 65 20 78 4f 70 65 6e ven if the xOpen
53b0: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 reported that i
53c0: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a t failed. The.*
53d0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 * only way to pr
53e0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 event a call to
53f0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 xClose following
5400: 20 61 20 66 61 69 6c 65 64 20 78 4f 70 65 6e 0a a failed xOpen.
5410: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 78 4f ** is for the xO
5420: 70 65 6e 20 74 6f 20 73 65 74 20 74 68 65 20 73 pen to set the s
5430: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 qlite3_file.pMet
5440: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 74 6f 20 hods element to
5450: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 NULL..**.** The
5460: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 flags argument t
5470: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f o xSync may be o
5480: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 ne of [SQLITE_SY
5490: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a NC_NORMAL] or.**
54a0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 [SQLITE_SYNC_FU
54b0: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 LL]. The first
54c0: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f choice is the no
54d0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a rmal fsync()..**
54e0: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 The second choi
54f0: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 ce is a Mac OS X
5500: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e style fullsync.
5510: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 The [SQLITE_SY
5520: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 NC_DATAONLY].**
5530: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 flag may be ORed
5540: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 in to indicate
5550: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 that only the da
5560: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a ta of the file.*
5570: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e * and not its in
5580: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 ode needs to be
5590: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 synced..**.** Th
55a0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
55b0: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 to xLock() and
55c0: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e xUnlock() are on
55d0: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 e of.** <ul>.**
55e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
55f0: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e K_NONE],.** <li>
5600: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 [SQLITE_LOCK_SH
5610: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b ARED],.** <li> [
5620: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
5630: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b RVED],.** <li> [
5640: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 SQLITE_LOCK_PEND
5650: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e ING], or.** <li>
5660: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 [SQLITE_LOCK_EX
5670: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 CLUSIVE]..** </u
5680: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e l>.** xLock() in
5690: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b creases the lock
56a0: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 . xUnlock() decr
56b0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a eases the lock..
56c0: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 ** The xCheckRes
56d0: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 ervedLock() meth
56e0: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 od checks whethe
56f0: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 r any database c
5700: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 onnection,.** ei
5710: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f ther in this pro
5720: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 cess or in some
5730: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 other process, i
5740: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 s holding a RESE
5750: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 RVED,.** PENDING
5760: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c , or EXCLUSIVE l
5770: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e ock on the file.
5780: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 It returns tru
5790: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c e.** if such a l
57a0: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 ock exists and f
57b0: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a alse otherwise..
57c0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 **.** The xFileC
57d0: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 ontrol() method
57e0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 is a generic int
57f0: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f erface that allo
5800: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 ws custom.** VFS
5810: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
5820: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e to directly con
5830: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c trol an open fil
5840: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b e using the.** [
5850: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
5860: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 trol()] interfac
5870: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 e. The second "
5880: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 op" argument is
5890: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 an.** integer op
58a0: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 code. The third
58b0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 argument is a g
58c0: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 eneric pointer i
58d0: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f ntended to.** po
58e0: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 int to a structu
58f0: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 re that may cont
5900: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 ain arguments or
5910: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 space in which
5920: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 to.** write retu
5930: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 rn values. Pote
5940: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 ntial uses for x
5950: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 FileControl() mi
5960: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 ght be.** functi
5970: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c ons to enable bl
5980: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 ocking locks wit
5990: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 h timeouts, to c
59a0: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 hange the.** loc
59b0: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 king strategy (f
59c0: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 or example to us
59d0: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 e dot-file locks
59e0: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a ), to inquire.**
59f0: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 about the statu
5a00: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 s of a lock, or
5a10: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c to break stale l
5a20: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 ocks. The SQLit
5a30: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 e.** core reserv
5a40: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c es all opcodes l
5a50: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 ess than 100 for
5a60: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a its own use..**
5a70: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c A [SQLITE_FCNTL
5a80: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 _LOCKSTATE | lis
5a90: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 t of opcodes] le
5aa0: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 ss than 100 is a
5ab0: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 vailable..** App
5ac0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 lications that d
5ad0: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 efine a custom x
5ae0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
5af0: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 od should use op
5b00: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 codes.** greater
5b10: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f than 100 to avo
5b20: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a id conflicts..**
5b30: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 .** The xSectorS
5b40: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 ize() method ret
5b50: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 urns the sector
5b60: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 size of the.** d
5b70: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 evice that under
5b80: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 lies the file.
5b90: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 The sector size
5ba0: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 is the.** minimu
5bb0: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e m write that can
5bc0: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 be performed wi
5bd0: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 thout disturbing
5be0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 .** other bytes
5bf0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 in the file. Th
5c00: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 e xDeviceCharact
5c10: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 eristics().** me
5c20: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 thod returns a b
5c30: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 it vector descri
5c40: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f bing behaviors o
5c50: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 f the.** underly
5c60: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a ing device:.**.*
5c70: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
5c80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5c90: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 MIC].** <li> [SQ
5ca0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
5cb0: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C512].** <li> [S
5cc0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5cd0: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC1K].** <li> [S
5ce0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5cf0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC2K].** <li> [S
5d00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5d10: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC4K].** <li> [S
5d20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5d30: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC8K].** <li> [S
5d40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5d50: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC16K].** <li> [
5d60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5d70: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC32K].** <li>
5d80: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
5d90: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e OMIC64K].** <li>
5da0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 [SQLITE_IOCAP_S
5db0: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c AFE_APPEND].** <
5dc0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
5dd0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a P_SEQUENTIAL].**
5de0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 </ul>.**.** The
5df0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5e00: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 OMIC property me
5e10: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 ans that all wri
5e20: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 tes of.** any si
5e30: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 ze are atomic.
5e40: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
5e50: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 _ATOMICnnn value
5e60: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 s.** mean that w
5e70: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 rites of blocks
5e80: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 that are nnn byt
5e90: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a es in size and.*
5ea0: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f * are aligned to
5eb0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 an address whic
5ec0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 h is an integer
5ed0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e multiple of.** n
5ee0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 nn are atomic.
5ef0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
5f00: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c _SAFE_APPEND val
5f10: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 ue means.** that
5f20: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 when data is ap
5f30: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 pended to a file
5f40: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 , the data is ap
5f50: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 pended.** first
5f60: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 then the size of
5f70: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 the file is ext
5f80: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 ended, never the
5f90: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 other.** way ar
5fa0: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 ound. The SQLIT
5fb0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
5fc0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e AL property mean
5fd0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d s that.** inform
5fe0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e ation is written
5ff0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 to disk in the
6000: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 same order as ca
6010: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 lls.** to xWrite
6020: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 ()..**.** If xRe
6030: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c ad() returns SQL
6040: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f ITE_IOERR_SHORT_
6050: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 READ it must als
6060: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 o fill.** in the
6070: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 unread portions
6080: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 of the buffer w
6090: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 ith zeros. A VF
60a0: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 S that.** fails
60b0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f to zero-fill sho
60c0: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 rt reads might s
60d0: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f eem to work. Ho
60e0: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 wever,.** failur
60f0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 e to zero-fill s
6100: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 hort reads will
6110: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 eventually lead
6120: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 to.** database c
6130: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 orruption..*/.ty
6140: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
6150: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 ite3_io_methods
6160: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
6170: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 ds;.struct sqlit
6180: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a e3_io_methods {.
6190: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a int iVersion;.
61a0: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 int (*xClose)(
61b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a sqlite3_file*);.
61c0: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 int (*xRead)(s
61d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f qlite3_file*, vo
61e0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 id*, int iAmt, s
61f0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 qlite3_int64 iOf
6200: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 st);. int (*xWr
6210: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ite)(sqlite3_fil
6220: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c e*, const void*,
6230: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 int iAmt, sqlit
6240: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b e3_int64 iOfst);
6250: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 . int (*xTrunca
6260: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 te)(sqlite3_file
6270: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
6280: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a size);. int (*
6290: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 xSync)(sqlite3_f
62a0: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 ile*, int flags)
62b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 ;. int (*xFileS
62c0: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ize)(sqlite3_fil
62d0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
62e0: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 4 *pSize);. int
62f0: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 (*xLock)(sqlite
6300: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 3_file*, int);.
6310: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 int (*xUnlock)(
6320: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
6330: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 nt);. int (*xCh
6340: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 eckReservedLock)
6350: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
6360: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 int *pResOut);.
6370: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 int (*xFileCont
6380: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c rol)(sqlite3_fil
6390: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 e*, int op, void
63a0: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 *pArg);. int (
63b0: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 *xSectorSize)(sq
63c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 lite3_file*);.
63d0: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 int (*xDeviceCha
63e0: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 racteristics)(sq
63f0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 lite3_file*);.
6400: 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 /* Additional me
6410: 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 thods may be add
6420: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
6430: 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a eases */.};../*.
6440: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 ** CAPI3REF: Sta
6450: 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 ndard File Contr
6460: 6f 6c 20 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 ol Opcodes {H113
6470: 31 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 10} <S30800>.**.
6480: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 ** These integer
6490: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f constants are o
64a0: 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 pcodes for the x
64b0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
64c0: 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 od.** of the [sq
64d0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
64e0: 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 ] object and for
64f0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
6500: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a le_control()].**
6510: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
6520: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
6530: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f NTL_LOCKSTATE] o
6540: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f pcode is used fo
6550: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 r debugging. Th
6560: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 is.** opcode cau
6570: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e ses the xFileCon
6580: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 trol method to w
6590: 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 rite the current
65a0: 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 state of.** the
65b0: 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 lock (one of [S
65c0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d QLITE_LOCK_NONE]
65d0: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 , [SQLITE_LOCK_S
65e0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 HARED],.** [SQLI
65f0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 TE_LOCK_RESERVED
6600: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ], [SQLITE_LOCK_
6610: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 PENDING], or [SQ
6620: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 LITE_LOCK_EXCLUS
6630: 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e IVE]).** into an
6640: 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 integer that th
6650: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 e pArg argument
6660: 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 points to. This
6670: 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 capability.** is
6680: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 used during tes
6690: 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 ting and only ne
66a0: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 eds to be suppor
66b0: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f ted when SQLITE_
66c0: 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e TEST.** is defin
66d0: 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ed..*/.#define S
66e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b QLITE_FCNTL_LOCK
66f0: 53 54 41 54 45 20 20 20 20 20 20 20 20 31 0a 23 STATE 1.#
6700: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 define SQLITE_GE
6710: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 T_LOCKPROXYFILE
6720: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
6730: 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 QLITE_SET_LOCKPR
6740: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33 0a 23 OXYFILE 3.#
6750: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 define SQLITE_LA
6760: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 ST_ERRNO
6770: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 4../*.** CA
6780: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 PI3REF: Mutex Ha
6790: 6e 64 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 ndle {H17110} <S
67a0: 32 30 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20130>.**.** The
67b0: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 mutex module wi
67c0: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 thin SQLite defi
67d0: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 nes [sqlite3_mut
67e0: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 ex] to be an.**
67f0: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f abstract type fo
6800: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 r a mutex object
6810: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f . The SQLite co
6820: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a re never looks.*
6830: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 * at the interna
6840: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e l representation
6850: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f of an [sqlite3_
6860: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 mutex]. It only
6870: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 .** deals with p
6880: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b ointers to the [
6890: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f sqlite3_mutex] o
68a0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 bject..**.** Mut
68b0: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 exes are created
68c0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
68d0: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a mutex_alloc()]..
68e0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
68f0: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 t sqlite3_mutex
6900: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a sqlite3_mutex;..
6910: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
6920: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a OS Interface Obj
6930: 65 63 74 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 ect {H11140} <S2
6940: 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 0100>.**.** An i
6950: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 nstance of the s
6960: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 qlite3_vfs objec
6970: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e t defines the in
6980: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a terface between.
6990: 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f ** the SQLite co
69a0: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 re and the under
69b0: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 lying operating
69c0: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 system. The "vf
69d0: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d s".** in the nam
69e0: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 e of the object
69f0: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 stands for "virt
6a00: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 ual file system"
6a10: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 ..**.** The valu
6a20: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f e of the iVersio
6a30: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 n field is initi
6a40: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 ally 1 but may b
6a50: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 e larger in.** f
6a60: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
6a70: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 f SQLite. Addit
6a80: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 ional fields may
6a90: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 be appended to
6aa0: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 this.** object w
6ab0: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e hen the iVersion
6ac0: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 value is increa
6ad0: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 sed. Note that
6ae0: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a the structure.**
6af0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
6b00: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 vfs object chang
6b10: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 es in the transa
6b20: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a ction between.**
6b30: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
6b40: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 3.5.9 and 3.6.0
6b50: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 and yet the iVer
6b60: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e sion field was n
6b70: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a ot.** modified..
6b80: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 **.** The szOsFi
6b90: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 le field is the
6ba0: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 size of the subc
6bb0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f lassed [sqlite3_
6bc0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 file].** structu
6bd0: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 re used by this
6be0: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 VFS. mxPathname
6bf0: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 is the maximum
6c00: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 length of.** a p
6c10: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 athname in this
6c20: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 VFS..**.** Regis
6c30: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 tered sqlite3_vf
6c40: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 s objects are ke
6c50: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c pt on a linked l
6c60: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a ist formed by.**
6c70: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 the pNext point
6c80: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 er. The [sqlite
6c90: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 3_vfs_register()
6ca0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
6cb0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 3_vfs_unregister
6cc0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d ()] interfaces m
6cd0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a anage this list.
6ce0: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 ** in a thread-s
6cf0: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 afe way. The [s
6d00: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 qlite3_vfs_find(
6d10: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 )] interface.**
6d20: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 searches the lis
6d30: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 t. Neither the
6d40: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 application code
6d50: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 nor the VFS.**
6d60: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 implementation s
6d70: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e hould use the pN
6d80: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ext pointer..**.
6d90: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 ** The pNext fie
6da0: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 ld is the only f
6db0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 ield in the sqli
6dc0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 te3_vfs.** struc
6dd0: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 ture that SQLite
6de0: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 will ever modif
6df0: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 y. SQLite will
6e00: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f only access.** o
6e10: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 r modify this fi
6e20: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e eld while holdin
6e30: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 g a particular s
6e40: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 tatic mutex..**
6e50: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
6e60: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 should never mod
6e70: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 ify anything wit
6e80: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f hin the sqlite3_
6e90: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e vfs.** object on
6ea0: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 ce the object ha
6eb0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 s been registere
6ec0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 d..**.** The zNa
6ed0: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 me field holds t
6ee0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 he name of the V
6ef0: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 FS module. The
6f00: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 name must.** be
6f10: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c unique across al
6f20: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a l VFS modules..*
6f30: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c *.** SQLite will
6f40: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 guarantee that
6f50: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 the zFilename pa
6f60: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e rameter to xOpen
6f70: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 .** is either a
6f80: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 NULL pointer or
6f90: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a string obtained.
6fa0: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 ** from xFullPat
6fb0: 68 6e 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 hname(). SQLite
6fc0: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 further guarant
6fd0: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ees that.** the
6fe0: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 string will be v
6ff0: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 alid and unchang
7000: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 ed until xClose(
7010: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 ) is.** called.
7020: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 Because of the p
7030: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 revious sentence
7040: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 ,.** the [sqlite
7050: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 3_file] can safe
7060: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 ly store a point
7070: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c er to the.** fil
7080: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 ename if it need
7090: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 s to remember th
70a0: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 e filename for s
70b0: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 ome reason..** I
70c0: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 f the zFilename
70d0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 parameter is xOp
70e0: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 en is a NULL poi
70f0: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a nter then xOpen.
7100: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 ** must invent i
7110: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 ts own temporary
7120: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 name for the fi
7130: 6c 65 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 le. Whenever th
7140: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 e .** xFilename
7150: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c parameter is NUL
7160: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 L it will also b
7170: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 e the case that
7180: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 the.** flags par
7190: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c ameter will incl
71a0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ude [SQLITE_OPEN
71b0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e _DELETEONCLOSE].
71c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 .**.** The flags
71d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 argument to xOp
71e0: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c en() includes al
71f0: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a l bits set in.**
7200: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d the flags argum
7210: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ent to [sqlite3_
7220: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 open_v2()]. Or
7230: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e if [sqlite3_open
7240: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 ()].** or [sqlit
7250: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 e3_open16()] is
7260: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 used, then flags
7270: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 includes at lea
7280: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 st.** [SQLITE_OP
7290: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 EN_READWRITE] |
72a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 [SQLITE_OPEN_CRE
72b0: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 ATE]. .** If xOp
72c0: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c en() opens a fil
72d0: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e e read-only then
72e0: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c it sets *pOutFl
72f0: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 ags to.** includ
7300: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 e [SQLITE_OPEN_R
7310: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 EADONLY]. Other
7320: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c bits in *pOutFl
7330: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a ags may be set..
7340: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c **.** SQLite wil
7350: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f l also add one o
7360: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
7370: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 flags to the xOp
7380: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 en().** call, de
7390: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f pending on the o
73a0: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e bject being open
73b0: 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a ed:.**.** <ul>.*
73c0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
73d0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a OPEN_MAIN_DB].**
73e0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
73f0: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c PEN_MAIN_JOURNAL
7400: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
7410: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d TE_OPEN_TEMP_DB]
7420: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
7430: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 E_OPEN_TEMP_JOUR
7440: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
7450: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 QLITE_OPEN_TRANS
7460: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e IENT_DB].** <li>
7470: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 [SQLITE_OPEN_S
7480: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c UBJOURNAL].** <l
7490: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
74a0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d _MASTER_JOURNAL]
74b0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
74c0: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 The file I/O imp
74d0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 lementation can
74e0: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 use the object t
74f0: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 ype flags to.**
7500: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 change the way i
7510: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c t deals with fil
7520: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 es. For example
7530: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
7540: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f .** that does no
7550: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 t care about cra
7560: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 sh recovery or r
7570: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 ollback might ma
7580: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f ke.** the open o
7590: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 f a journal file
75a0: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 a no-op. Write
75b0: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 s to this journa
75c0: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 l would.** also
75d0: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 be no-ops, and a
75e0: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 ny attempt to re
75f0: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 ad the journal w
7600: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 ould return.** S
7610: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 QLITE_IOERR. Or
7620: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
7630: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e ion might recogn
7640: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 ize that a datab
7650: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c ase.** file will
7660: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 be doing page-a
7670: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 ligned sector re
7680: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 ads and writes i
7690: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 n a random.** or
76a0: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 der and set up i
76b0: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d ts I/O subsystem
76c0: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a accordingly..**
76d0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 .** SQLite might
76e0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 also add one of
76f0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 the following f
7700: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 lags to the xOpe
7710: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 n method:.**.**
7720: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
7730: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
7740: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e ONCLOSE].** <li>
7750: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 [SQLITE_OPEN_EX
7760: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c CLUSIVE].** </ul
7770: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c >.**.** The [SQL
7780: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
7790: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 NCLOSE] flag mea
77a0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 ns the file shou
77b0: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 ld be.** deleted
77c0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 when it is clos
77d0: 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 ed. The [SQLITE
77e0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
77f0: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 OSE].** will be
7800: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 set for TEMP da
7810: 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c tabases, journal
7820: 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 s and for subjou
7830: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 rnals..**.** The
7840: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 [SQLITE_OPEN_EX
7850: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 CLUSIVE] flag is
7860: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 always used in
7870: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 conjunction.** w
7880: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
7890: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 OPEN_CREATE] fla
78a0: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 g, which are bot
78b0: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e h directly.** an
78c0: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f alogous to the O
78d0: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 _EXCL and O_CREA
78e0: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 T flags of the P
78f0: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 OSIX open().** A
7900: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f PI. The SQLITE_
7910: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 OPEN_EXCLUSIVE f
7920: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 lag, when paired
7930: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 with the .** SQ
7940: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
7950: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 , is used to ind
7960: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 icate that file
7970: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a should always.**
7980: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 be created, and
7990: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 that it is an e
79a0: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 rror if it alrea
79b0: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 dy exists..** It
79c0: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 is <i>not</i> u
79d0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 sed to indicate
79e0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 the file should
79f0: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f be opened .** fo
7a00: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 r exclusive acce
7a10: 73 73 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 ss..**.** At lea
7a20: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 st szOsFile byte
7a30: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 s of memory are
7a40: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c allocated by SQL
7a50: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 ite.** to hold t
7a60: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c he [sqlite3_fil
7a70: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 e] structure pas
7a80: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 sed as the third
7a90: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 .** argument to
7aa0: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 xOpen. The xOpe
7ab0: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f n method does no
7ac0: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c t have to.** all
7ad0: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 ocate the struct
7ae0: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a ure; it should j
7af0: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 ust fill it in.
7b00: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 Note that.** th
7b10: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d e xOpen method m
7b20: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 ust set the sqli
7b30: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
7b40: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 s to either.** a
7b50: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f valid [sqlite3_
7b60: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
7b70: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 ct or to NULL.
7b80: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a xOpen must do.**
7b90: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 this even if th
7ba0: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 e open fails. S
7bb0: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 QLite expects th
7bc0: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 at the sqlite3_f
7bd0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 ile.pMethods.**
7be0: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 element will be
7bf0: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 valid after xOpe
7c00: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 n returns regard
7c10: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 less of the succ
7c20: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 ess.** or failur
7c30: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 e of the xOpen c
7c40: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 all..**.** The f
7c50: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f lags argument to
7c60: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 xAccess() may b
7c70: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 e [SQLITE_ACCESS
7c80: 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 _EXISTS].** to t
7c90: 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 est for the exis
7ca0: 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c tence of a file,
7cb0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 or [SQLITE_ACCE
7cc0: 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f SS_READWRITE] to
7cd0: 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 .** test whether
7ce0: 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 a file is reada
7cf0: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 ble and writable
7d00: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 , or [SQLITE_ACC
7d10: 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 ESS_READ].** to
7d20: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 test whether a f
7d30: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 ile is at least
7d40: 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 readable. The
7d50: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a file can be a.**
7d60: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a directory..**.*
7d70: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c * SQLite will al
7d80: 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 ways allocate at
7d90: 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d least mxPathnam
7da0: 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 e+1 bytes for th
7db0: 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 e.** output buff
7dc0: 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 er xFullPathname
7dd0: 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a . The exact siz
7de0: 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 e of the output
7df0: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 buffer.** is als
7e00: 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 o passed as a pa
7e10: 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 rameter to both
7e20: 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 methods. If the
7e30: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a output buffer.*
7e40: 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 * is not large e
7e50: 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 nough, [SQLITE_C
7e60: 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 ANTOPEN] should
7e70: 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e be returned. Sin
7e80: 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 ce this is.** ha
7e90: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c ndled as a fatal
7ea0: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 error by SQLite
7eb0: 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 , vfs implementa
7ec0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 tions should end
7ed0: 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 eavor.** to prev
7ee0: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 ent this by sett
7ef0: 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 ing mxPathname t
7f00: 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 o a sufficiently
7f10: 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a large value..**
7f20: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e .** The xRandomn
7f30: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c ess(), xSleep(),
7f40: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d and xCurrentTim
7f50: 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a e() interfaces.*
7f60: 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 * are not strict
7f70: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 ly a part of the
7f80: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 filesystem, but
7f90: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 they are.** inc
7fa0: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 luded in the VFS
7fb0: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 structure for c
7fc0: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 ompleteness..**
7fd0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 The xRandomness(
7fe0: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d ) function attem
7ff0: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 pts to return nB
8000: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 ytes bytes.** of
8010: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 good-quality ra
8020: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f ndomness into zO
8030: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 ut. The return
8040: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 value is.** the
8050: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 actual number of
8060: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d bytes of random
8070: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a ness obtained..*
8080: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d * The xSleep() m
8090: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 ethod causes the
80a0: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 calling thread
80b0: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a to sleep for at.
80c0: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d ** least the num
80d0: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f ber of microseco
80e0: 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 nds given. The
80f0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a xCurrentTime().*
8100: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 * method returns
8110: 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 a Julian Day Nu
8120: 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 mber for the cur
8130: 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 rent date and ti
8140: 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 me..**.*/.typede
8150: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
8160: 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 _vfs sqlite3_vfs
8170: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
8180: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 _vfs {. int iVe
8190: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 rsion;
81a0: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 /* Structure v
81b0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f ersion number */
81c0: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b . int szOsFile;
81d0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
81e0: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 ize of subclasse
81f0: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a d sqlite3_file *
8200: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 /. int mxPathna
8210: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 me; /*
8220: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 Maximum file pat
8230: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a hname length */.
8240: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 sqlite3_vfs *p
8250: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 Next; /* Ne
8260: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 xt registered VF
8270: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 S */. const cha
8280: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 r *zName;
8290: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 /* Name of this
82a0: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 virtual file sys
82b0: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 tem */. void *p
82c0: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 AppData;
82d0: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 /* Pointer to
82e0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 application-spec
82f0: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 ific data */. i
8300: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 nt (*xOpen)(sqli
8310: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
8320: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c char *zName, sql
8330: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 ite3_file*,.
8340: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 int f
8350: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 lags, int *pOutF
8360: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 lags);. int (*x
8370: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f Delete)(sqlite3_
8380: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
8390: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e *zName, int syn
83a0: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 cDir);. int (*x
83b0: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f Access)(sqlite3_
83c0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
83d0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 *zName, int fla
83e0: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 gs, int *pResOut
83f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c );. int (*xFull
8400: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 Pathname)(sqlite
8410: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
8420: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e ar *zName, int n
8430: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 Out, char *zOut)
8440: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f ;. void *(*xDlO
8450: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 pen)(sqlite3_vfs
8460: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
8470: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 Filename);. voi
8480: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 d (*xDlError)(sq
8490: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 lite3_vfs*, int
84a0: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 nByte, char *zEr
84b0: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a rMsg);. void (*
84c0: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 (*xDlSym)(sqlite
84d0: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 3_vfs*,void*, co
84e0: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f nst char *zSymbo
84f0: 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 l))(void);. voi
8500: 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 d (*xDlClose)(sq
8510: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 lite3_vfs*, void
8520: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e *);. int (*xRan
8530: 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 domness)(sqlite3
8540: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 _vfs*, int nByte
8550: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 , char *zOut);.
8560: 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 int (*xSleep)(s
8570: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 qlite3_vfs*, int
8580: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a microseconds);.
8590: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 int (*xCurrent
85a0: 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 Time)(sqlite3_vf
85b0: 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 s*, double*);.
85c0: 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 int (*xGetLastEr
85d0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ror)(sqlite3_vfs
85e0: 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b *, int, char *);
85f0: 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 . /* New fields
8600: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 may be appended
8610: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 in figure versi
8620: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 ons. The iVersi
8630: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 on. ** value wi
8640: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 ll increment whe
8650: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 never this happe
8660: 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a ns. */.};../*.**
8670: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 CAPI3REF: Flags
8680: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 for the xAccess
8690: 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 48 31 31 VFS method {H11
86a0: 31 39 30 7d 20 3c 48 31 31 31 34 30 3e 0a 2a 2a 190} <H11140>.**
86b0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 .** These intege
86c0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 r constants can
86d0: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 be used as the t
86e0: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
86f0: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 o.** the xAccess
8700: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 method of an [s
8710: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
8720: 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 ct. {END} They
8730: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 determine.** wha
8740: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 t kind of permis
8750: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 sions the xAcces
8760: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b s method is look
8770: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 ing for..** With
8780: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 SQLITE_ACCESS_E
8790: 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 XISTS, the xAcce
87a0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d ss method.** sim
87b0: 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 ply checks wheth
87c0: 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 er the file exis
87d0: 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 ts..** With SQLI
87e0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 TE_ACCESS_READWR
87f0: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 ITE, the xAccess
8800: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b method.** check
8810: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 s whether the fi
8820: 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 le is both reada
8830: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 ble and writable
8840: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 ..** With SQLITE
8850: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 _ACCESS_READ, th
8860: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
8870: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 .** checks wheth
8880: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 er the file is r
8890: 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 eadable..*/.#def
88a0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ine SQLITE_ACCES
88b0: 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 S_EXISTS 0.#d
88c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 efine SQLITE_ACC
88d0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a ESS_READWRITE 1.
88e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
88f0: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 CCESS_READ
8900: 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 2../*.** CAPI3RE
8910: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 F: Initialize Th
8920: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 e SQLite Library
8930: 20 7b 48 31 30 31 33 30 7d 20 3c 53 32 30 30 30 {H10130} <S2000
8940: 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 0><S30100>.**.**
8950: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 The sqlite3_ini
8960: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e tialize() routin
8970: 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 e initializes th
8980: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 e.** SQLite libr
8990: 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ary. The sqlite
89a0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 3_shutdown() rou
89b0: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 tine.** dealloca
89c0: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 tes any resource
89d0: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f s that were allo
89e0: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 cated by sqlite3
89f0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a _initialize()..*
8a00: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 *.** A call to s
8a10: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
8a20: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 e() is an "effec
8a30: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 tive" call if it
8a40: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 is.** the first
8a50: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e time sqlite3_in
8a60: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e itialize() is in
8a70: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 voked during the
8a80: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 lifetime of.**
8a90: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 the process, or
8aa0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 if it is the fir
8ab0: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f st time sqlite3_
8ac0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
8ad0: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f invoked.** follo
8ae0: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 wing a call to s
8af0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
8b00: 29 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 ). Only an effe
8b10: 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 ctive call.** of
8b20: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
8b30: 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 ize() does any i
8b40: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 nitialization.
8b50: 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a All other calls.
8b60: 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 ** are harmless
8b70: 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 no-ops..**.** A
8b80: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
8b90: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e shutdown() is an
8ba0: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c "effective" cal
8bb0: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 l if it is the f
8bc0: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 irst.** call to
8bd0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
8be0: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 () since the las
8bf0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 t sqlite3_initia
8c00: 6c 69 7a 65 28 29 2e 20 20 4f 6e 6c 79 0a 2a 2a lize(). Only.**
8c10: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 an effective ca
8c20: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
8c30: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e utdown() does an
8c40: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 y deinitializati
8c50: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 on..** All other
8c60: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
8c70: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 3_shutdown() are
8c80: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 harmless no-ops
8c90: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 ..**.** Among ot
8ca0: 68 65 72 20 74 68 69 6e 67 73 2c 20 73 71 6c 69 her things, sqli
8cb0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
8cc0: 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a shall invoke.**
8cd0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
8ce0: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 (). Similarly,
8cf0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
8d00: 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e 76 6f ().** shall invo
8d10: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e ke sqlite3_os_en
8d20: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 d()..**.** The s
8d30: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
8d40: 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 e() routine retu
8d50: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 rns [SQLITE_OK]
8d60: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49 on success..** I
8d70: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f f for some reaso
8d80: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 n, sqlite3_initi
8d90: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c alize() is unabl
8da0: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a e to initialize.
8db0: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 ** the library (
8dc0: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e perhaps it is un
8dd0: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 able to allocate
8de0: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 a needed resour
8df0: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 ce such.** as a
8e00: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e mutex) it return
8e10: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 s an [error code
8e20: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 ] other than [SQ
8e30: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 LITE_OK]..**.**
8e40: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
8e50: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 ialize() routine
8e60: 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 is called inter
8e70: 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 nally by many ot
8e80: 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e her.** SQLite in
8e90: 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 terfaces so that
8ea0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
8eb0: 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 usually does not
8ec0: 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f need to.** invo
8ed0: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ke sqlite3_initi
8ee0: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 alize() directly
8ef0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 . For example,
8f00: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
8f10: 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 .** calls sqlite
8f20: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 3_initialize() s
8f30: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 o the SQLite lib
8f40: 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 rary will be aut
8f50: 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e omatically.** in
8f60: 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b itialized when [
8f70: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 sqlite3_open()]
8f80: 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 is called if it
8f90: 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 has not be initi
8fa0: 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 alized.** alread
8fb0: 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20 y. However, if
8fc0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
8fd0: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c ed with the [SQL
8fe0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 ITE_OMIT_AUTOINI
8ff0: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 T].** compile-ti
9000: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 me option, then
9010: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 the automatic ca
9020: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 lls to sqlite3_i
9030: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 nitialize().** a
9040: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 re omitted and t
9050: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
9060: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 ust call sqlite3
9070: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 _initialize() di
9080: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 rectly.** prior
9090: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 to using any oth
90a0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
90b0: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 ace. For maximu
90c0: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a m portability,.*
90d0: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e * it is recommen
90e0: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 ded that applica
90f0: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 tions always inv
9100: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 oke sqlite3_init
9110: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 ialize().** dire
9120: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 ctly prior to us
9130: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 ing any other SQ
9140: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 Lite interface.
9150: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 Future releases
9160: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 .** of SQLite ma
9170: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 y require this.
9180: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
9190: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 the behavior ex
91a0: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 hibited.** when
91b0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
91c0: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f ed with [SQLITE_
91d0: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d OMIT_AUTOINIT] m
91e0: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a ight become the.
91f0: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 ** default behav
9200: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 ior in some futu
9210: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 re release of SQ
9220: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Lite..**.** The
9230: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
9240: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f ) routine does o
9250: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 perating-system
9260: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 specific.** init
9270: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 ialization of th
9280: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
9290: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f . The sqlite3_o
92a0: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 s_end().** routi
92b0: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 ne undoes the ef
92c0: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f fect of sqlite3_
92d0: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 os_init(). Typi
92e0: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 cal tasks.** per
92f0: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 formed by these
9300: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 routines include
9310: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 allocation or d
9320: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f eallocation.** o
9330: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 f static resourc
9340: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 es, initializati
9350: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 on of global var
9360: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 iables,.** setti
9370: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 ng up a default
9380: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f [sqlite3_vfs] mo
9390: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 dule, or setting
93a0: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 up.** a default
93b0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 configuration u
93c0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f sing [sqlite3_co
93d0: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 nfig()]..**.** T
93e0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
93f0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f hould never invo
9400: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 ke either sqlite
9410: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 3_os_init().** o
9420: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 r sqlite3_os_end
9430: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 () directly. Th
9440: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
9450: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 ould only invoke
9460: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 .** sqlite3_init
9470: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c ialize() and sql
9480: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e ite3_shutdown().
9490: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 The sqlite3_os
94a0: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 _init().** inter
94b0: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 face is called a
94c0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 utomatically by
94d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
94e0: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 ze() and.** sqli
94f0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 te3_os_end() is
9500: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 called by sqlite
9510: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 3_shutdown(). A
9520: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d ppropriate.** im
9530: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f plementations fo
9540: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 r sqlite3_os_ini
9550: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t() and sqlite3_
9560: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 os_end().** are
9570: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 built into SQLit
9580: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d e when it is com
9590: 70 69 6c 65 64 20 66 6f 72 20 75 6e 69 78 2c 20 piled for unix,
95a0: 77 69 6e 64 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 windows, or os/2
95b0: 2e 0a 2a 2a 20 57 68 65 6e 20 62 75 69 6c 74 20 ..** When built
95c0: 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f for other platfo
95d0: 72 6d 73 20 28 75 73 69 6e 67 20 74 68 65 20 5b rms (using the [
95e0: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d SQLITE_OS_OTHER=
95f0: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 1] compile-time.
9600: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 ** option) the a
9610: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
9620: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c supply a suitabl
9630: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
9640: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
9650: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 os_init() and sq
9660: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 lite3_os_end().
9670: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d An application-
9680: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c supplied.** impl
9690: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 ementation of sq
96a0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
96b0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e or sqlite3_os_en
96c0: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 d().** must retu
96d0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f rn [SQLITE_OK] o
96e0: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f n success and so
96f0: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 me other [error
9700: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 code] upon.** fa
9710: 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ilure..*/.int sq
9720: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
9730: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 (void);.int sqli
9740: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 te3_shutdown(voi
9750: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f d);.int sqlite3_
9760: 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 os_init(void);.i
9770: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e nt sqlite3_os_en
9780: 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 d(void);../*.**
9790: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
97a0: 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 uring The SQLite
97b0: 20 4c 69 62 72 61 72 79 20 7b 48 31 34 31 30 30 Library {H14100
97c0: 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 32 30 } <S20000><S3020
97d0: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
97e0: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c AL.**.** The sql
97f0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e ite3_config() in
9800: 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
9810: 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 to make global c
9820: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 onfiguration.**
9830: 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 changes to SQLit
9840: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 e in order to tu
9850: 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 ne SQLite to the
9860: 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 specific needs
9870: 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 of.** the applic
9880: 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 ation. The defa
9890: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ult configuratio
98a0: 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 n is recommended
98b0: 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 for most.** app
98c0: 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f lications and so
98d0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
98e0: 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 usually not nec
98f0: 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a essary. It is.*
9900: 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 * provided to su
9910: 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 pport rare appli
9920: 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 cations with unu
9930: 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a sual needs..**.*
9940: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
9950: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 nfig() interface
9960: 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 is not threadsa
9970: 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 fe. The applica
9980: 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 tion.** must ins
9990: 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 ure that no othe
99a0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
99b0: 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 ces are invoked
99c0: 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 by other.** thre
99d0: 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 ads while sqlite
99e0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 3_config() is ru
99f0: 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d nning. Furtherm
9a00: 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e ore, sqlite3_con
9a10: 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c fig().** may onl
9a20: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 y be invoked pri
9a30: 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e or to library in
9a40: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 itialization usi
9a50: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 ng.** [sqlite3_i
9a60: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 nitialize()] or
9a70: 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 after shutdown b
9a80: 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 y [sqlite3_shutd
9a90: 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65 2c own()]..** Note,
9aa0: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 73 however, that s
9ab0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
9ac0: 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 can be called as
9ad0: 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 part of the.**
9ae0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
9af0: 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
9b00: 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 -defined [sqlite
9b10: 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 3_os_init()]..**
9b20: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
9b30: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
9b40: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 3_config() is an
9b50: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c integer.** [SQL
9b60: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c ITE_CONFIG_SINGL
9b70: 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 ETHREAD | config
9b80: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 uration option]
9b90: 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a that determines.
9ba0: 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 ** what property
9bb0: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f of SQLite is to
9bc0: 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 be configured.
9bd0: 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 Subsequent argu
9be0: 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 ments.** vary de
9bf0: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b pending on the [
9c00: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
9c10: 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e NGLETHREAD | con
9c20: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
9c30: 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 n].** in the fir
9c40: 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a st argument..**.
9c50: 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 ** When a config
9c60: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 uration option i
9c70: 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 s set, sqlite3_c
9c80: 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 onfig() returns
9c90: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 [SQLITE_OK]..**
9ca0: 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 If the option is
9cb0: 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 unknown or SQLi
9cc0: 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 te is unable to
9cd0: 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a set the option.*
9ce0: 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 * then this rout
9cf0: 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f ine returns a no
9d00: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f n-zero [error co
9d10: 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 de]..**.** Requi
9d20: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 rements:.** [H14
9d30: 31 30 33 5d 20 5b 48 31 34 31 30 36 5d 20 5b 48 103] [H14106] [H
9d40: 31 34 31 32 30 5d 20 5b 48 31 34 31 32 33 5d 20 14120] [H14123]
9d50: 5b 48 31 34 31 32 36 5d 20 5b 48 31 34 31 32 39 [H14126] [H14129
9d60: 5d 20 5b 48 31 34 31 33 32 5d 20 5b 48 31 34 31 ] [H14132] [H141
9d70: 33 35 5d 0a 2a 2a 20 5b 48 31 34 31 33 38 5d 20 35].** [H14138]
9d80: 5b 48 31 34 31 34 31 5d 20 5b 48 31 34 31 34 34 [H14141] [H14144
9d90: 5d 20 5b 48 31 34 31 34 37 5d 20 5b 48 31 34 31 ] [H14147] [H141
9da0: 35 30 5d 20 5b 48 31 34 31 35 33 5d 20 5b 48 31 50] [H14153] [H1
9db0: 34 31 35 36 5d 20 5b 48 31 34 31 35 39 5d 0a 2a 4156] [H14159].*
9dc0: 2a 20 5b 48 31 34 31 36 32 5d 20 5b 48 31 34 31 * [H14162] [H141
9dd0: 36 35 5d 20 5b 48 31 34 31 36 38 5d 0a 2a 2f 0a 65] [H14168].*/.
9de0: 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e SQLITE_EXPERIMEN
9df0: 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TAL int sqlite3_
9e00: 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 config(int, ...)
9e10: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
9e20: 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 F: Configure dat
9e30: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
9e40: 73 20 20 7b 48 31 34 32 30 30 7d 20 3c 53 32 30 s {H14200} <S20
9e50: 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 000>.** EXPERIME
9e60: 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 NTAL.**.** The s
9e70: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
9e80: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
9e90: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e used to make con
9ea0: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 figuration.** ch
9eb0: 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 anges to a [data
9ec0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
9ed0: 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 . The interface
9ee0: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a is similar to.*
9ef0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
9f00: 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 g()] except that
9f10: 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 the changes app
9f20: 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a ly to a single.*
9f30: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
9f40: 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 ection] (specifi
9f50: 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ed in the first
9f60: 61 72 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a argument). The.
9f70: 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f ** sqlite3_db_co
9f80: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 nfig() interface
9f90: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 can only be use
9fa0: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 d immediately af
9fb0: 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 ter.** the datab
9fc0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
9fd0: 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 s created using
9fe0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
9ff0: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ,.** [sqlite3_op
a000: 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c en16()], or [sql
a010: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e ite3_open_v2()].
a020: 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 .**.** The sec
a030: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
a040: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
a050: 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 g(D,V,...) is t
a060: 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 he.** configurat
a070: 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69 6e ion verb - an in
a080: 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 teger code that
a090: 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a 2a indicates what.*
a0a0: 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 * aspect of the
a0b0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
a0c0: 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 tion] is being c
a0d0: 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68 onfigured..** Th
a0e0: 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f e only choice fo
a0f0: 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73 20 r this value is
a100: 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 [SQLITE_DBCONFIG
a110: 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 _LOOKASIDE]..**
a120: 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c 69 New verbs are li
a130: 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65 64 kely to be added
a140: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
a150: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ses of SQLite..*
a160: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 * Additional arg
a170: 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e uments depend on
a180: 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a the verb..**.**
a190: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
a1a0: 2a 20 5b 48 31 34 32 30 33 5d 20 5b 48 31 34 32 * [H14203] [H142
a1b0: 30 36 5d 20 5b 48 31 34 32 30 39 5d 20 5b 48 31 06] [H14209] [H1
a1c0: 34 32 31 32 5d 20 5b 48 31 34 32 31 35 5d 0a 2a 4212] [H14215].*
a1d0: 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d /.SQLITE_EXPERIM
a1e0: 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 ENTAL int sqlite
a1f0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 3_db_config(sqli
a200: 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e te3*, int op, ..
a210: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
a220: 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f REF: Memory Allo
a230: 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 cation Routines
a240: 7b 48 31 30 31 35 35 7d 20 3c 53 32 30 31 32 30 {H10155} <S20120
a250: 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
a260: 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 L.**.** An insta
a270: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
a280: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 ct defines the i
a290: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e nterface between
a2a0: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c SQLite.** and l
a2b0: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 ow-level memory
a2c0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 allocation routi
a2d0: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 nes..**.** This
a2e0: 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 object is used i
a2f0: 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 n only one place
a300: 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 in the SQLite i
a310: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 nterface..** A p
a320: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
a330: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
a340: 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 ject is the argu
a350: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 ment to.** [sqli
a360: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 te3_config()] wh
a370: 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 en the configura
a380: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a tion option is.*
a390: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
a3a0: 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 _MALLOC]. By cr
a3b0: 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e eating an instan
a3c0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
a3d0: 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 t.** and passing
a3e0: 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f it to [sqlite3_
a3f0: 63 6f 6e 66 69 67 28 29 5d 20 64 75 72 69 6e 67 config()] during
a400: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 configuration,
a410: 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f an.** applicatio
a420: 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e n can specify an
a430: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d alternative mem
a440: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 ory allocation s
a450: 75 62 73 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 ubsystem.** for
a460: 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f SQLite to use fo
a470: 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e r all of its dyn
a480: 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 amic memory need
a490: 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 s..**.** Note th
a4a0: 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 at SQLite comes
a4b0: 77 69 74 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 with a built-in
a4c0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
a4d0: 20 74 68 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 that is.** perf
a4e0: 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 ectly adequate f
a4f0: 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d or the overwhelm
a500: 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 ing majority of
a510: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 applications.**
a520: 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 and that this ob
a530: 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 ject is only use
a540: 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 ful to a tiny mi
a550: 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 nority of applic
a560: 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 ations.** with s
a570: 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 pecialized memor
a580: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 y allocation req
a590: 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 uirements. This
a5a0: 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c object is.** al
a5b0: 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 so used during t
a5c0: 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 esting of SQLite
a5d0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 in order to spe
a5e0: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 cify an alternat
a5f0: 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c ive.** memory al
a600: 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d locator that sim
a610: 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 ulates memory ou
a620: 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 t-of-memory cond
a630: 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 itions in.** ord
a640: 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 er to verify tha
a650: 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 t SQLite recover
a660: 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f s gracefully fro
a670: 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 m such.** condit
a680: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ions..**.** The
a690: 78 4d 61 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 xMalloc, xFree,
a6a0: 61 6e 64 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 and xRealloc met
a6b0: 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c hods must work l
a6c0: 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f ike the.** mallo
a6d0: 63 28 29 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 c(), free(), and
a6e0: 20 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 realloc() funct
a6f0: 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 ions from the st
a700: 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 2e 0a andard library..
a710: 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 **.** xSize shou
a720: 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c ld return the al
a730: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 located size of
a740: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
a750: 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c ion.** previousl
a760: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
a770: 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c xMalloc or xReal
a780: 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 loc. The alloca
a790: 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 ted size.** is a
a7a0: 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 lways at least a
a7b0: 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 s big as the req
a7c0: 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 uested size but
a7d0: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a may be larger..*
a7e0: 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 *.** The xRoundu
a7f0: 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 p method returns
a800: 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 what would be t
a810: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a he allocated siz
a820: 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 e of.** a memory
a830: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 allocation give
a840: 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 n a particular r
a850: 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 equested size.
a860: 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 Most memory.** a
a870: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 llocators round
a880: 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 up memory alloca
a890: 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 tions at least t
a8a0: 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 o the next multi
a8b0: 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f ple.** of 8. So
a8c0: 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f me allocators ro
a8d0: 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 und up to a larg
a8e0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 er multiple or t
a8f0: 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a o a power of 2..
a900: 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 **.** The xInit
a910: 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a method initializ
a920: 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c es the memory al
a930: 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 locator. (For e
a940: 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 xample,.** it mi
a950: 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 ght allocate any
a960: 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 require mutexes
a970: 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 or initialize i
a980: 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 nternal data.**
a990: 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 structures. The
a9a0: 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f xShutdown metho
a9b0: 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e d is invoked (in
a9c0: 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 directly) by.**
a9d0: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
a9e0: 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 n()] and should
a9f0: 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 deallocate any r
aa00: 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 esources acquire
aa10: 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 d.** by xInit.
aa20: 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 The pAppData poi
aa30: 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 nter is used as
aa40: 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 the only paramet
aa50: 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 er to.** xInit a
aa60: 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f nd xShutdown..*/
aa70: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
aa80: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
aa90: 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f ods sqlite3_mem_
aaa0: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 methods;.struct
aab0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
aac0: 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a ods {. void *(*
aad0: 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 xMalloc)(int);
aae0: 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 /* Memory
aaf0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 allocation func
ab00: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 tion */. void (
ab10: 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 *xFree)(void*);
ab20: 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 /* Free
ab30: 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 a prior allocat
ab40: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 ion */. void *(
ab50: 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a *xRealloc)(void*
ab60: 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a ,int); /* Resiz
ab70: 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 e an allocation
ab80: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 */. int (*xSize
ab90: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 )(void*);
aba0: 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 /* Return th
abb0: 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c e size of an all
abc0: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 ocation */. int
abd0: 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 (*xRoundup)(int
abe0: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 ); /* R
abf0: 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 ound up request
ac00: 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 size to allocati
ac10: 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 on size */. int
ac20: 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 (*xInit)(void*)
ac30: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 ; /* I
ac40: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 nitialize the me
ac50: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a mory allocator *
ac60: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 /. void (*xShut
ac70: 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 down)(void*);
ac80: 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 /* Deinitiali
ac90: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c ze the memory al
aca0: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 locator */. voi
acb0: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 d *pAppData;
acc0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 /* A
acd0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 rgument to xInit
ace0: 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e () and xShutdown
acf0: 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 () */.};../*.**
ad00: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
ad10: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 uration Options
ad20: 7b 48 31 30 31 36 30 7d 20 3c 53 32 30 30 30 30 {H10160} <S20000
ad30: 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
ad40: 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f L.**.** These co
ad50: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 nstants are the
ad60: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 available intege
ad70: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 r configuration
ad80: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 options that.**
ad90: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 can be passed as
ada0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
adb0: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ent to the [sqli
adc0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e te3_config()] in
add0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e terface..**.** N
ade0: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ew configuration
adf0: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 options may be
ae00: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
ae10: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
ae20: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 te..** Existing
ae30: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
ae40: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 tions might be d
ae50: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 iscontinued. Ap
ae60: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 plications.** sh
ae70: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 ould check the r
ae80: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 eturn code from
ae90: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
aea0: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 )] to make sure
aeb0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c that.** the call
aec0: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 worked. The [s
aed0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
aee0: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 interface will
aef0: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d return a.** non-
af00: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
af10: 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e ] if a discontin
af20: 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 ued or unsupport
af30: 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ed configuration
af40: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e option.** is in
af50: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c voked..**.** <dl
af60: 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f >.** <dt>SQLITE_
af70: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
af80: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e EAD</dt>.** <dd>
af90: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 There are no arg
afa0: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
afb0: 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 ption. This opt
afc0: 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 ion disables.**
afd0: 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 all mutexing and
afe0: 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 puts SQLite int
aff0: 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 o a mode where i
b000: 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 t can only be us
b010: 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c ed.** by a singl
b020: 65 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a e thread.</dd>.*
b030: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
b040: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
b050: 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 AD</dt>.** <dd>T
b060: 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 here are no argu
b070: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 ments to this op
b080: 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 tion. This opti
b090: 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d on disables.** m
b0a0: 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 utexing on [data
b0b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
b0c0: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
b0d0: 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 tatement] object
b0e0: 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 s..** The applic
b0f0: 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 ation is respons
b100: 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 ible for seriali
b110: 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a zing access to.*
b120: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
b130: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 ections] and [pr
b140: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
b150: 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d s]. But other m
b160: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e utexes.** are en
b170: 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 abled so that SQ
b180: 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 Lite will be saf
b190: 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 e to use in a mu
b1a0: 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 lti-threaded.**
b1b0: 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c environment as l
b1c0: 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 ong as no two th
b1d0: 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f reads attempt to
b1e0: 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a use the same.**
b1f0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
b200: 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 ction] at the sa
b210: 6d 65 20 74 69 6d 65 2e 20 20 53 65 65 20 74 68 me time. See th
b220: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 e [threading mod
b230: 65 5d 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74 61 74 e].** documentat
b240: 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ion for addition
b250: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c al information.<
b260: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
b270: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 QLITE_CONFIG_SER
b280: 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 IALIZED</dt>.**
b290: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f <dd>There are no
b2a0: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
b2b0: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 is option. This
b2c0: 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a option enables.
b2d0: 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 ** all mutexes i
b2e0: 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 ncluding the rec
b2f0: 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 ursive.** mutexe
b300: 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 s on [database c
b310: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b onnection] and [
b320: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
b330: 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 nt] objects..**
b340: 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 In this mode (wh
b350: 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 ich is the defau
b360: 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 lt when SQLite i
b370: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
b380: 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 ** [SQLITE_THREA
b390: 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 DSAFE=1]) the SQ
b3a0: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c Lite library wil
b3b0: 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 l itself seriali
b3c0: 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 ze access.** to
b3d0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
b3e0: 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 tions] and [prep
b3f0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
b400: 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 so that the.**
b410: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 application is f
b420: 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 ree to use the s
b430: 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f ame [database co
b440: 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 nnection] or the
b450: 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 .** same [prepar
b460: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e ed statement] in
b470: 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
b480: 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 ds at the same t
b490: 69 6d 65 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 ime..** See the
b4a0: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
b4b0: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 documentation f
b4c0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e or additional in
b4d0: 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a formation.</dd>.
b4e0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
b4f0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f _CONFIG_MALLOC</
b500: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
b510: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
b520: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
b530: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 hich is a pointe
b540: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 r to an.** insta
b550: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
b560: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
b570: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 structure. The
b580: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 argument specif
b590: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 ies.** alternati
b5a0: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d ve low-level mem
b5b0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
b5c0: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 outines to be us
b5d0: 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a ed in place of.*
b5e0: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c * the memory all
b5f0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
b600: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 built into SQLi
b610: 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c te.</dd>.**.** <
b620: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
b630: 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a _GETMALLOC</dt>.
b640: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 ** <dd>This opti
b650: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
b660: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
b670: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
b680: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
b690: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
b6a0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 mem_methods] str
b6b0: 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 ucture. The [sq
b6c0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
b6d0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 s].** structure
b6e0: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 is filled with t
b6f0: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 he currently def
b700: 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ined memory allo
b710: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e cation routines.
b720: 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 .** This option
b730: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
b740: 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 verload the defa
b750: 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ult memory alloc
b760: 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 ation.** routine
b770: 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 s with a wrapper
b780: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e that simulation
b790: 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 s memory allocat
b7a0: 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a ion failure or.*
b7b0: 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 * tracks memory
b7c0: 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 usage, for examp
b7d0: 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c le.</dd>.**.** <
b7e0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
b7f0: 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a _MEMSTATUS</dt>.
b800: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 ** <dd>This opti
b810: 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 on takes single
b820: 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 argument of type
b830: 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 int, interprete
b840: 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 d as a .** boole
b850: 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 an, which enable
b860: 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 s or disables th
b870: 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 e collection of
b880: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
b890: 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 n .** statistics
b8a0: 2e 20 57 68 65 6e 20 64 69 73 61 62 6c 65 64 2c . When disabled,
b8b0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 the following S
b8c0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
b8d0: 20 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d become .** non-
b8e0: 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 operational:.**
b8f0: 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e <ul>.** <li>
b900: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
b910: 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c _used()].** <l
b920: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f i> [sqlite3_memo
b930: 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a ry_highwater()].
b940: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
b950: 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d e3_soft_heap_lim
b960: 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 it()].** <li>
b970: 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 [sqlite3_status(
b980: 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a )].** </ul>.**
b990: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 </dd>.**.** <dt
b9a0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
b9b0: 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c CRATCH</dt>.** <
b9c0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 dd>This option s
b9d0: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 pecifies a stati
b9e0: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 c memory buffer
b9f0: 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 that SQLite can
ba00: 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 use for.** scrat
ba10: 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 ch memory. Ther
ba20: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 e are three argu
ba30: 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 ments: A pointe
ba40: 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 r an 8-byte.** a
ba50: 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 ligned memory bu
ba60: 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 ffer from which
ba70: 74 68 65 20 73 63 72 61 63 68 20 61 6c 6c 6f 63 the scrach alloc
ba80: 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a ations will be.*
ba90: 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a * drawn, the siz
baa0: 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 e of each scratc
bab0: 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a h allocation (sz
bac0: 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 ),.** and the ma
bad0: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
bae0: 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 scratch allocati
baf0: 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a ons (N). The sz
bb00: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 .** argument mus
bb10: 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 t be a multiple
bb20: 6f 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70 61 of 16. The sz pa
bb30: 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 rameter should b
bb40: 65 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a 2a e a few bytes.**
bb50: 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 larger than the
bb60: 20 61 63 74 75 61 6c 20 73 63 72 61 74 63 68 20 actual scratch
bb70: 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20 64 space required d
bb80: 75 65 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20 6f ue to internal o
bb90: 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65 20 verhead..** The
bba0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 first argument s
bbb0: 68 6f 75 6c 64 20 70 6f 69 6e 74 65 72 20 74 6f hould pointer to
bbc0: 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e an 8-byte align
bbd0: 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 ed buffer.** of
bbe0: 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 at least sz*N by
bbf0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a tes of memory..*
bc00: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 * SQLite will us
bc10: 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f e no more than o
bc20: 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65 ne scratch buffe
bc30: 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68 r at once per th
bc40: 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 read, so.** N sh
bc50: 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 ould be set to t
bc60: 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 he expected maxi
bc70: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 mum number of th
bc80: 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a reads. The sz.*
bc90: 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 * parameter shou
bca0: 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20 74 68 ld be 6 times th
bcb0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 e size of the la
bcc0: 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 rgest database p
bcd0: 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 age size..** Scr
bce0: 61 74 63 68 20 62 75 66 66 65 72 73 20 61 72 65 atch buffers are
bcf0: 20 75 73 65 64 20 61 73 20 70 61 72 74 20 6f 66 used as part of
bd00: 20 74 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e the btree balan
bd10: 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 ce operation. I
bd20: 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62 f.** The btree b
bd30: 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64 alancer needs ad
bd40: 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 ditional memory
bd50: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 beyond what is p
bd60: 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 rovided by.** sc
bd70: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 6f 72 ratch buffers or
bd80: 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62 if no scratch b
bd90: 75 66 66 65 72 20 73 70 61 63 65 20 69 73 20 73 uffer space is s
bda0: 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53 pecified, then S
bdb0: 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f QLite.** goes to
bdc0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
bdd0: 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 ()] to obtain th
bde0: 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 e memory it need
bdf0: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 s.</dd>.**.** <d
be00: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
be10: 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a PAGECACHE</dt>.*
be20: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f * <dd>This optio
be30: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 n specifies a st
be40: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 atic memory buff
be50: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 er that SQLite c
be60: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 an use for.** th
be70: 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 e database page
be80: 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 cache with the d
be90: 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 efault page cach
bea0: 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e e implemenation.
beb0: 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 .** This confi
bec0: 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 guration should
bed0: 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 not be used if a
bee0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
bef0: 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 fine page.** cac
bf00: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
bf10: 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e n is loaded usin
bf20: 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e g the SQLITE_CON
bf30: 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f FIG_PCACHE optio
bf40: 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 n..** There are
bf50: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 three arguments
bf60: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 to this option:
bf70: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 A pointer to 8-b
bf80: 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d yte aligned.** m
bf90: 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 emory, the size
bfa0: 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 of each page buf
bfb0: 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 fer (sz), and th
bfc0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 e number of page
bfd0: 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a s (N)..** The sz
bfe0: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 argument should
bff0: 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 be the size of
c000: 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 the largest data
c010: 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 base page.** (a
c020: 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 power of two bet
c030: 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 ween 512 and 327
c040: 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 68) plus a littl
c050: 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 e extra for each
c060: 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e .** page header.
c070: 20 20 54 68 65 20 70 61 67 65 20 68 65 61 64 65 The page heade
c080: 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 r size is 20 to
c090: 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 40 bytes dependi
c0a0: 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 ng on.** the hos
c0b0: 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 t architecture.
c0c0: 20 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c It is harmless,
c0d0: 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 apart from the
c0e0: 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a wasted memory,.*
c0f0: 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c * to make sz a l
c100: 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e ittle too large.
c110: 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 The first.** a
c120: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 rgument should p
c130: 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 oint to an alloc
c140: 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 ation of at leas
c150: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 t sz*N bytes of
c160: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 memory..** SQLit
c170: 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d e will use the m
c180: 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 emory provided b
c190: 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 y the first argu
c1a0: 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 ment to satisfy
c1b0: 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 its.** memory ne
c1c0: 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 eds for the firs
c1d0: 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 t N pages that i
c1e0: 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e t adds to cache.
c1f0: 20 20 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a If additional.
c200: 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 ** page cache me
c210: 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 mory is needed b
c220: 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 eyond what is pr
c230: 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f ovided by this o
c240: 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 ption, then.** S
c250: 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 QLite goes to [s
c260: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
c270: 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f for the additio
c280: 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 nal storage spac
c290: 65 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d e..** The implem
c2a0: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 entation might u
c2b0: 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f se one or more o
c2c0: 66 20 74 68 65 20 4e 20 62 75 66 66 65 72 73 20 f the N buffers
c2d0: 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f to hold .** memo
c2e0: 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e ry accounting in
c2f0: 66 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 65 20 70 formation. The p
c300: 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 ointer in the fi
c310: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 rst argument mus
c320: 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 t.** be aligned
c330: 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 to an 8-byte bou
c340: 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 ndary or subsequ
c350: 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 ent behavior of
c360: 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 SQLite.** will b
c370: 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 e undefined.</dd
c380: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
c390: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f TE_CONFIG_HEAP</
c3a0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
c3b0: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 option specifies
c3c0: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 a static memory
c3d0: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c buffer that SQL
c3e0: 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 ite will use.**
c3f0: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 for all of its d
c400: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c ynamic memory al
c410: 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 location needs b
c420: 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 eyond those prov
c430: 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b ided.** for by [
c440: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
c450: 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 RATCH] and [SQLI
c460: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
c470: 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 CHE]..** There a
c480: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e re three argumen
c490: 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c ts: An 8-byte al
c4a0: 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f igned pointer to
c4b0: 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 the memory,.**
c4c0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
c4d0: 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 tes in the memor
c4e0: 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 y buffer, and th
c4f0: 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 e minimum alloca
c500: 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 49 66 tion size..** If
c510: 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 the first point
c520: 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 er (the memory p
c530: 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c ointer) is NULL,
c540: 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 then SQLite rev
c550: 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 erts.** to using
c560: 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d its default mem
c570: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 ory allocator (t
c580: 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 he system malloc
c590: 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f () implementatio
c5a0: 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 n),.** undoing a
c5b0: 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 ny prior invocat
c5c0: 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 ion of [SQLITE_C
c5d0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 ONFIG_MALLOC].
c5e0: 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 If the.** memory
c5f0: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 pointer is not
c600: 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 NULL and either
c610: 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d [SQLITE_ENABLE_M
c620: 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 EMSYS3] or.** [S
c630: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d QLITE_ENABLE_MEM
c640: 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 SYS5] are define
c650: 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 d, then the alte
c660: 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a rnative memory.*
c670: 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 * allocator is e
c680: 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 ngaged to handle
c690: 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 all of SQLites
c6a0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
c6b0: 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 n needs..** The
c6c0: 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 first pointer (t
c6d0: 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 he memory pointe
c6e0: 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e r) must be align
c6f0: 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a ed to an 8-byte.
c700: 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 ** boundary or s
c710: 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 ubsequent behavi
c720: 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c or of SQLite wil
c730: 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c l be undefined.<
c740: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
c750: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
c760: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 EX</dt>.** <dd>T
c770: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
c780: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
c790: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f nt which is a po
c7a0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 inter to an.** i
c7b0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
c7c0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
c7d0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
c7e0: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 . The argument
c7f0: 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 specifies.** alt
c800: 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 ernative low-lev
c810: 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 el mutex routine
c820: 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 s to be used in
c830: 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 place.** the mut
c840: 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c ex routines buil
c850: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f t into SQLite.</
c860: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
c870: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
c880: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 UTEX</dt>.** <dd
c890: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b >This option tak
c8a0: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
c8b0: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
c8c0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
c8d0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
c8e0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
c8f0: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
c900: 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c re. The.** [sql
c910: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
c920: 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 ds].** structure
c930: 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 is filled with
c940: 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 the currently de
c950: 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 fined mutex rout
c960: 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 ines..** This op
c970: 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 tion can be used
c980: 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 to overload the
c990: 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 default mutex a
c9a0: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 llocation.** rou
c9b0: 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 tines with a wra
c9c0: 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 pper used to tra
c9d0: 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 ck mutex usage f
c9e0: 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a or performance.*
c9f0: 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 * profiling or t
ca00: 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d esting, for exam
ca10: 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ple.</dd>.**.**
ca20: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
ca30: 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e G_LOOKASIDE</dt>
ca40: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
ca50: 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 ion takes two ar
ca60: 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 guments that det
ca70: 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 ermine the defau
ca80: 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c lt.** memory all
ca90: 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 cation lookaside
caa0: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 optimization.
cab0: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
cac0: 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a nt is the.** siz
cad0: 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 e of each lookas
cae0: 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 ide buffer slot
caf0: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 and the second i
cb00: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a s the number of.
cb10: 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 ** slots allocat
cb20: 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 ed to each datab
cb30: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c ase connection.<
cb40: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
cb50: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
cb60: 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e CHE</dt>.** <dd>
cb70: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
cb80: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
cb90: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
cba0: 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 ointer to.** an
cbb0: 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
cbc0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e methods] object.
cbd0: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 This object sp
cbe0: 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 ecifies the inte
cbf0: 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 rface.** to a cu
cc00: 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 stom page cache
cc10: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 implementation.
cc20: 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 SQLite makes a
cc30: 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f copy of the.** o
cc40: 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 bject and uses i
cc50: 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 t for page cache
cc60: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
cc70: 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ons.</dd>.**.**
cc80: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
cc90: 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74 3e G_GETPCACHE</dt>
cca0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
ccb0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
ccc0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
ccd0: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 h is a pointer t
cce0: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 o an.** [sqlite3
ccf0: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d _pcache_methods]
cd00: 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 object. SQLite
cd10: 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 copies of the c
cd20: 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 urrent.** page c
cd30: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
cd40: 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 ion into that ob
cd50: 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ject.</dd>.**.**
cd60: 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </dl>.*/.#defin
cd70: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
cd80: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 SINGLETHREAD 1
cd90: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
cda0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
cdb0: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 _MULTITHREAD 2
cdc0: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
cdd0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
cde0: 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 G_SERIALIZED
cdf0: 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 3 /* nil */.#de
ce00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
ce10: 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 IG_MALLOC
ce20: 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 4 /* sqlite3_m
ce30: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 em_methods* */.#
ce40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
ce50: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 NFIG_GETMALLOC
ce60: 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5 /* sqlite3
ce70: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f _mem_methods* */
ce80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
ce90: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 CONFIG_SCRATCH
cea0: 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 6 /* void*
ceb0: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 , int sz, int N
cec0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
ced0: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
cee0: 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 HE 7 /* voi
cef0: 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 d*, int sz, int
cf00: 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c N */.#define SQL
cf10: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 ITE_CONFIG_HEAP
cf20: 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 8 /* v
cf30: 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c oid*, int nByte,
cf40: 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 int min */.#def
cf50: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
cf60: 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 G_MEMSTATUS
cf70: 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 9 /* boolean */
cf80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
cf90: 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 CONFIG_MUTEX
cfa0: 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 10 /* sqlit
cfb0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
cfc0: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
cfd0: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
cfe0: 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 TEX 11 /* s
cff0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
d000: 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 hods* */./* prev
d010: 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f iously SQLITE_CO
d020: 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 NFIG_CHUNKALLOC
d030: 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 12 which is now
d040: 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 unused. */ .#def
d050: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
d060: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 G_LOOKASIDE 1
d070: 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 3 /* int int */
d080: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d090: 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 CONFIG_PCACHE
d0a0: 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 14 /* sqlit
d0b0: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
d0c0: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
d0d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
d0e0: 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 CACHE 15 /*
d0f0: 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d sqlite3_pcache_m
d100: 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a ethods* */../*.*
d110: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
d120: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e iguration Option
d130: 73 20 7b 48 31 30 31 37 30 7d 20 3c 53 32 30 30 s {H10170} <S200
d140: 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 00>.** EXPERIMEN
d150: 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TAL.**.** These
d160: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 constants are th
d170: 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 e available inte
d180: 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ger configuratio
d190: 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a n options that.*
d1a0: 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 * can be passed
d1b0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 as the second ar
d1c0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 gument to the [s
d1d0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
d1e0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
d1f0: 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 *.** New configu
d200: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
d210: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
d220: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
d230: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 f SQLite..** Exi
d240: 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 sting configurat
d250: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 ion options migh
d260: 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 t be discontinue
d270: 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 d. Applications
d280: 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b .** should check
d290: 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 the return code
d2a0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 from [sqlite3_d
d2b0: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d b_config()] to m
d2c0: 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a ake sure that.**
d2d0: 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 the call worked
d2e0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
d2f0: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 db_config()] int
d300: 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 erface will retu
d310: 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f rn a.** non-zero
d320: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
d330: 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 a discontinued
d340: 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 or unsupported c
d350: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
d360: 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 ion.** is invoke
d370: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a d..**.** <dl>.**
d380: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
d390: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f NFIG_LOOKASIDE</
d3a0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
d3b0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 option takes thr
d3c0: 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 ee additional ar
d3d0: 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 guments that det
d3e0: 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b ermine the .** [
d3f0: 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
d400: 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 allocator] conf
d410: 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 iguration for th
d420: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
d430: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 ection]..** The
d440: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 first argument (
d450: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
d460: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
d470: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 db_config()] is
d480: 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 a.** pointer to
d490: 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 an 8-byte aligne
d4a0: 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 d memory buffer
d4b0: 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 to use for looka
d4c0: 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 side memory..**
d4d0: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
d4e0: 6e 74 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 nt may be NULL i
d4f0: 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c n which case SQL
d500: 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 ite will allocat
d510: 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 e the.** lookasi
d520: 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 de buffer itself
d530: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
d540: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 malloc()]. The
d550: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
d560: 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f is the.** size o
d570: 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 f each lookaside
d580: 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 buffer slot and
d590: 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d the third argum
d5a0: 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ent is the numbe
d5b0: 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 r of.** slots.
d5c0: 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 The size of the
d5d0: 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 buffer in the fi
d5e0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 rst argument mus
d5f0: 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 t be greater tha
d600: 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f n.** or equal to
d610: 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 the product of
d620: 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 the second and t
d630: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 3c hird arguments.<
d640: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e /dd>.**.** </dl>
d650: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
d660: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
d670: 41 53 49 44 45 20 20 20 20 31 30 30 31 20 20 2f ASIDE 1001 /
d680: 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 * void* int int
d690: 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */.../*.** CAPI3
d6a0: 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 REF: Enable Or D
d6b0: 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 isable Extended
d6c0: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 Result Codes {H1
d6d0: 32 32 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2200} <S10700>.*
d6e0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
d6f0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
d700: 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 _codes() routine
d710: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 enables or disa
d720: 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 bles the.** [ext
d730: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
d740: 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 es] feature of S
d750: 51 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e QLite. The exten
d760: 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f ded result.** co
d770: 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 des are disabled
d780: 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 by default for
d790: 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 historical compa
d7a0: 74 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 tibility conside
d7b0: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 rations..**.** R
d7c0: 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
d7d0: 5b 48 31 32 32 30 31 5d 20 5b 48 31 32 32 30 32 [H12201] [H12202
d7e0: 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ].*/.int sqlite3
d7f0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
d800: 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c _codes(sqlite3*,
d810: 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a int onoff);../*
d820: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 .** CAPI3REF: La
d830: 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 st Insert Rowid
d840: 7b 48 31 32 32 32 30 7d 20 3c 53 31 30 37 30 30 {H12220} <S10700
d850: 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 >.**.** Each ent
d860: 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 ry in an SQLite
d870: 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 table has a uniq
d880: 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 ue 64-bit signed
d890: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 .** integer key
d8a0: 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 called the [ROWI
d8b0: 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 54 68 D | "rowid"]. Th
d8c0: 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 e rowid is alway
d8d0: 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 s available.** a
d8e0: 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 s an undeclared
d8f0: 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 column named ROW
d900: 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 ID, OID, or _ROW
d910: 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 ID_ as long as t
d920: 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 hose.** names ar
d930: 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 e not also used
d940: 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 by explicitly de
d950: 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 clared columns.
d960: 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 If.** the table
d970: 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 has a column of
d980: 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 type [INTEGER PR
d990: 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 IMARY KEY] then
d9a0: 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 that column.** i
d9b0: 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 s another alias
d9c0: 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a for the rowid..*
d9d0: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
d9e0: 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 e returns the [r
d9f0: 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 owid] of the mos
da00: 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 t recent.** succ
da10: 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 essful [INSERT]
da20: 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 into the databas
da30: 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 e from the [data
da40: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
da50: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 .** in the first
da60: 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e argument. If n
da70: 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e o successful [IN
da80: 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 SERT]s.** have e
da90: 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 ver occurred on
daa0: 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f that database co
dab0: 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 nnection, zero i
dac0: 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
dad0: 2a 20 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d * If an [INSERT]
dae0: 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 occurs within a
daf0: 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 trigger, then t
db00: 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 he [rowid] of th
db10: 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f e inserted.** ro
db20: 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 w is returned by
db30: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 this routine as
db40: 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 long as the tri
db50: 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e gger is running.
db60: 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 .** But once the
db70: 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 trigger termina
db80: 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 tes, the value r
db90: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 eturned by this
dba0: 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 routine.** rever
dbb0: 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 ts to the last v
dbc0: 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 alue inserted be
dbd0: 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 fore the trigger
dbe0: 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e fired..**.** An
dbf0: 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 [INSERT] that f
dc00: 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f ails due to a co
dc10: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 nstraint violati
dc20: 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 on is not a.** s
dc30: 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
dc40: 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 T] and does not
dc50: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
dc60: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
dc70: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 s.** routine. T
dc80: 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 hus INSERT OR FA
dc90: 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 IL, INSERT OR IG
dca0: 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 NORE, INSERT OR
dcb0: 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 ROLLBACK,.** and
dcc0: 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 INSERT OR ABORT
dcd0: 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 make no changes
dce0: 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 to the return v
dcf0: 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 alue of this.**
dd00: 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 routine when the
dd10: 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 ir insertion fai
dd20: 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 ls. When INSERT
dd30: 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 OR REPLACE.** e
dd40: 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 ncounters a cons
dd50: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e traint violation
dd60: 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 , it does not fa
dd70: 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 il. The.** INSE
dd80: 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 RT continues to
dd90: 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 completion after
dda0: 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 deleting rows t
ddb0: 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 hat caused.** th
ddc0: 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f e constraint pro
ddd0: 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f blem so INSERT O
dde0: 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 R REPLACE will a
ddf0: 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 lways change.**
de00: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
de10: 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 of this interfa
de20: 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 ce..**.** For th
de30: 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 e purposes of th
de40: 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b is routine, an [
de50: 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 INSERT] is consi
de60: 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 dered to.** be s
de70: 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 uccessful even i
de80: 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 f it is subseque
de90: 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b ntly rolled back
dea0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
deb0: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 32 31 ents:.** [H12221
dec0: 5d 20 5b 48 31 32 32 32 33 5d 0a 2a 2a 0a 2a 2a ] [H12223].**.**
ded0: 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
dee0: 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 hread performs a
def0: 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e new [INSERT] on
df00: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 the same.** dat
df10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
df20: 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 while the [sqli
df30: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
df40: 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 rowid()].** func
df50: 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 tion is running
df60: 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 and thus changes
df70: 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 the last insert
df80: 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 [rowid],.** the
df90: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 n the value retu
dfa0: 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
dfb0: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
dfc0: 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 id()] is.** unpr
dfd0: 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 edictable and mi
dfe0: 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 ght not equal ei
dff0: 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 ther the old or
e000: 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 the new.** last
e010: 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a insert [rowid]..
e020: 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 */.sqlite3_int64
e030: 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e sqlite3_last_in
e040: 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 sert_rowid(sqlit
e050: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
e060: 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 I3REF: Count The
e070: 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 Number Of Rows
e080: 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34 30 Modified {H12240
e090: 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a } <S10600>.**.**
e0a0: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 This function r
e0b0: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
e0c0: 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f r of database ro
e0d0: 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 ws that were cha
e0e0: 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 nged.** or inser
e0f0: 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 ted or deleted b
e100: 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e y the most recen
e110: 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 tly completed SQ
e120: 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f L statement.** o
e130: 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 n the [database
e140: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 connection] spec
e150: 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 ified by the fir
e160: 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a st parameter..**
e170: 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 Only changes th
e180: 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 at are directly
e190: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
e1a0: 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 [INSERT], [UPDA
e1b0: 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 TE],.** or [DELE
e1c0: 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 TE] statement ar
e1d0: 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 e counted. Auxi
e1e0: 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 liary changes ca
e1f0: 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 used by.** trigg
e200: 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e ers are not coun
e210: 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 ted. Use the [sq
e220: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
e230: 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a ges()] function.
e240: 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 ** to find the t
e250: 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 otal number of c
e260: 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 hanges including
e270: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 changes caused
e280: 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a by triggers..**.
e290: 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 ** Changes to a
e2a0: 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 view that are si
e2b0: 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 mulated by an [I
e2c0: 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 NSTEAD OF trigge
e2d0: 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f r].** are not co
e2e0: 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 unted. Only rea
e2f0: 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 l table changes
e300: 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a are counted..**.
e310: 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 ** A "row change
e320: 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f " is a change to
e330: 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 a single row of
e340: 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a a single table.
e350: 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 ** caused by an
e360: 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 INSERT, DELETE,
e370: 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d or UPDATE statem
e380: 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a ent. Rows that.
e390: 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 ** are changed a
e3a0: 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f s side effects o
e3b0: 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 f [REPLACE] cons
e3c0: 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f traint resolutio
e3d0: 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 n,.** rollback,
e3e0: 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 ABORT processing
e3f0: 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 , [DROP TABLE],
e400: 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a or by any other.
e410: 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f ** mechanisms do
e420: 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 not count as di
e430: 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 rect row changes
e440: 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 ..**.** A "trigg
e450: 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 er context" is a
e460: 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 scope of execut
e470: 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 ion that begins
e480: 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 and.** ends with
e490: 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 the script of a
e4a0: 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 [CREATE TRIGGER
e4b0: 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a | trigger]. .**
e4c0: 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d Most SQL statem
e4d0: 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c ents are.** eval
e4e0: 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 uated outside of
e4f0: 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 any trigger. T
e500: 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 his is the "top
e510: 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 level".** trigge
e520: 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 r context. If a
e530: 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 trigger fires f
e540: 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 rom the top leve
e550: 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 l, a.** new trig
e560: 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 ger context is e
e570: 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 ntered for the d
e580: 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 uration of that
e590: 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 one.** trigger.
e5a0: 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 Subtriggers cre
e5b0: 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 ate subcontexts
e5c0: 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 for their durati
e5d0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e on..**.** Callin
e5e0: 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 g [sqlite3_exec(
e5f0: 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 )] or [sqlite3_s
e600: 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 tep()] recursive
e610: 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 ly does.** not c
e620: 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 reate a new trig
e630: 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a ger context..**.
e640: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
e650: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
e660: 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f ber of direct ro
e670: 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 w changes in the
e680: 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 .** most recent
e690: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
e6a0: 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d or DELETE statem
e6b0: 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 ent within the s
e6c0: 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 ame.** trigger c
e6d0: 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 ontext..**.** Th
e6e0: 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 us, when called
e6f0: 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 from the top lev
e700: 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f el, this functio
e710: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a n returns the.**
e720: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 number of chang
e730: 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 es in the most r
e740: 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 ecent INSERT, UP
e750: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a DATE, or DELETE.
e760: 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 ** that also occ
e770: 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 urred at the top
e780: 20 6c 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 level. Within
e790: 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 the body of a tr
e7a0: 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 igger,.** the sq
e7b0: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 lite3_changes()
e7c0: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 interface can be
e7d0: 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 called to find
e7e0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
e7f0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 changes in the
e800: 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f most recently co
e810: 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 mpleted INSERT,
e820: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 UPDATE, or DELET
e830: 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 E.** statement w
e840: 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f ithin the body o
e850: 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 f the same trigg
e860: 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 er..** However,
e870: 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 the number retur
e880: 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 ned does not inc
e890: 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 lude changes.**
e8a0: 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 caused by subtri
e8b0: 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 ggers since thos
e8c0: 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e e have their own
e8d0: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 context..**.**
e8e0: 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 See also the [sq
e8f0: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
e900: 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ges()] interface
e910: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 and the.** [cou
e920: 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d nt_changes pragm
e930: 61 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 a]..**.** Requir
e940: 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 ements:.** [H122
e950: 34 31 5d 20 5b 48 31 32 32 34 33 5d 0a 2a 2a 0a 41] [H12243].**.
e960: 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 ** If a separate
e970: 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 thread makes ch
e980: 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d anges on the sam
e990: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
e9a0: 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b ction.** while [
e9b0: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
e9c0: 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 )] is running th
e9d0: 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 en the value ret
e9e0: 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 urned.** is unpr
e9f0: 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f edictable and no
ea00: 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f t meaningful..*/
ea10: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 .int sqlite3_cha
ea20: 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a nges(sqlite3*);.
ea30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
ea40: 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 Total Number Of
ea50: 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b Rows Modified {
ea60: 48 31 32 32 36 30 7d 20 3c 53 31 30 36 30 30 3e H12260} <S10600>
ea70: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
ea80: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
ea90: 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 number of row c
eaa0: 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 hanges caused by
eab0: 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 [INSERT],.** [U
eac0: 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 PDATE] or [DELET
ead0: 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 E] statements si
eae0: 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 nce the [databas
eaf0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 e connection] wa
eb00: 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 s opened..** The
eb10: 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 count includes
eb20: 61 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d all changes from
eb30: 20 61 6c 6c 20 0a 2a 2a 20 5b 43 52 45 41 54 45 all .** [CREATE
eb40: 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 TRIGGER | trigg
eb50: 65 72 5d 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 er] contexts. H
eb60: 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 owever,.** the c
eb70: 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e ount does not in
eb80: 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 clude changes us
eb90: 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 ed to implement
eba0: 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 [REPLACE] constr
ebb0: 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c aints,.** do rol
ebc0: 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 lbacks or ABORT
ebd0: 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b processing, or [
ebe0: 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 DROP TABLE] proc
ebf0: 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 essing. The.**
ec00: 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 count does not i
ec10: 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 nclude rows of v
ec20: 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 iews that fire a
ec30: 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 n [INSTEAD OF tr
ec40: 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 igger],.** thoug
ec50: 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 h if the INSTEAD
ec60: 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 OF trigger make
ec70: 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 s changes of its
ec80: 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e own, those chan
ec90: 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e ges .** are coun
eca0: 74 65 64 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e ted..** The chan
ecb0: 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 ges are counted
ecc0: 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 as soon as the s
ecd0: 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 tatement that ma
ece0: 6b 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 kes them is.** c
ecf0: 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 ompleted (when t
ed00: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e he statement han
ed10: 64 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 6f dle is passed to
ed20: 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
ed30: 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
ed40: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 3_finalize()])..
ed50: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 **.** See also t
ed60: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e he [sqlite3_chan
ed70: 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ges()] interface
ed80: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 and the.** [cou
ed90: 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d nt_changes pragm
eda0: 61 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 a]..**.** Requir
edb0: 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 ements:.** [H122
edc0: 36 31 5d 20 5b 48 31 32 32 36 33 5d 0a 2a 2a 0a 61] [H12263].**.
edd0: 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 ** If a separate
ede0: 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 thread makes ch
edf0: 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d anges on the sam
ee00: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
ee10: 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b ction.** while [
ee20: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
ee30: 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e anges()] is runn
ee40: 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c ing then the val
ee50: 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 ue.** returned i
ee60: 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 s unpredictable
ee70: 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 and not meaningf
ee80: 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ul..*/.int sqlit
ee90: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
eea0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
eeb0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 ** CAPI3REF: Int
eec0: 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 errupt A Long-Ru
eed0: 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31 32 nning Query {H12
eee0: 32 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 270} <S30500>.**
eef0: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f .** This functio
ef00: 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e n causes any pen
ef10: 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 ding database op
ef20: 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 eration to abort
ef30: 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 and.** return a
ef40: 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f t its earliest o
ef50: 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 pportunity. This
ef60: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 routine is typi
ef70: 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 cally.** called
ef80: 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 in response to a
ef90: 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 user action suc
efa0: 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 h as pressing "C
efb0: 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 ancel".** or Ctr
efc0: 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 l-C where the us
efd0: 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 er wants a long
efe0: 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 query operation
eff0: 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 to halt.** immed
f000: 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 iately..**.** It
f010: 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c is safe to call
f020: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 this routine fr
f030: 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 om a thread diff
f040: 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a erent from the.*
f050: 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 * thread that is
f060: 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 currently runni
f070: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ng the database
f080: 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 operation. But
f090: 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 it.** is not saf
f0a0: 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 e to call this r
f0b0: 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 outine with a [d
f0c0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
f0d0: 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 on] that.** is c
f0e0: 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 losed or might c
f0f0: 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 lose before sqli
f100: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
f110: 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 returns..**.** I
f120: 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 f an SQL operati
f130: 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c on is very nearl
f140: 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 y finished at th
f150: 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 e time when.** s
f160: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
f170: 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 () is called, th
f180: 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 en it might not
f190: 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e have an opportun
f1a0: 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 ity.** to be int
f1b0: 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 errupted and mig
f1c0: 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 ht continue to c
f1d0: 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a ompletion..**.**
f1e0: 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f An SQL operatio
f1f0: 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 n that is interr
f200: 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 upted will retur
f210: 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 n [SQLITE_INTERR
f220: 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 UPT]..** If the
f230: 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 interrupted SQL
f240: 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 operation is an
f250: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
f260: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 or DELETE.** tha
f270: 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 t is inside an e
f280: 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
f290: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e ion, then the en
f2a0: 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e tire transaction
f2b0: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c .** will be roll
f2c0: 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 ed back automati
f2d0: 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 cally..**.** The
f2e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
f2f0: 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e pt(D) call is in
f300: 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c effect until al
f310: 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e l currently runn
f320: 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ing.** SQL state
f330: 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 ments on [databa
f340: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
f350: 20 63 6f 6d 70 6c 65 74 65 2e 20 20 41 6e 79 20 complete. Any
f360: 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e new SQL statemen
f370: 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 ts.** that are s
f380: 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 tarted after the
f390: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
f3a0: 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 pt() call and be
f3b0: 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e fore the .** run
f3c0: 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 ning statements
f3d0: 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 reaches zero are
f3e0: 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 interrupted as
f3f0: 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e if they had been
f400: 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f .** running prio
f410: 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
f420: 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c _interrupt() cal
f430: 6c 2e 20 20 4e 65 77 20 53 51 4c 20 73 74 61 74 l. New SQL stat
f440: 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 ements.** that a
f450: 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 re started after
f460: 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 the running sta
f470: 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 tement count rea
f480: 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a ches zero are.**
f490: 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 not effected by
f4a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 the sqlite3_int
f4b0: 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 41 20 63 errupt()..** A c
f4c0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 all to sqlite3_i
f4d0: 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 nterrupt(D) that
f4e0: 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 occurs when the
f4f0: 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e re are no runnin
f500: 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 g.** SQL stateme
f510: 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 nts is a no-op a
f520: 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 nd has no effect
f530: 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e on SQL statemen
f540: 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 ts.** that are s
f550: 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 tarted after the
f560: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
f570: 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e pt() call return
f580: 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 s..**.** Require
f590: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 37 ments:.** [H1227
f5a0: 31 5d 20 5b 48 31 32 32 37 32 5d 0a 2a 2a 0a 2a 1] [H12272].**.*
f5b0: 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 * If the databas
f5c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f e connection clo
f5d0: 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 ses while [sqlit
f5e0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a e3_interrupt()].
f5f0: 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 ** is running th
f600: 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 en bad things wi
f610: 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e ll likely happen
f620: 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ..*/.void sqlite
f630: 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 3_interrupt(sqli
f640: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
f650: 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e PI3REF: Determin
f660: 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 e If An SQL Stat
f670: 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 ement Is Complet
f680: 65 20 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 32 e {H10510} <S702
f690: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 00>.**.** These
f6a0: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 routines are use
f6b0: 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 ful during comma
f6c0: 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f nd-line input to
f6d0: 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 determine if th
f6e0: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 e.** currently e
f6f0: 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d ntered text seem
f700: 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 s to form a comp
f710: 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 lete SQL stateme
f720: 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 nt or.** if addi
f730: 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 tional input is
f740: 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 needed before se
f750: 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 nding the text i
f760: 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f nto.** SQLite fo
f770: 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73 r parsing. Thes
f780: 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 e routines retur
f790: 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 n 1 if the input
f7a0: 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 string.** appea
f7b0: 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c rs to be a compl
f7c0: 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ete SQL statemen
f7d0: 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 t. A statement
f7e0: 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a is judged to be.
f7f0: 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 ** complete if i
f800: 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 t ends with a se
f810: 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e micolon token an
f820: 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 d is not a prefi
f830: 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 x of a.** well-f
f840: 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 ormed CREATE TRI
f850: 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 GGER statement.
f860: 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 Semicolons that
f870: 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 are embedded wi
f880: 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c thin.** string l
f890: 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 iterals or quote
f8a0: 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d d identifier nam
f8b0: 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 es or comments a
f8c0: 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 re not.** indepe
f8d0: 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 ndent tokens (th
f8e0: 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 ey are part of t
f8f0: 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 he token in whic
f900: 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d h they are.** em
f910: 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 bedded) and thus
f920: 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 do not count as
f930: 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 a statement ter
f940: 6d 69 6e 61 74 6f 72 2e 20 20 57 68 69 74 65 73 minator. Whites
f950: 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d pace.** and comm
f960: 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 ents that follow
f970: 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 the final semic
f980: 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 olon are ignored
f990: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
f9a0: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 utines return 0
f9b0: 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 if the statement
f9c0: 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 is incomplete.
f9d0: 20 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 If a.** memory
f9e0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 allocation fails
f9f0: 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f , then SQLITE_NO
fa00: 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e MEM is returned.
fa10: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
fa20: 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 tines do not par
fa30: 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 se the SQL state
fa40: 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 ments thus.** wi
fa50: 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 ll not detect sy
fa60: 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f ntactically inco
fa70: 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a rrect SQL..**.**
fa80: 20 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e If SQLite has n
fa90: 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 ot been initiali
faa0: 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 zed using [sqlit
fab0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
fac0: 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e prior .** to in
fad0: 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 voking sqlite3_c
fae0: 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e omplete16() then
faf0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
fb00: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ize() is invoked
fb10: 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c .** automaticall
fb20: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d y by sqlite3_com
fb30: 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 plete16(). If t
fb40: 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 hat initializati
fb50: 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 on fails,.** the
fb60: 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c n the return val
fb70: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
fb80: 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c complete16() wil
fb90: 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a l be non-zero.**
fba0: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 regardless of w
fbb0: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
fbc0: 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 e input SQL is c
fbd0: 6f 6d 70 6c 65 74 65 2e 0a 2a 2a 0a 2a 2a 20 52 omplete..**.** R
fbe0: 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 equirements: [H1
fbf0: 30 35 31 31 5d 20 5b 48 31 30 35 31 32 5d 0a 2a 0511] [H10512].*
fc00: 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 *.** The input t
fc10: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c o [sqlite3_compl
fc20: 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 ete()] must be a
fc30: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
fc40: 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 .** UTF-8 string
fc50: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 ..**.** The inpu
fc60: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f t to [sqlite3_co
fc70: 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 mplete16()] must
fc80: 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 be a zero-termi
fc90: 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 nated.** UTF-16
fca0: 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 string in native
fcb0: 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a byte order..*/.
fcc0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 int sqlite3_comp
fcd0: 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 lete(const char
fce0: 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 *sql);.int sqlit
fcf0: 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f e3_complete16(co
fd00: 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a nst void *sql);.
fd10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
fd20: 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c Register A Call
fd30: 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 back To Handle S
fd40: 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 QLITE_BUSY Error
fd50: 73 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 34 s {H12310} <S404
fd60: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 00>.**.** This r
fd70: 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 outine sets a ca
fd80: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
fd90: 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e that might be in
fda0: 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a voked whenever.*
fdb0: 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 * an attempt is
fdc0: 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 made to open a d
fdd0: 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 atabase table th
fde0: 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 at another threa
fdf0: 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 d.** or process
fe00: 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a has locked..**.*
fe10: 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 * If the busy ca
fe20: 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 llback is NULL,
fe30: 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 then [SQLITE_BUS
fe40: 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f Y] or [SQLITE_IO
fe50: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 ERR_BLOCKED].**
fe60: 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 is returned imme
fe70: 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 diately upon enc
fe80: 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f ountering the lo
fe90: 63 6b 2e 20 49 66 20 74 68 65 20 62 75 73 79 20 ck. If the busy
fea0: 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e callback.** is n
feb0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 ot NULL, then th
fec0: 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 e callback will
fed0: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 be invoked with
fee0: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a two arguments..*
fef0: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
ff00: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 rgument to the h
ff10: 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 andler is a copy
ff20: 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f of the void* po
ff30: 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 inter which.** i
ff40: 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 s the third argu
ff50: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
ff60: 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 busy_handler().
ff70: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
ff80: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 ment to.** the h
ff90: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 andler callback
ffa0: 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
ffb0: 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 times that the
ffc0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 busy handler has
ffd0: 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 .** been invoked
ffe0: 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e for this lockin
fff0: 67 20 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65 g event. If the
10000 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 .** busy callbac
10010 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 k returns 0, the
10020 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 n no additional
10030 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 attempts are mad
10040 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 e to.** access t
10050 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 he database and
10060 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 [SQLITE_BUSY] or
10070 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 [SQLITE_IOERR_B
10080 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 LOCKED] is retur
10090 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 ned..** If the c
100a0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
100b0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 non-zero, then a
100c0 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a nother attempt.*
100d0 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 * is made to ope
100e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 n the database f
100f0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 or reading and t
10100 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 he cycle repeats
10110 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 ..**.** The pres
10120 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 ence of a busy h
10130 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 andler does not
10140 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 guarantee that i
10150 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 t will be invoke
10160 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 d.** when there
10170 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 is lock contenti
10180 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65 on. If SQLite de
10190 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e termines that in
101a0 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a voking the busy.
101b0 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 ** handler could
101c0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 result in a dea
101d0 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 dlock, it will g
101e0 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 o ahead and retu
101f0 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d rn [SQLITE_BUSY]
10200 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 .** or [SQLITE_I
10210 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e OERR_BLOCKED] in
10220 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e stead of invokin
10230 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c g the busy handl
10240 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 er..** Consider
10250 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 a scenario where
10260 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 one process is
10270 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c holding a read l
10280 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 ock that.** it i
10290 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d s trying to prom
102a0 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 ote to a reserve
102b0 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 d lock and.** a
102c0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 second process i
102d0 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 s holding a rese
102e0 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 rved lock that i
102f0 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 t is trying.** t
10300 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 o promote to an
10310 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 exclusive lock.
10320 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 The first proce
10330 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 ss cannot procee
10340 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 d.** because it
10350 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 is blocked by th
10360 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 e second and the
10370 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
10380 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 cannot.** procee
10390 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 d because it is
103a0 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 blocked by the f
103b0 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 irst. If both p
103c0 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f rocesses.** invo
103d0 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ke the busy hand
103e0 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 lers, neither wi
103f0 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 ll make any prog
10400 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 ress. Therefore
10410 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 ,.** SQLite retu
10420 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 rns [SQLITE_BUSY
10430 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 ] for the first
10440 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 process, hoping
10450 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c that this.** wil
10460 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 l induce the fir
10470 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 st process to re
10480 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c lease its read l
10490 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a ock and allow.**
104a0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 the second proc
104b0 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a ess to proceed..
104c0 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c **.** The defaul
104d0 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 t busy callback
104e0 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 is NULL..**.** T
104f0 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d he [SQLITE_BUSY]
10500 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 error is conver
10510 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 ted to [SQLITE_I
10520 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a OERR_BLOCKED].**
10530 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 when SQLite is
10540 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 in the middle of
10550 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 a large transac
10560 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 tion where all t
10570 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 he.** changes wi
10580 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 ll not fit into
10590 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 the in-memory ca
105a0 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c che. SQLite wil
105b0 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c l.** already hol
105c0 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 d a RESERVED loc
105d0 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 k on the databas
105e0 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e e file, but it n
105f0 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f eeds.** to promo
10600 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 te this lock to
10610 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 EXCLUSIVE so tha
10620 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 t it can spill c
10630 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e ache.** pages in
10640 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 to the database
10650 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 file without har
10660 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a m to concurrent.
10670 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 ** readers. If
10680 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 it is unable to
10690 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b promote the lock
106a0 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 , then the in-me
106b0 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 mory.** cache wi
106c0 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e ll be left in an
106d0 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 inconsistent st
106e0 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 ate and so the e
106f0 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 rror.** code is
10700 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 promoted from th
10710 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e e relatively ben
10720 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 ign [SQLITE_BUSY
10730 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 ] to.** the more
10740 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f severe [SQLITE_
10750 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 IOERR_BLOCKED].
10760 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 This error code
10770 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f promotion.** fo
10780 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 rces an automati
10790 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 c rollback of th
107a0 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 e changes. See
107b0 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 the.** <a href="
107c0 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d /cvstrac/wiki?p=
107d0 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 CorruptionFollow
107e0 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a ingBusyError">.*
107f0 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c * CorruptionFoll
10800 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f owingBusyError</
10810 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 a> wiki page for
10820 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 a discussion of
10830 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 why.** this is
10840 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a important..**.**
10850 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 There can only
10860 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 be a single busy
10870 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 handler defined
10880 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 for each.** [da
10890 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
108a0 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e n]. Setting a n
108b0 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 ew busy handler
108c0 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 clears any.** pr
108d0 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e eviously set han
108e0 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 dler. Note that
108f0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
10900 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 3_busy_timeout()
10910 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 ].** will also s
10920 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 et or clear the
10930 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a busy handler..**
10940 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c .** The busy cal
10950 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 lback should not
10960 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e take any action
10970 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 s which modify t
10980 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 he.** database c
10990 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 onnection that i
109a0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 nvoked the busy
109b0 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 handler. Any su
109c0 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 ch actions.** re
109d0 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 sult in undefine
109e0 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a d behavior..** .
109f0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
10a00 0a 2a 2a 20 5b 48 31 32 33 31 31 5d 20 5b 48 31 .** [H12311] [H1
10a10 32 33 31 32 5d 20 5b 48 31 32 33 31 34 5d 20 5b 2312] [H12314] [
10a20 48 31 32 33 31 36 5d 20 5b 48 31 32 33 31 38 5d H12316] [H12318]
10a30 0a 2a 2a 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 .**.** A busy ha
10a40 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 ndler must not c
10a50 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 lose the databas
10a60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
10a70 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 or [prepared sta
10a80 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 tement] that inv
10a90 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 oked the busy ha
10aa0 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ndler..*/.int sq
10ab0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
10ac0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 er(sqlite3*, int
10ad0 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 (*)(void*,int),
10ae0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
10af0 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 API3REF: Set A B
10b00 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 usy Timeout {H12
10b10 33 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 340} <S40410>.**
10b20 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
10b30 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 sets a [sqlite3
10b40 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 _busy_handler |
10b50 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 busy handler] th
10b60 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 at sleeps.** for
10b70 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f a specified amo
10b80 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e unt of time when
10b90 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b a table is lock
10ba0 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 ed. The handler
10bb0 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d .** will sleep m
10bc0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e ultiple times un
10bd0 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 til at least "ms
10be0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f " milliseconds o
10bf0 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 f sleeping.** ha
10c00 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 ve accumulated.
10c10 7b 48 31 32 33 34 33 7d 20 41 66 74 65 72 20 22 {H12343} After "
10c20 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 ms" milliseconds
10c30 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a of sleeping,.**
10c40 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 the handler ret
10c50 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 urns 0 which cau
10c60 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ses [sqlite3_ste
10c70 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a p()] to return.*
10c80 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 * [SQLITE_BUSY]
10c90 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 or [SQLITE_IOERR
10ca0 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a _BLOCKED]..**.**
10cb0 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f Calling this ro
10cc0 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 utine with an ar
10cd0 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e gument less than
10ce0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 or equal to zer
10cf0 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 o.** turns off a
10d00 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 ll busy handlers
10d10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 ..**.** There ca
10d20 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 n only be a sing
10d30 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 le busy handler
10d40 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 for a particular
10d50 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
10d60 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e nnection] any an
10d70 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 y given moment.
10d80 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 If another busy
10d90 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 handler.** was
10da0 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 defined (using
10db0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 [sqlite3_busy_ha
10dc0 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 ndler()]) prior
10dd0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 to calling.** th
10de0 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 is routine, that
10df0 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 other busy hand
10e00 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a ler is cleared..
10e10 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
10e20 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 34 31 5d 20 ts:.** [H12341]
10e30 5b 48 31 32 33 34 33 5d 20 5b 48 31 32 33 34 34 [H12343] [H12344
10e40 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ].*/.int sqlite3
10e50 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 _busy_timeout(sq
10e60 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b lite3*, int ms);
10e70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
10e80 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f : Convenience Ro
10e90 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 utines For Runni
10ea0 6e 67 20 51 75 65 72 69 65 73 20 7b 48 31 32 33 ng Queries {H123
10eb0 37 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 70} <S10000>.**.
10ec0 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 ** Definition: A
10ed0 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 <b>result table
10ee0 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 </b> is memory d
10ef0 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 ata structure cr
10f00 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 eated by the.**
10f10 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 [sqlite3_get_tab
10f20 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e le()] interface.
10f30 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 A result table
10f40 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 records the.**
10f50 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 complete query r
10f60 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 esults from one
10f70 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e or more queries.
10f80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 .**.** The table
10f90 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 conceptually ha
10fa0 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f s a number of ro
10fb0 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 ws and columns.
10fc0 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 But.** these nu
10fd0 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 mbers are not pa
10fe0 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 rt of the result
10ff0 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 table itself.
11000 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 These.** numbers
11010 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 are obtained se
11020 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e parately. Let N
11030 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f be the number o
11040 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 f rows.** and M
11050 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 be the number of
11060 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 columns..**.**
11070 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 A result table i
11080 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
11090 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 inters to zero-t
110a0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 erminated UTF-8
110b0 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 strings..** Ther
110c0 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c e are (N+1)*M el
110d0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 ements in the ar
110e0 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 ray. The first
110f0 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 M pointers point
11100 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d .** to zero-term
11110 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 inated strings t
11120 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 hat contain the
11130 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f names of the co
11140 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 lumns..** The re
11150 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 maining entries
11160 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 all point to que
11170 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c ry results. NUL
11180 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a L values result.
11190 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 ** in NULL point
111a0 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 ers. All other
111b0 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 values are in th
111c0 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 eir UTF-8 zero-t
111d0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 erminated.** str
111e0 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 ing representati
111f0 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 on as returned b
11200 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d y [sqlite3_colum
11210 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a n_text()]..**.**
11220 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
11230 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 might consist of
11240 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d one or more mem
11250 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e ory allocations.
11260 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 .** It is not sa
11270 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 fe to pass a res
11280 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 ult table direct
11290 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 ly to [sqlite3_f
112a0 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 ree()]..** A res
112b0 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 ult table should
112c0 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
112d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
112e0 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a ree_table()]..**
112f0 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c .** As an exampl
11300 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 e of the result
11310 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 table format, su
11320 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 ppose a query re
11330 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f sult.** is as fo
11340 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c llows:.**.** <bl
11350 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
11360 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 * Name
11370 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 | Age.**
11380 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d -----------
11390 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 ------------.**
113a0 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 Alice
113b0 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 | 43.**
113c0 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 Bob |
113d0 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 28.** Cin
113e0 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a dy | 21.**
113f0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
11400 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 ote>.**.** There
11410 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 are two column
11420 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 (M==2) and three
11430 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 rows (N==3). T
11440 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c hus the.** resul
11450 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e t table has 8 en
11460 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 tries. Suppose
11470 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 the result table
11480 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e is stored.** in
11490 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 an array names
114a0 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 azResult. Then
114b0 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 azResult holds t
114c0 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a his content:.**.
114d0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
114e0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 pre>.** a
114f0 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d zResult[0] =
11500 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 "Name";.**
11510 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
11520 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 1] = "Age";.**
11530 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
11540 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 91;2] = "Alice";
11550 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
11560 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 ult[3] = "43
11570 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
11580 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 esult[4] = "
11590 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 Bob";.**
115a0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 azResult[5]
115b0 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 = "28";.**
115c0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 azResult[6
115d0 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 ] = "Cindy";.**
115e0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
115f0 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a #91;7] = "21";.*
11600 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
11610 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 uote>.**.** The
11620 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
11630 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 e() function eva
11640 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f luates one or mo
11650 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d re.** semicolon-
11660 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 separated SQL st
11670 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 atements in the
11680 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
11690 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 UTF-8.** string
116a0 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d of its 2nd param
116b0 65 74 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e eter. It return
116c0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 s a result table
116d0 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 to the.** point
116e0 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 er given in its
116f0 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 3rd parameter..*
11700 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63 *.** After the c
11710 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 alling function
11720 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 has finished usi
11730 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69 ng the result, i
11740 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 t should.** pass
11750 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 the pointer to
11760 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 the result table
11770 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 to sqlite3_free
11780 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 _table() in orde
11790 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 r to.** release
117a0 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 the memory that
117b0 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 was malloced. B
117c0 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 ecause of the wa
117d0 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 y the.** [sqlite
117e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 3_malloc()] happ
117f0 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 ens within sqlit
11800 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 e3_get_table(),
11810 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 the calling.** f
11820 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 unction must not
11830 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 try to call [sq
11840 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 lite3_free()] di
11850 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a rectly. Only.**
11860 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 [sqlite3_free_t
11870 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 able()] is able
11880 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d to release the m
11890 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 emory properly a
118a0 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a nd safely..**.**
118b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 The sqlite3_get
118c0 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 _table() interfa
118d0 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 ce is implemente
118e0 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 d as a wrapper a
118f0 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 round.** [sqlite
11900 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 3_exec()]. The
11910 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
11920 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 e() routine does
11930 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 not have access
11940 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 .** to any inter
11950 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 nal data structu
11960 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 res of SQLite.
11970 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 It uses only the
11980 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 public.** inter
11990 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 face defined her
119a0 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 e. As a consequ
119b0 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 ence, errors tha
119c0 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a t occur in the.*
119d0 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 * wrapper layer
119e0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 outside of the i
119f0 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 nternal [sqlite3
11a00 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 _exec()] call ar
11a10 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 e not.** reflect
11a20 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 ed in subsequent
11a30 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
11a40 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 e3_errcode()] or
11a50 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
11a60 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ()]..**.** Requi
11a70 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 rements:.** [H12
11a80 33 37 31 5d 20 5b 48 31 32 33 37 33 5d 20 5b 48 371] [H12373] [H
11a90 31 32 33 37 34 5d 20 5b 48 31 32 33 37 36 5d 20 12374] [H12376]
11aa0 5b 48 31 32 33 37 39 5d 20 5b 48 31 32 33 38 32 [H12379] [H12382
11ab0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ].*/.int sqlite3
11ac0 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 _get_table(. sq
11ad0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
11ae0 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 /* An open d
11af0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e atabase */. con
11b00 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
11b10 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 /* SQL to be
11b20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 evaluated */. c
11b30 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 har ***pazResult
11b40 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 , /* Results
11b50 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a of the query */.
11b60 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 int *pnRow,
11b70 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 /* Numbe
11b80 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 r of result rows
11b90 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f written here */
11ba0 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e . int *pnColumn
11bb0 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 , /* Numb
11bc0 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c er of result col
11bd0 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 umns written her
11be0 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a e */. char **pz
11bf0 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 Errmsg /*
11c00 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 Error msg writte
11c10 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 n here */.);.voi
11c20 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 d sqlite3_free_t
11c30 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 able(char **resu
11c40 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 lt);../*.** CAPI
11c50 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 3REF: Formatted
11c60 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 String Printing
11c70 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 Functions {H1740
11c80 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 0} <S70000><S200
11c90 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 00>.**.** These
11ca0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 routines are wor
11cb0 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 kalikes of the "
11cc0 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 printf()" family
11cd0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a of functions.**
11ce0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 from the standa
11cf0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a rd C library..**
11d00 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
11d10 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 mprintf() and sq
11d20 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 lite3_vmprintf()
11d30 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 routines write
11d40 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 their.** results
11d50 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 into memory obt
11d60 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
11d70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a te3_malloc()]..*
11d80 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 * The strings re
11d90 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 turned by these
11da0 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f two routines sho
11db0 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 uld be.** releas
11dc0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 ed by [sqlite3_f
11dd0 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f ree()]. Both ro
11de0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a utines return a.
11df0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 ** NULL pointer
11e00 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c if [sqlite3_mall
11e10 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 oc()] is unable
11e20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 to allocate enou
11e30 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 gh.** memory to
11e40 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 hold the resulti
11e50 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a ng string..**.**
11e60 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 In sqlite3_snpr
11e70 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 intf() routine i
11e80 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e s similar to "sn
11e90 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a printf()" from.*
11ea0 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 * the standard C
11eb0 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 library. The r
11ec0 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e esult is written
11ed0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 into the.** buf
11ee0 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 fer supplied as
11ef0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
11f00 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 eter whose size
11f10 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 is given by.** t
11f20 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
11f30 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 er. Note that th
11f40 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a e order of the.*
11f50 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 * first two para
11f60 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 meters is revers
11f70 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 ed from snprintf
11f80 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a (). This is an.
11f90 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 ** historical ac
11fa0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e cident that cann
11fb0 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 ot be fixed with
11fc0 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 out breaking.**
11fd0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
11fe0 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 ibility. Note a
11ff0 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 lso that sqlite3
12000 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 _snprintf().** r
12010 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
12020 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 to its buffer i
12030 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 nstead of the nu
12040 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 mber of.** chara
12050 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 cters actually w
12060 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 ritten into the
12070 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69 buffer. We admi
12080 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 t that.** the nu
12090 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 mber of characte
120a0 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 rs written would
120b0 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 be a more usefu
120c0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 l return.** valu
120d0 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 e but we cannot
120e0 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 change the imple
120f0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c mentation of sql
12100 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a ite3_snprintf().
12110 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 ** now without b
12120 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 reaking compatib
12130 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 ility..**.** As
12140 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 long as the buff
12150 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 er size is great
12160 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 er than zero, sq
12170 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
12180 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 .** guarantees t
12190 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 hat the buffer i
121a0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 s always zero-te
121b0 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66 rminated. The f
121c0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 irst.** paramete
121d0 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 r "n" is the tot
121e0 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 al size of the b
121f0 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 uffer, including
12200 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 space for.** th
12210 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f e zero terminato
12220 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 r. So the longe
12230 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 st string that c
12240 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 an be completely
12250 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c .** written will
12260 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 be n-1 characte
12270 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 rs..**.** These
12280 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 routines all imp
12290 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 lement some addi
122a0 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e tional formattin
122b0 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 g.** options tha
122c0 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 t are useful for
122d0 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 constructing SQ
122e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a L statements..**
122f0 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 All of the usua
12300 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 l printf() forma
12310 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 tting options ap
12320 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f ply. In additio
12330 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 n, there.** is a
12340 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 re "%q", "%Q", a
12350 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e nd "%z" options.
12360 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 .**.** The %q op
12370 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 tion works like
12380 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 %s in that it su
12390 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c bstitutes a null
123a0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 -terminated.** s
123b0 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 tring from the a
123c0 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 rgument list. B
123d0 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c ut %q also doubl
123e0 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 es every '\'' ch
123f0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 aracter..** %q i
12400 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 s designed for u
12410 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 se inside a stri
12420 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 ng literal. By
12430 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c doubling each '\
12440 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 ''.** character
12450 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 it escapes that
12460 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c character and al
12470 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e lows it to be in
12480 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 serted into.** t
12490 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a he string..**.**
124a0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 For example, as
124b0 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 sume the string
124c0 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 variable zText c
124d0 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 ontains text as
124e0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
124f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
12500 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 .** char *zText
12510 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 = "It's a happy
12520 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 day!";.** </pre
12530 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
12540 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 *.** One can use
12550 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e this text in an
12560 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 SQL statement a
12570 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
12580 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
12590 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 e>.** char *zSQ
125a0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 L = sqlite3_mpri
125b0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f ntf("INSERT INTO
125c0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 table VALUES('%
125d0 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a q')", zText);.**
125e0 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 sqlite3_exec(d
125f0 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 b, zSQL, 0, 0, 0
12600 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 );.** sqlite3_f
12610 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f ree(zSQL);.** </
12620 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
12630 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 >.**.** Because
12640 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 the %q format st
12650 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 ring is used, th
12660 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 e '\'' character
12670 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 in zText.** is
12680 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 escaped and the
12690 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 SQL generated is
126a0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
126b0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
126c0 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 pre>.** INSERT
126d0 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 INTO table1 VALU
126e0 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 ES('It''s a happ
126f0 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 y day!').** </pr
12700 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
12710 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f **.** This is co
12720 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 rrect. Had we u
12730 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f sed %s instead o
12740 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 f %q, the genera
12750 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 ted SQL.** would
12760 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b have looked lik
12770 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 e this:.**.** <b
12780 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
12790 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 ** INSERT INTO
127a0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 table1 VALUES('I
127b0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 t's a happy day!
127c0 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 ');.** </pre></b
127d0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
127e0 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 This second exa
127f0 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 mple is an SQL s
12800 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 yntax error. As
12810 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 a general rule
12820 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c you should.** al
12830 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 ways use %q inst
12840 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 ead of %s when i
12850 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e nserting text in
12860 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 to a string lite
12870 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 ral..**.** The %
12880 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c Q option works l
12890 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 ike %q except it
128a0 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c also adds singl
128b0 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a e quotes around.
128c0 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f ** the outside o
128d0 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 f the total stri
128e0 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c ng. Additionall
128f0 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 y, if the parame
12900 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 ter in the.** ar
12910 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 gument list is a
12920 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 NULL pointer, %
12930 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 Q substitutes th
12940 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 e text "NULL" (w
12950 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 ithout.** single
12960 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 quotes) in plac
12970 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69 e of the %Q opti
12980 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 on. So, for exa
12990 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 mple, one could
129a0 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 say:.**.** <bloc
129b0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
129c0 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 char *zSQL = sq
129d0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 lite3_mprintf("I
129e0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 NSERT INTO table
129f0 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 VALUES(%Q)", zT
12a00 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 ext);.** sqlite
12a10 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 3_exec(db, zSQL,
12a20 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 0, 0, 0);.** s
12a30 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c qlite3_free(zSQL
12a40 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
12a50 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
12a60 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 The code above w
12a70 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 ill render a cor
12a80 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 rect SQL stateme
12a90 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a nt in the zSQL.*
12aa0 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 * variable even
12ab0 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 if the zText var
12ac0 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 iable is a NULL
12ad0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 pointer..**.** T
12ae0 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 he "%z" formatti
12af0 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 ng option works
12b00 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 exactly like "%s
12b10 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 " with the.** ad
12b20 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 dition that afte
12b30 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 r the string has
12b40 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 been read and c
12b50 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 opied into.** th
12b60 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 e result, [sqlit
12b70 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 e3_free()] is ca
12b80 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 lled on the inpu
12b90 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a t string. {END}.
12ba0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
12bb0 74 73 3a 0a 2a 2a 20 5b 48 31 37 34 30 33 5d 20 ts:.** [H17403]
12bc0 5b 48 31 37 34 30 36 5d 20 5b 48 31 37 34 30 37 [H17406] [H17407
12bd0 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 ].*/.char *sqlit
12be0 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 e3_mprintf(const
12bf0 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 char*,...);.cha
12c00 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 r *sqlite3_vmpri
12c10 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c ntf(const char*,
12c20 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 va_list);.char
12c30 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 *sqlite3_snprint
12c40 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 f(int,char*,cons
12c50 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a t char*, ...);..
12c60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
12c70 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f Memory Allocatio
12c80 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 48 31 37 n Subsystem {H17
12c90 33 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 300} <S20000>.**
12ca0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 .** The SQLite c
12cb0 6f 72 65 20 20 75 73 65 73 20 74 68 65 73 65 20 ore uses these
12cc0 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 three routines f
12cd0 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 or all of its ow
12ce0 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 n.** internal me
12cf0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
12d00 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e needs. "Core" in
12d10 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 the previous se
12d20 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e ntence.** does n
12d30 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 ot include opera
12d40 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 ting-system spec
12d50 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 ific VFS impleme
12d60 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a ntation. The.**
12d70 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 Windows VFS use
12d80 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 s native malloc(
12d90 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 ) and free() for
12da0 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 some operations
12db0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
12dc0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 te3_malloc() rou
12dd0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 tine returns a p
12de0 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 ointer to a bloc
12df0 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 k.** of memory a
12e00 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 t least N bytes
12e10 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 in length, where
12e20 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 N is the parame
12e30 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 ter..** If sqlit
12e40 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 e3_malloc() is u
12e50 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 nable to obtain
12e60 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a sufficient free.
12e70 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 ** memory, it re
12e80 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
12e90 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20 70 61 nter. If the pa
12ea0 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 rameter N to.**
12eb0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
12ec0 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 is zero or nega
12ed0 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 tive then sqlite
12ee0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 3_malloc() retur
12ef0 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 ns.** a NULL poi
12f00 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c nter..**.** Call
12f10 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 ing sqlite3_free
12f20 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 () with a pointe
12f30 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 r previously ret
12f40 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 urned.** by sqli
12f50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 te3_malloc() or
12f60 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
12f70 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 ) releases that
12f80 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 memory so.** tha
12f90 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 t it might be re
12fa0 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 used. The sqlit
12fb0 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e e3_free() routin
12fc0 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 e is.** a no-op
12fd0 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 if is called wit
12fe0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 h a NULL pointer
12ff0 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c . Passing a NUL
13000 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 L pointer.** to
13010 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 sqlite3_free() i
13020 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 s harmless. Aft
13030 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 er being freed,
13040 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 memory.** should
13050 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 neither be read
13060 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 nor written. E
13070 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 ven reading prev
13080 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 iously freed.**
13090 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 memory might res
130a0 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 ult in a segment
130b0 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f ation fault or o
130c0 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f ther severe erro
130d0 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 r..** Memory cor
130e0 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 ruption, a segme
130f0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f ntation fault, o
13100 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 r other severe e
13110 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 rror.** might re
13120 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f sult if sqlite3_
13130 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 free() is called
13140 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c with a non-NULL
13150 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a pointer that.**
13160 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 was not obtaine
13170 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d d from sqlite3_m
13180 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 alloc() or sqlit
13190 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a e3_realloc()..**
131a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
131b0 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 realloc() interf
131c0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ace attempts to
131d0 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f resize a.** prio
131e0 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 r memory allocat
131f0 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 ion to be at lea
13200 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 st N bytes, wher
13210 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 e N is the.** se
13220 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 cond parameter.
13230 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f The memory allo
13240 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 cation to be res
13250 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 ized is the firs
13260 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 t.** parameter.
13270 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 If the first pa
13280 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
13290 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 e3_realloc().**
132a0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
132b0 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 r then its behav
132c0 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c ior is identical
132d0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 to calling.** s
132e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 qlite3_malloc(N)
132f0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 where N is the
13300 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
13310 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c to sqlite3_real
13320 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 loc()..** If the
13330 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
13340 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 r to sqlite3_rea
13350 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f lloc() is zero o
13360 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 r.** negative th
13370 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
13380 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 is exactly the s
13390 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a ame as calling.*
133a0 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 * sqlite3_free(P
133b0 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 ) where P is the
133c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
133d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c to sqlite3_real
133e0 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 loc()..** sqlite
133f0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 3_realloc() retu
13400 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
13410 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
13420 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 tion.** of at le
13430 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 ast N bytes in s
13440 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 ize or NULL if s
13450 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 ufficient memory
13460 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e is unavailable.
13470 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 .** If M is the
13480 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f size of the prio
13490 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 r allocation, th
134a0 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 en min(N,M) byte
134b0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f s.** of the prio
134c0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 r allocation are
134d0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 copied into the
134e0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 beginning of bu
134f0 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a ffer returned.**
13500 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c by sqlite3_real
13510 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 loc() and the pr
13520 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 ior allocation i
13530 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 s freed..** If s
13540 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
13550 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 returns NULL, t
13560 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c hen the prior al
13570 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e location.** is n
13580 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 ot freed..**.**
13590 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 The memory retur
135a0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d ned by sqlite3_m
135b0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 alloc() and sqli
135c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a te3_realloc().**
135d0 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e is always align
135e0 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 ed to at least a
135f0 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 n 8 byte boundar
13600 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 y. {END}.**.** T
13610 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 he default imple
13620 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 mentation of the
13630 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
13640 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65 on subsystem use
13650 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 s.** the malloc(
13660 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 ), realloc() and
13670 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64 free() provided
13680 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64 by the standard
13690 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b C library..** {
136a0 48 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c H17382} However,
136b0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f if SQLite is co
136c0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a mpiled with the.
136d0 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 ** SQLITE_MEMORY
136e0 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e _SIZE=<i>NNN</i>
136f0 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C preprocessor
13700 6d 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e macro (where <i>
13710 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e NNN</i>.** is an
13720 20 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20 integer), then
13730 53 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 SQLite create a
13740 73 74 61 74 69 63 20 61 72 72 61 79 20 6f 66 20 static array of
13750 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e at least.** <i>N
13760 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 NN</i> bytes in
13770 73 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68 size and uses th
13780 61 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c at array for all
13790 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a of its dynamic.
137a0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
137b0 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 tion needs. {END
137c0 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 } Additional me
137d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f mory allocator o
137e0 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 ptions.** may be
137f0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
13800 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a releases..**.**
13810 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 In SQLite versi
13820 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 on 3.5.0 and 3.5
13830 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 .1, it was possi
13840 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a ble to define.**
13850 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 the SQLITE_OMIT
13860 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 _MEMORY_ALLOCATI
13870 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 ON which would c
13880 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 ause the built-i
13890 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 n.** implementat
138a0 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 ion of these rou
138b0 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 tines to be omit
138c0 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 ted. That capab
138d0 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c ility.** is no l
138e0 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 onger provided.
138f0 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d Only built-in m
13900 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 emory allocators
13910 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a can be used..**
13920 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 .** The Windows
13930 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 OS interface lay
13940 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 er calls.** the
13950 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 system malloc()
13960 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 and free() direc
13970 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 tly when convert
13980 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 ing.** filenames
13990 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 between the UTF
139a0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 -8 encoding used
139b0 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e by SQLite.** an
139c0 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e d whatever filen
139d0 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 ame encoding is
139e0 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 used by the part
139f0 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a icular Windows.*
13a00 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 * installation.
13a10 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 Memory allocati
13a20 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 on errors are de
13a30 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 tected, but.** t
13a40 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 hey are reported
13a50 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 back as [SQLITE
13a60 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a _CANTOPEN] or.**
13a70 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 [SQLITE_IOERR]
13a80 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c rather than [SQL
13a90 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a ITE_NOMEM]..**.*
13aa0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
13ab0 2a 2a 20 5b 48 31 37 33 30 33 5d 20 5b 48 31 37 ** [H17303] [H17
13ac0 33 30 34 5d 20 5b 48 31 37 33 30 35 5d 20 5b 48 304] [H17305] [H
13ad0 31 37 33 30 36 5d 20 5b 48 31 37 33 31 30 5d 20 17306] [H17310]
13ae0 5b 48 31 37 33 31 32 5d 20 5b 48 31 37 33 31 35 [H17312] [H17315
13af0 5d 20 5b 48 31 37 33 31 38 5d 0a 2a 2a 20 5b 48 ] [H17318].** [H
13b00 31 37 33 32 31 5d 20 5b 48 31 37 33 32 32 5d 20 17321] [H17322]
13b10 5b 48 31 37 33 32 33 5d 0a 2a 2a 0a 2a 2a 20 54 [H17323].**.** T
13b20 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d he pointer argum
13b30 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 ents to [sqlite3
13b40 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 _free()] and [sq
13b50 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
13b60 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 .** must be eith
13b70 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 er NULL or else
13b80 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 pointers obtaine
13b90 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a d from a prior.*
13ba0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 * invocation of
13bb0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
13bc0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
13bd0 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 ealloc()] that h
13be0 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 ave.** not yet b
13bf0 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a een released..**
13c00 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
13c10 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 ion must not rea
13c20 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 d or write any p
13c30 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 art of.** a bloc
13c40 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 k of memory afte
13c50 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 r it has been re
13c60 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 leased using.**
13c70 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
13c80 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
13c90 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 lloc()]..*/.void
13ca0 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 *sqlite3_malloc
13cb0 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c (int);.void *sql
13cc0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 ite3_realloc(voi
13cd0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 d*, int);.void s
13ce0 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 qlite3_free(void
13cf0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
13d00 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f REF: Memory Allo
13d10 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 cator Statistics
13d20 20 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 31 {H17370} <S3021
13d30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 0>.**.** SQLite
13d40 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 provides these t
13d50 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f wo interfaces fo
13d60 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 r reporting on t
13d70 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 he status.** of
13d80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c the [sqlite3_mal
13d90 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 loc()], [sqlite3
13da0 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 _free()], and [s
13db0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
13dc0 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 ].** routines, w
13dd0 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 hich form the bu
13de0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c ilt-in memory al
13df0 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 location subsyst
13e00 65 6d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 em..**.** Requir
13e10 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 ements:.** [H173
13e20 37 31 5d 20 5b 48 31 37 33 37 33 5d 20 5b 48 31 71] [H17373] [H1
13e30 37 33 37 34 5d 20 5b 48 31 37 33 37 35 5d 0a 2a 7374] [H17375].*
13e40 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 /.sqlite3_int64
13e50 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
13e60 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 sed(void);.sqlit
13e70 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e3_int64 sqlite3
13e80 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
13e90 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 r(int resetFlag)
13ea0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
13eb0 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d F: Pseudo-Random
13ec0 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f Number Generato
13ed0 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 30 30 r {H17390} <S200
13ee0 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 00>.**.** SQLite
13ef0 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 contains a high
13f00 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d -quality pseudo-
13f10 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 random number ge
13f20 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 nerator (PRNG) u
13f30 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 sed to.** select
13f40 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c random [ROWID |
13f50 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e ROWIDs] when in
13f60 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f serting new reco
13f70 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 rds into a table
13f80 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 that.** already
13f90 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 uses the larges
13fa0 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 t possible [ROWI
13fb0 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 D]. The PRNG is
13fc0 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a also used for.*
13fd0 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 * the build-in r
13fe0 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 andom() and rand
13ff0 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e omblob() SQL fun
14000 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e ctions. This in
14010 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a terface allows.*
14020 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 * applications t
14030 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d o access the sam
14040 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 e PRNG for other
14050 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a purposes..**.**
14060 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 A call to this
14070 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e routine stores N
14080 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d bytes of random
14090 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 ness into buffer
140a0 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 P..**.** The fi
140b0 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f rst time this ro
140c0 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 utine is invoked
140d0 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 (either interna
140e0 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 lly or by.** the
140f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 application) th
14100 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 e PRNG is seeded
14110 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 using randomnes
14120 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 s obtained.** fr
14130 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 om the xRandomne
14140 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 ss method of the
14150 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 default [sqlite
14160 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 3_vfs] object..*
14170 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 * On all subsequ
14180 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c ent invocations,
14190 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 the pseudo-rand
141a0 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 omness is genera
141b0 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c ted.** internall
141c0 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 y and without re
141d0 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 course to the [s
141e0 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e qlite3_vfs] xRan
141f0 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f domness.** metho
14200 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 d..**.** Require
14210 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 39 ments:.** [H1739
14220 32 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 2].*/.void sqlit
14230 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e e3_randomness(in
14240 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a t N, void *P);..
14250 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
14260 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 Compile-Time Aut
14270 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 horization Callb
14280 61 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c 53 acks {H12500} <S
14290 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 70100>.**.** Thi
142a0 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 s routine regist
142b0 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 ers a authorizer
142c0 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 callback with a
142d0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b particular.** [
142e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
142f0 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 ion], supplied i
14300 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
14310 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 ment..** The aut
14320 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
14330 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 is invoked as S
14340 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 QL statements ar
14350 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 e being compiled
14360 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f .** by [sqlite3_
14370 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 prepare()] or it
14380 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 s variants [sqli
14390 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
143a0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 ],.** [sqlite3_p
143b0 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 repare16()] and
143c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
143d0 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 16_v2()]. At va
143e0 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 rious.** points
143f0 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 during the compi
14400 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 lation process,
14410 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e as logic is bein
14420 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 g created.** to
14430 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 perform various
14440 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 actions, the aut
14450 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
14460 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a is invoked to.*
14470 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 * see if those a
14480 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 ctions are allow
14490 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 ed. The authori
144a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f zer callback sho
144b0 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 uld.** return [S
144c0 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c QLITE_OK] to all
144d0 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b ow the action, [
144e0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 SQLITE_IGNORE] t
144f0 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a o disallow the.*
14500 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f * specific actio
14510 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 n but allow the
14520 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f SQL statement to
14530 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a continue to be.
14540 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 ** compiled, or
14550 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f [SQLITE_DENY] to
14560 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 cause the entir
14570 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
14580 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 to be.** rejecte
14590 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e d with an error.
145a0 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 If the authori
145b0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 zer callback ret
145c0 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 urns.** any valu
145d0 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 e other than [SQ
145e0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 LITE_IGNORE], [S
145f0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 QLITE_OK], or [S
14600 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 QLITE_DENY].** t
14610 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 hen the [sqlite3
14620 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
14630 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c r equivalent cal
14640 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 l that triggered
14650 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a .** the authoriz
14660 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 er will fail wit
14670 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 h an error messa
14680 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 ge..**.** When t
14690 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
146a0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c rns [SQLITE_OK],
146b0 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 that means the
146c0 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 operation.** req
146d0 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 uested is ok. W
146e0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
146f0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
14700 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b _DENY], the.** [
14710 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
14720 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c v2()] or equival
14730 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 ent call that tr
14740 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 iggered the.** a
14750 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 uthorizer will f
14760 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f ail with an erro
14770 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 r message explai
14780 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 ning that.** acc
14790 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a ess is denied. .
147a0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
147b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
147c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
147d0 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f back is a copy o
147e0 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 f the third.** p
147f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
14800 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
14810 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 orizer() interfa
14820 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 ce. The second p
14830 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 arameter.** to t
14840 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 he callback is a
14850 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 n integer [SQLIT
14860 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 E_COPY | action
14870 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 code] that speci
14880 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 fies.** the part
14890 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f icular action to
148a0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 be authorized.
148b0 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 The third throug
148c0 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 h sixth paramete
148d0 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c rs.** to the cal
148e0 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 lback are zero-t
148f0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 erminated string
14900 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 s that contain a
14910 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 dditional.** det
14920 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 ails about the a
14930 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 ction to be auth
14940 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 orized..**.** If
14950 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 the action code
14960 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 is [SQLITE_READ
14970 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c ].** and the cal
14980 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 lback returns [S
14990 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 QLITE_IGNORE] th
149a0 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 en the.** [prepa
149b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 red statement] s
149c0 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 tatement is cons
149d0 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 tructed to subst
149e0 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 itute.** a NULL
149f0 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f value in place o
14a00 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 f the table colu
14a10 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 mn that would ha
14a20 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 ve.** been read
14a30 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 if [SQLITE_OK] h
14a40 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 ad been returned
14a50 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 . The [SQLITE_I
14a60 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e GNORE].** return
14a70 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
14a80 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 deny an untruste
14a90 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f d user access to
14aa0 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 individual.** c
14ab0 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c olumns of a tabl
14ac0 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 61 63 74 e..** If the act
14ad0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c ion code is [SQL
14ae0 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 ITE_DELETE] and
14af0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
14b00 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f urns.** [SQLITE_
14b10 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 IGNORE] then the
14b20 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 [DELETE] operat
14b30 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 ion proceeds but
14b40 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 the.** [truncat
14b50 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 e optimization]
14b60 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 is disabled and
14b70 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c all rows are del
14b80 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c eted individuall
14b90 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 y..**.** An auth
14ba0 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 orizer is used w
14bb0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hen [sqlite3_pre
14bc0 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 pare | preparing
14bd0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 ].** SQL stateme
14be0 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 nts from an untr
14bf0 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f usted source, to
14c00 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 ensure that the
14c10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
14c20 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f ** do not try to
14c30 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 access data the
14c40 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 y are not allowe
14c50 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 d to see, or tha
14c60 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a t they do not.**
14c70 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 try to execute
14c80 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d malicious statem
14c90 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 ents that damage
14ca0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 the database.
14cb0 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 For.** example,
14cc0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d an application m
14cd0 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 ay allow a user
14ce0 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 to enter arbitra
14cf0 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 ry.** SQL querie
14d00 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e s for evaluation
14d10 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 by a database.
14d20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 But the applica
14d30 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 tion does.** not
14d40 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 want the user t
14d50 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b o be able to mak
14d60 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e e arbitrary chan
14d70 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 ges to the.** da
14d80 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 tabase. An auth
14d90 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 orizer could the
14da0 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 n be put in plac
14db0 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 e while the.** u
14dc0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 ser-entered SQL
14dd0 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 is being [sqlite
14de0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 3_prepare | prep
14df0 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 ared] that.** di
14e00 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 sallows everythi
14e10 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 ng except [SELEC
14e20 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a T] statements..*
14e30 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e *.** Application
14e40 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 s that need to p
14e50 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 rocess SQL from
14e60 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 untrusted source
14e70 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 s.** might also
14e80 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e consider lowerin
14e90 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 g resource limit
14ea0 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 s using [sqlite3
14eb0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 _limit()].** and
14ec0 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 limiting databa
14ed0 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 se size using th
14ee0 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e e [max_page_coun
14ef0 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 t] [PRAGMA].** i
14f00 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 n addition to us
14f10 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 ing an authorize
14f20 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 r..**.** Only a
14f30 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 single authorize
14f40 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 r can be in plac
14f50 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 e on a database
14f60 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 connection.** at
14f70 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 a time. Each c
14f80 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
14f90 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 et_authorizer ov
14fa0 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 errides the.** p
14fb0 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 revious call. D
14fc0 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f isable the autho
14fd0 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c rizer by install
14fe0 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 ing a NULL callb
14ff0 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 ack..** The auth
15000 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c orizer is disabl
15010 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a ed by default..*
15020 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 *.** The authori
15030 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 zer callback mus
15040 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e t not do anythin
15050 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 g that will modi
15060 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 fy.** the databa
15070 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
15080 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 at invoked the a
15090 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
150a0 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 ck..** Note that
150b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
150c0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c e_v2()] and [sql
150d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 ite3_step()] bot
150e0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a h modify their.*
150f0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
15100 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d ctions for the m
15110 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 eaning of "modif
15120 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 y" in this parag
15130 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e raph..**.** When
15140 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
15150 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 e_v2()] is used
15160 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 to prepare a sta
15170 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 tement, the.** s
15180 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 tatement might b
15190 65 20 72 65 70 72 65 70 61 72 65 64 20 64 75 72 e reprepared dur
151a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ing [sqlite3_ste
151b0 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a p()] due to a .*
151c0 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e * schema change.
151d0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 Hence, the app
151e0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
151f0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a ensure that the.
15200 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f ** correct autho
15210 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 rizer callback r
15220 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 emains in place
15230 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 during the [sqli
15240 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a te3_step()]..**.
15250 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 ** Note that the
15260 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
15270 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
15280 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b only during.** [
15290 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
152a0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e )] or its varian
152b0 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 ts. Authorizati
152c0 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 on is not.** per
152d0 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 formed during st
152e0 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 atement evaluati
152f0 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 on in [sqlite3_s
15300 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a tep()], unless.*
15310 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 * as stated in t
15320 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 he previous para
15330 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 graph, sqlite3_s
15340 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a tep() invokes.**
15350 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
15360 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 _v2() to reprepa
15370 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 re a statement a
15380 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 fter a schema ch
15390 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 ange..**.** Requ
153a0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
153b0 32 35 30 31 5d 20 5b 48 31 32 35 30 32 5d 20 5b 2501] [H12502] [
153c0 48 31 32 35 30 33 5d 20 5b 48 31 32 35 30 34 5d H12503] [H12504]
153d0 20 5b 48 31 32 35 30 35 5d 20 5b 48 31 32 35 30 [H12505] [H1250
153e0 36 5d 20 5b 48 31 32 35 30 37 5d 20 5b 48 31 32 6] [H12507] [H12
153f0 35 31 30 5d 0a 2a 2a 20 5b 48 31 32 35 31 31 5d 510].** [H12511]
15400 20 5b 48 31 32 35 31 32 5d 20 5b 48 31 32 35 32 [H12512] [H1252
15410 30 5d 20 5b 48 31 32 35 32 31 5d 20 5b 48 31 32 0] [H12521] [H12
15420 35 32 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 522].*/.int sqli
15430 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
15440 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a er(. sqlite3*,.
15450 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 int (*xAuth)(v
15460 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 oid*,int,const c
15470 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
15480 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e ,const char*,con
15490 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 st char*),. voi
154a0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a d *pUserData.);.
154b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
154c0 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 Authorizer Retu
154d0 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30 rn Codes {H12590
154e0 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a } <H12500>.**.**
154f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
15500 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 t_authorizer | a
15510 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
15520 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 ck function] mus
15530 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 t.** return eith
15540 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f er [SQLITE_OK] o
15550 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 r one of these t
15560 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 wo constants in
15570 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e order.** to sign
15580 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 al SQLite whethe
15590 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 r or not the act
155a0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 ion is permitted
155b0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 . See the.** [s
155c0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
155d0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
155e0 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e er documentation
155f0 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c ] for additional
15600 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e .** information.
15610 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
15620 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a TE_DENY 1 /*
15630 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 Abort the SQL s
15640 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e tatement with an
15650 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e error */.#defin
15660 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 e SQLITE_IGNORE
15670 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 2 /* Don't all
15680 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 ow access, but d
15690 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e on't generate an
156a0 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a error */../*.**
156b0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f CAPI3REF: Autho
156c0 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 rizer Action Cod
156d0 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 es {H12550} <H12
156e0 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 500>.**.** The [
156f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
15700 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 orizer()] interf
15710 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 ace registers a
15720 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
15730 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 n.** that is inv
15740 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a oked to authoriz
15750 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 e certain SQL st
15760 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e atement actions.
15770 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 The.** second
15780 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
15790 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
157a0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 integer code tha
157b0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 t specifies.** w
157c0 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 hat action is be
157d0 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 ing authorized.
157e0 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 These are the i
157f0 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f nteger action co
15800 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 des that.** the
15810 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
15820 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 ack may be passe
15830 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 d..**.** These a
15840 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 ction code value
15850 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b s signify what k
15860 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e ind of operation
15870 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 is to be.** aut
15880 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 horized. The 3r
15890 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 d and 4th parame
158a0 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 ters to the auth
158b0 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c orization.** cal
158c0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 lback function w
158d0 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 ill be parameter
158e0 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 s or NULL depend
158f0 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 ing on which of
15900 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 these.** codes i
15910 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 s used as the se
15920 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 cond parameter.
15930 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 The 5th paramet
15940 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 er to the.** aut
15950 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
15960 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
15970 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d the database ("m
15980 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a ain", "temp",.**
15990 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 etc.) if applic
159a0 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 able. The 6th p
159b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
159c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
159d0 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 ack.** is the na
159e0 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d me of the inner-
159f0 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 most trigger or
15a00 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 view that is res
15a10 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 ponsible for.**
15a20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d the access attem
15a30 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 pt or NULL if th
15a40 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 is access attemp
15a50 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 t is directly fr
15a60 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 om.** top-level
15a70 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 SQL code..**.**
15a80 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
15a90 20 5b 48 31 32 35 35 31 5d 20 5b 48 31 32 35 35 [H12551] [H1255
15aa0 32 5d 20 5b 48 31 32 35 35 33 5d 20 5b 48 31 32 2] [H12553] [H12
15ab0 35 35 34 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 554].*/./*******
15ac0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
15ad0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
15ae0 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a **** 3rd *******
15af0 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a ***** 4th ******
15b00 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 *****/.#define S
15b10 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 QLITE_CREATE_IND
15b20 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 EX 1
15b30 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
15b40 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
15b50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
15b60 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c LITE_CREATE_TABL
15b70 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f E 2 /
15b80 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
15b90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
15ba0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
15bb0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
15bc0 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a INDEX 3 /*
15bd0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
15be0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
15bf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
15c00 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 TE_CREATE_TEMP_T
15c10 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 ABLE 4 /*
15c20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
15c30 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
15c40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
15c50 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 E_CREATE_TEMP_TR
15c60 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 IGGER 5 /* T
15c70 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
15c80 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
15c90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
15ca0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 _CREATE_TEMP_VIE
15cb0 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 W 6 /* Vi
15cc0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
15cd0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
15ce0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
15cf0 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 CREATE_TRIGGER
15d00 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 7 /* Tri
15d10 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
15d20 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
15d30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
15d40 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 REATE_VIEW
15d50 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 8 /* View
15d60 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
15d70 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
15d80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
15d90 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 LETE
15da0 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 9 /* Table
15db0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
15dc0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
15dd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
15de0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 P_INDEX
15df0 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 10 /* Index
15e00 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
15e10 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
15e20 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
15e30 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 _TABLE
15e40 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 11 /* Table N
15e50 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
15e60 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
15e70 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
15e80 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 TEMP_INDEX
15e90 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 12 /* Index Na
15ea0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
15eb0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
15ec0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
15ed0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 EMP_TABLE 1
15ee0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 3 /* Table Nam
15ef0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
15f00 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
15f10 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
15f20 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 MP_TRIGGER 14
15f30 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
15f40 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
15f50 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
15f60 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
15f70 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 P_VIEW 15
15f80 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
15f90 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
15fa0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
15fb0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 SQLITE_DROP_TRIG
15fc0 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 GER 16
15fd0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
15fe0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
15ff0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
16000 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 QLITE_DROP_VIEW
16010 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 17
16020 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
16030 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
16040 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
16050 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 LITE_INSERT
16060 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 18 /
16070 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
16080 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
16090 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
160a0 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 ITE_PRAGMA
160b0 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 19 /*
160c0 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 Pragma Name
160d0 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 1st arg or NULL
160e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
160f0 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 TE_READ
16100 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 20 /*
16110 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
16120 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 Column Name
16130 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16140 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 E_SELECT
16150 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 21 /* N
16160 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e ULL N
16170 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
16180 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16190 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 _TRANSACTION
161a0 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 22 /* Op
161b0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 eration NU
161c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
161d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
161e0 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 UPDATE
161f0 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 23 /* Tab
16200 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c le Name Col
16210 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a umn Name */.
16220 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
16230 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 TTACH
16240 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 24 /* File
16250 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c name NULL
16260 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
16270 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
16280 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 TACH
16290 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 25 /* Datab
162a0 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 ase Name NULL
162b0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
162c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 efine SQLITE_ALT
162d0 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 ER_TABLE
162e0 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 26 /* Databa
162f0 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 se Name Table
16300 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
16310 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e fine SQLITE_REIN
16320 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 DEX
16330 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 27 /* Index N
16340 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
16350 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
16360 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 ine SQLITE_ANALY
16370 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ZE
16380 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 28 /* Table Na
16390 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
163a0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
163b0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
163c0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 _VTABLE 2
163d0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 9 /* Table Nam
163e0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 e Module Na
163f0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
16400 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 e SQLITE_DROP_VT
16410 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 ABLE 30
16420 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
16430 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d Module Nam
16440 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
16450 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e SQLITE_FUNCTION
16460 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 31
16470 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 /* NULL
16480 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 Function Na
16490 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 me */.#define
164a0 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 SQLITE_SAVEPOINT
164b0 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 32
164c0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 /* Operation
164d0 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 Savepoint Na
164e0 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 me */.#define S
164f0 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 QLITE_COPY
16500 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 0
16510 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 /* No longer use
16520 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d */../*.** CAPI
16530 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 3REF: Tracing An
16540 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 d Profiling Func
16550 74 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c tions {H12280} <
16560 53 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S60400>.** EXPER
16570 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
16580 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 ese routines reg
16590 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 ister callback f
165a0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 unctions that ca
165b0 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a n be used for.**
165c0 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f tracing and pro
165d0 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 filing the execu
165e0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 tion of SQL stat
165f0 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ements..**.** Th
16600 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
16610 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 ion registered b
16620 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 y sqlite3_trace(
16630 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a ) is invoked at.
16640 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 ** various times
16650 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 when an SQL sta
16660 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 tement is being
16670 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f run by [sqlite3_
16680 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 step()]..** The
16690 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
166a0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 a UTF-8 renderi
166b0 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 ng of the SQL st
166c0 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 atement text.**
166d0 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 as the statement
166e0 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 first begins ex
166f0 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 ecuting. Additi
16700 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f onal callbacks o
16710 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 ccur.** as each
16720 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f triggered subpro
16730 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e gram is entered.
16740 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 The callbacks
16750 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 for triggers.**
16760 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 contain a UTF-8
16770 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 SQL comment that
16780 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 identifies the
16790 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 trigger..**.** T
167a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
167b0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 tion registered
167c0 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 by sqlite3_profi
167d0 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a le() is invoked.
167e0 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 ** as each SQL s
167f0 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 tatement finishe
16800 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 s. The profile
16810 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e callback contain
16820 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 s.** the origina
16830 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 l statement text
16840 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 and an estimate
16850 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 of wall-clock t
16860 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f ime.** of how lo
16870 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e ng that statemen
16880 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a t took to run..*
16890 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
168a0 73 3a 0a 2a 2a 20 5b 48 31 32 32 38 31 5d 20 5b s:.** [H12281] [
168b0 48 31 32 32 38 32 5d 20 5b 48 31 32 32 38 33 5d H12282] [H12283]
168c0 20 5b 48 31 32 32 38 34 5d 20 5b 48 31 32 32 38 [H12284] [H1228
168d0 35 5d 20 5b 48 31 32 32 38 37 5d 20 5b 48 31 32 5] [H12287] [H12
168e0 32 38 38 5d 20 5b 48 31 32 32 38 39 5d 0a 2a 2a 288] [H12289].**
168f0 20 5b 48 31 32 32 39 30 5d 0a 2a 2f 0a 53 51 4c [H12290].*/.SQL
16900 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c ITE_EXPERIMENTAL
16910 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 void *sqlite3_t
16920 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 race(sqlite3*, v
16930 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 oid(*xTrace)(voi
16940 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c d*,const char*),
16950 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f void*);.SQLITE_
16960 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 EXPERIMENTAL voi
16970 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 d *sqlite3_profi
16980 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 le(sqlite3*,.
16990 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 void(*xProfile)(
169a0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 void*,const char
169b0 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 *,sqlite3_uint64
169c0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a ), void*);../*.*
169d0 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 * CAPI3REF: Quer
169e0 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 y Progress Callb
169f0 61 63 6b 73 20 7b 48 31 32 39 31 30 7d 20 3c 53 acks {H12910} <S
16a00 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 60400>.**.** Thi
16a10 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 s routine config
16a20 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 ures a callback
16a30 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a function - the.*
16a40 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 * progress callb
16a50 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e ack - that is in
16a60 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c voked periodical
16a70 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a ly during long.*
16a80 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 * running calls
16a90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 to [sqlite3_exec
16aa0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 ()], [sqlite3_st
16ab0 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 ep()] and.** [sq
16ac0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
16ad0 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 )]. An example
16ae0 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 use for this.**
16af0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 interface is to
16b00 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 keep a GUI updat
16b10 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 ed during a larg
16b20 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 e query..**.** I
16b30 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 f the progress c
16b40 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
16b50 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 non-zero, the op
16b60 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e eration is.** in
16b70 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 terrupted. This
16b80 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 feature can be
16b90 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e used to implemen
16ba0 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 t a.** "Cancel"
16bb0 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 button on a GUI
16bc0 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 progress dialog
16bd0 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 box..**.** The p
16be0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 rogress handler
16bf0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 must not do anyt
16c00 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d hing that will m
16c10 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 odify.** the dat
16c20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
16c30 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
16c40 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
16c50 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 er..** Note that
16c60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
16c70 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c e_v2()] and [sql
16c80 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 ite3_step()] bot
16c90 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a h modify their.*
16ca0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
16cb0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d ctions for the m
16cc0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 eaning of "modif
16cd0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 y" in this parag
16ce0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 raph..**.** Requ
16cf0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
16d00 32 39 31 31 5d 20 5b 48 31 32 39 31 32 5d 20 5b 2911] [H12912] [
16d10 48 31 32 39 31 33 5d 20 5b 48 31 32 39 31 34 5d H12913] [H12914]
16d20 20 5b 48 31 32 39 31 35 5d 20 5b 48 31 32 39 31 [H12915] [H1291
16d30 36 5d 20 5b 48 31 32 39 31 37 5d 20 5b 48 31 32 6] [H12917] [H12
16d40 39 31 38 5d 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 918].**.*/.void
16d50 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 sqlite3_progress
16d60 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 _handler(sqlite3
16d70 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 *, int, int(*)(v
16d80 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a oid*), void*);..
16d90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
16da0 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 Opening A New Da
16db0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
16dc0 6e 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32 n {H12700} <S402
16dd0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 00>.**.** These
16de0 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e routines open an
16df0 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 SQLite database
16e00 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 file whose name
16e10 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 is given by the
16e20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 .** filename arg
16e30 75 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e ument. The filen
16e40 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ame argument is
16e50 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 interpreted as U
16e60 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 TF-8 for.** sqli
16e70 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 te3_open() and s
16e80 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
16e90 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 and as UTF-16 i
16ea0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 n the native byt
16eb0 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 e.** order for s
16ec0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e qlite3_open16().
16ed0 20 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e A [database con
16ee0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 nection] handle
16ef0 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 is usually.** re
16f00 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c turned in *ppDb,
16f10 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f even if an erro
16f20 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f r occurs. The o
16f30 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 nly exception is
16f40 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 that.** if SQLi
16f50 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 te is unable to
16f60 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 allocate memory
16f70 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c to hold the [sql
16f80 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a ite3] object,.**
16f90 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 a NULL will be
16fa0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 written into *pp
16fb0 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 Db instead of a
16fc0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b pointer to the [
16fd0 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 sqlite3].** obje
16fe0 63 74 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 ct. If the datab
16ff0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 ase is opened (a
17000 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 nd/or created) s
17010 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 uccessfully, the
17020 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d n.** [SQLITE_OK]
17030 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f is returned. O
17040 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 therwise an [err
17050 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
17060 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 rned. The.** [s
17070 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
17080 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 or [sqlite3_err
17090 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 msg16()] routine
170a0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f s can be used to
170b0 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e obtain.** an En
170c0 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 glish language d
170d0 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 escription of th
170e0 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 e error..**.** T
170f0 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 he default encod
17100 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 ing for the data
17110 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 base will be UTF
17120 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 -8 if.** sqlite3
17130 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 _open() or sqlit
17140 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
17150 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 called and.** UT
17160 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 F-16 in the nati
17170 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 ve byte order if
17180 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
17190 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a ) is used..**.**
171a0 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 Whether or not
171b0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 an error occurs
171c0 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 when it is opene
171d0 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 d, resources.**
171e0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
171f0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
17200 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 nnection] handle
17210 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 should be relea
17220 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e sed by.** passin
17230 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 g it to [sqlite3
17240 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 _close()] when i
17250 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 t is no longer r
17260 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 equired..**.** T
17270 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f he sqlite3_open_
17280 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 v2() interface w
17290 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 orks like sqlite
172a0 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 3_open().** exce
172b0 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 pt that it accep
172c0 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 ts two additiona
172d0 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 l parameters for
172e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 additional cont
172f0 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 rol.** over the
17300 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e new database con
17310 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c nection. The fl
17320 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 ags parameter ca
17330 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a n take one of.**
17340 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 the following t
17350 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 hree values, opt
17360 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 ionally combined
17370 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 with the .** [S
17380 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
17390 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f EX] or [SQLITE_O
173a0 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 PEN_FULLMUTEX] f
173b0 6c 61 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e lags:.**.** <dl>
173c0 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f .** <dt>[SQLITE_
173d0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f OPEN_READONLY]</
173e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 dt>.** <dd>The d
173f0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
17400 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d d in read-only m
17410 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 ode. If the dat
17420 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a abase does not.*
17430 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c * already exist,
17440 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 an error is ret
17450 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a urned.</dd>.**.*
17460 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 * <dt>[SQLITE_OP
17470 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 EN_READWRITE]</d
17480 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 t>.** <dd>The da
17490 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
174a0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 for reading and
174b0 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 writing if poss
174c0 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 ible, or reading
174d0 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 .** only if the
174e0 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 file is write pr
174f0 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f otected by the o
17500 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e perating system.
17510 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 In either.** c
17520 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 ase the database
17530 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 must already ex
17540 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 ist, otherwise a
17550 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 n error is retur
17560 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ned.</dd>.**.**
17570 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e <dt>[SQLITE_OPEN
17580 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 _READWRITE] | [S
17590 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
175a0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 E]</dt>.** <dd>T
175b0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
175c0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e pened for readin
175d0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 g and writing, a
175e0 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69 74 nd is creates it
175f0 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e if.** it does n
17600 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 ot already exist
17610 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 . This is the be
17620 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 havior that is a
17630 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a lways used for.*
17640 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
17650 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 and sqlite3_ope
17660 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c n16().</dd>.** <
17670 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 /dl>.**.** If th
17680 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
17690 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
176a0 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 v2() is not one
176b0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e of the.** combin
176c0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f ations shown abo
176d0 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 ve or one of the
176e0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 combinations sh
176f0 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e own above combin
17700 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b ed.** with the [
17710 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
17720 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f TEX] or [SQLITE_
17730 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 OPEN_FULLMUTEX]
17740 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 flags,.** then t
17750 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
17760 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
17770 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f If the [SQLITE_O
17780 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 PEN_NOMUTEX] fla
17790 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 g is set, then t
177a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
177b0 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 ection.** opens
177c0 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 in the multi-thr
177d0 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d ead [threading m
177e0 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 ode] as long as
177f0 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 the single-threa
17800 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f d.** mode has no
17810 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f t been set at co
17820 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 mpile-time or st
17830 61 72 74 2d 74 69 6d 65 2e 20 20 49 66 20 74 68 art-time. If th
17840 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 e.** [SQLITE_OPE
17850 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 N_FULLMUTEX] fla
17860 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 g is set then th
17870 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
17880 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 ction opens.** i
17890 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 n the serialized
178a0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
178b0 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d ] unless single-
178c0 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 thread was.** pr
178d0 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 eviously selecte
178e0 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d d at compile-tim
178f0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e e or start-time.
17900 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 .**.** If the fi
17910 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f lename is ":memo
17920 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 ry:", then a pri
17930 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 vate, temporary
17940 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 in-memory databa
17950 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 se.** is created
17960 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 for the connect
17970 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 ion. This in-me
17980 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 mory database wi
17990 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a ll vanish when.*
179a0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
179b0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f onnection is clo
179c0 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 sed. Future ver
179d0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
179e0 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 might.** make us
179f0 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 e of additional
17a00 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 special filename
17a10 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 s that begin wit
17a20 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 h the ":" charac
17a30 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 ter..** It is re
17a40 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 commended that w
17a50 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 hen a database f
17a60 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 ilename actually
17a70 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 does begin with
17a80 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 .** a ":" charac
17a90 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 ter you should p
17aa0 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 refix the filena
17ab0 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 me with a pathna
17ac0 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e me such as.** ".
17ad0 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 /" to avoid ambi
17ae0 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 guity..**.** If
17af0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 the filename is
17b00 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c an empty string,
17b10 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c then a private,
17b20 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e temporary.** on
17b30 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 -disk database w
17b40 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 ill be created.
17b50 20 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 This private da
17b60 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a tabase will be.*
17b70 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 * automatically
17b80 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 deleted as soon
17b90 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 as the database
17ba0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c connection is cl
17bb0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 osed..**.** The
17bc0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
17bd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
17be0 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d _v2() is the nam
17bf0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c e of the.** [sql
17c00 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
17c10 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 that defines th
17c20 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
17c30 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 em interface tha
17c40 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 t.** the new dat
17c50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
17c60 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 should use. If
17c70 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
17c80 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 meter is.** a NU
17c90 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
17ca0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c the default [sql
17cb0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
17cc0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
17cd0 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f <b>Note to Windo
17ce0 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 ws users:</b> T
17cf0 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 he encoding used
17d00 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d for the filenam
17d10 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 e argument.** of
17d20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
17d30 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e and sqlite3_open
17d40 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 _v2() must be UT
17d50 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 F-8, not whateve
17d60 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 r.** codepage is
17d70 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e currently defin
17d80 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 ed. Filenames c
17d90 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e ontaining intern
17da0 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 ational.** chara
17db0 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f cters must be co
17dc0 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 nverted to UTF-8
17dd0 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e prior to passin
17de0 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 g them into.** s
17df0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 qlite3_open() or
17e00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
17e10 28 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ()..**.** Requir
17e20 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 ements:.** [H127
17e30 30 31 5d 20 5b 48 31 32 37 30 32 5d 20 5b 48 31 01] [H12702] [H1
17e40 32 37 30 33 5d 20 5b 48 31 32 37 30 34 5d 20 5b 2703] [H12704] [
17e50 48 31 32 37 30 36 5d 20 5b 48 31 32 37 30 37 5d H12706] [H12707]
17e60 20 5b 48 31 32 37 30 39 5d 20 5b 48 31 32 37 31 [H12709] [H1271
17e70 31 5d 0a 2a 2a 20 5b 48 31 32 37 31 32 5d 20 5b 1].** [H12712] [
17e80 48 31 32 37 31 33 5d 20 5b 48 31 32 37 31 34 5d H12713] [H12714]
17e90 20 5b 48 31 32 37 31 37 5d 20 5b 48 31 32 37 31 [H12717] [H1271
17ea0 39 5d 20 5b 48 31 32 37 32 31 5d 20 5b 48 31 32 9] [H12721] [H12
17eb0 37 32 33 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 723].*/.int sqli
17ec0 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 te3_open(. cons
17ed0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 t char *filename
17ee0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
17ef0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 filename (UTF-8)
17f00 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
17f10 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a ppDb /*
17f20 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
17f30 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 handle */.);.int
17f40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
17f50 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 . const void *f
17f60 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 ilename, /* Da
17f70 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
17f80 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 (UTF-16) */. sq
17f90 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 lite3 **ppDb
17fa0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 /* OUT: SQ
17fb0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a Lite db handle *
17fc0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 /.);.int sqlite3
17fd0 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 _open_v2(. cons
17fe0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 t char *filename
17ff0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
18000 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 filename (UTF-8)
18010 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
18020 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a ppDb, /*
18030 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
18040 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 handle */. int
18050 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 flags,
18060 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a /* Flags */.
18070 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 const char *zV
18080 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d fs /* Nam
18090 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 e of VFS module
180a0 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a to use */.);../*
180b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 .** CAPI3REF: Er
180c0 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 ror Codes And Me
180d0 73 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20 ssages {H12800}
180e0 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S60200>.**.** T
180f0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f he sqlite3_errco
18100 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 de() interface r
18110 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 eturns the numer
18120 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d ic [result code]
18130 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 or.** [extended
18140 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f result code] fo
18150 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e r the most recen
18160 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 t failed sqlite3
18170 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 _* API call.** a
18180 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 ssociated with a
18190 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
181a0 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 ction]. If a pri
181b0 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c or API call fail
181c0 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f ed.** but the mo
181d0 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 st recent API ca
181e0 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 ll succeeded, th
181f0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
18200 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 rom.** sqlite3_e
18210 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 rrcode() is unde
18220 66 69 6e 65 64 2e 20 20 54 68 65 20 73 71 6c 69 fined. The sqli
18230 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 te3_extended_err
18240 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 code().** interf
18250 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 ace is the same
18260 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 except that it a
18270 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 lways returns th
18280 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 e .** [extended
18290 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 result code] eve
182a0 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 n when extended
182b0 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
182c0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a .** disabled..**
182d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
182e0 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c errmsg() and sql
182f0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 ite3_errmsg16()
18300 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c return English-l
18310 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 anguage.** text
18320 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 that describes t
18330 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 he error, as eit
18340 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 her UTF-8 or UTF
18350 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 -16 respectively
18360 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 ..** Memory to h
18370 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 old the error me
18380 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 ssage string is
18390 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c managed internal
183a0 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 ly..** The appli
183b0 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 cation does not
183c0 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 need to worry ab
183d0 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 out freeing the
183e0 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 result..** Howev
183f0 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 er, the error st
18400 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 ring might be ov
18410 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 erwritten or dea
18420 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 llocated by.** s
18430 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
18440 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 to other SQLite
18450 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 interface functi
18460 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 ons..**.** When
18470 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b the serialized [
18480 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
18490 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 is in use, it mi
184a0 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 ght be the.** ca
184b0 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 se that a second
184c0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e error occurs on
184d0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
184e0 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a ad in between.**
184f0 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 the time of the
18500 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 first error and
18510 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 the call to the
18520 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a se interfaces..*
18530 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 * When that happ
18540 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 ens, the second
18550 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 error will be re
18560 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 ported since the
18570 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 se.** interfaces
18580 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 always report t
18590 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 he most recent r
185a0 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 esult. To avoid
185b0 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 .** this, each t
185c0 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e hread can obtain
185d0 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f exclusive use o
185e0 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 f the [database
185f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a connection] D.**
18600 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 by invoking [sq
18610 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 lite3_mutex_ente
18620 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d r]([sqlite3_db_m
18630 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 utex](D)) before
18640 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f beginning.** to
18650 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b use D and invok
18660 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
18670 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 ex_leave]([sqlit
18680 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 e3_db_mutex](D))
18690 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 after.** all ca
186a0 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 lls to the inter
186b0 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 faces listed her
186c0 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e e are completed.
186d0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 .**.** If an int
186e0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 erface fails wit
186f0 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c h SQLITE_MISUSE,
18700 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 that means the
18710 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 interface.** was
18720 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 invoked incorre
18730 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c ctly by the appl
18740 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 ication. In tha
18750 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 t case, the.** e
18760 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 rror code and me
18770 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 ssage may or may
18780 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a not be set..**.
18790 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
187a0 0a 2a 2a 20 5b 48 31 32 38 30 31 5d 20 5b 48 31 .** [H12801] [H1
187b0 32 38 30 32 5d 20 5b 48 31 32 38 30 33 5d 20 5b 2802] [H12803] [
187c0 48 31 32 38 30 37 5d 20 5b 48 31 32 38 30 38 5d H12807] [H12808]
187d0 20 5b 48 31 32 38 30 39 5d 0a 2a 2f 0a 69 6e 74 [H12809].*/.int
187e0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 sqlite3_errcode
187f0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 (sqlite3 *db);.i
18800 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e nt sqlite3_exten
18810 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 ded_errcode(sqli
18820 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 te3 *db);.const
18830 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 char *sqlite3_er
18840 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a rmsg(sqlite3*);.
18850 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
18860 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c te3_errmsg16(sql
18870 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
18880 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 API3REF: SQL Sta
18890 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 tement Object {H
188a0 31 33 30 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 13000} <H13010>.
188b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 ** KEYWORDS: {pr
188c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
188d0 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 } {prepared stat
188e0 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e ements}.**.** An
188f0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
18900 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 s object represe
18910 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c nts a single SQL
18920 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 statement..** T
18930 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 his object is va
18940 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 riously known as
18950 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 a "prepared sta
18960 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 tement" or a.**
18970 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 "compiled SQL st
18980 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 atement" or simp
18990 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 ly as a "stateme
189a0 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c nt"..**.** The l
189b0 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 ife of a stateme
189c0 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 nt object goes s
189d0 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 omething like th
189e0 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a is:.**.** <ol>.*
189f0 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 * <li> Create th
18a00 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b e object using [
18a10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
18a20 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 v2()] or a relat
18a30 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 ed.** funct
18a40 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e ion..** <li> Bin
18a50 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 d values to [hos
18a60 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 t parameters] us
18a70 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
18a80 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 bind_*().**
18a90 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 interfaces..**
18aa0 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c <li> Run the SQL
18ab0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c by calling [sql
18ac0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 ite3_step()] one
18ad0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a or more times..
18ae0 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 ** <li> Reset th
18af0 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e e statement usin
18b00 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
18b10 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b ()] then go back
18b20 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 .** to step
18b30 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 2. Do this zer
18b40 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e o or more times.
18b50 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 .** <li> Destroy
18b60 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e the object usin
18b70 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c g [sqlite3_final
18b80 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e ize()]..** </ol>
18b90 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 .**.** Refer to
18ba0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e documentation on
18bb0 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 individual meth
18bc0 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 ods above for ad
18bd0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f ditional.** info
18be0 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 rmation..*/.type
18bf0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
18c00 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f e3_stmt sqlite3_
18c10 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 stmt;../*.** CAP
18c20 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 I3REF: Run-time
18c30 4c 69 6d 69 74 73 20 7b 48 31 32 37 36 30 7d 20 Limits {H12760}
18c40 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S20600>.**.** T
18c50 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c his interface al
18c60 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 lows the size of
18c70 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 various constru
18c80 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 cts to be limite
18c90 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 d.** on a connec
18ca0 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 tion by connecti
18cb0 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 on basis. The f
18cc0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
18cd0 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 s the.** [databa
18ce0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 se connection] w
18cf0 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f hose limit is to
18d00 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 be set or queri
18d10 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f ed. The.** seco
18d20 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
18d30 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 one of the [limi
18d40 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 t categories] th
18d50 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 at define a.** c
18d60 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 lass of construc
18d70 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 ts to be size li
18d80 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 mited. The thir
18d90 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
18da0 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 he.** new limit
18db0 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 for that constru
18dc0 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f ct. The functio
18dd0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c n returns the ol
18de0 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 d limit..**.** I
18df0 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 f the new limit
18e00 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 is a negative nu
18e10 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 mber, the limit
18e20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a is unchanged..**
18e30 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 For the limit c
18e40 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 ategory of SQLIT
18e50 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 E_LIMIT_XYZ ther
18e60 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 e is a .** [limi
18e70 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 ts | hard upper
18e80 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62 79 bound].** set by
18e90 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 a compile-time
18ea0 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
18eb0 61 63 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b acro named .** [
18ec0 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f limits | SQLITE_
18ed0 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68 MAX_XYZ]..** (Th
18ee0 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 e "_LIMIT_" in t
18ef0 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 he name is chang
18f00 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a ed to "_MAX_".).
18f10 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 ** Attempts to i
18f20 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 ncrease a limit
18f30 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 above its hard u
18f40 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a pper bound are.*
18f50 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 * silently trunc
18f60 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 ated to the hard
18f70 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a upper limit..**
18f80 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d .** Run time lim
18f90 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 its are intended
18fa0 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c for use in appl
18fb0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 ications that ma
18fc0 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 nage.** both the
18fd0 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 ir own internal
18fe0 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 database and als
18ff0 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 o databases that
19000 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a are controlled.
19010 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 ** by untrusted
19020 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 external sources
19030 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 . An example ap
19040 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 plication might
19050 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 be a.** web brow
19060 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 ser that has its
19070 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 own databases f
19080 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f or storing histo
19090 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 ry and.** separa
190a0 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e te databases con
190b0 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 trolled by JavaS
190c0 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f cript applicatio
190d0 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a ns downloaded.**
190e0 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 off the Interne
190f0 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c t. The internal
19100 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 databases can b
19110 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c e given the.** l
19120 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 arge, default li
19130 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 mits. Databases
19140 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 managed by exte
19150 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e rnal sources can
19160 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 .** be given muc
19170 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 h smaller limits
19180 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 designed to pre
19190 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 vent a denial of
191a0 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 service.** atta
191b0 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 ck. Developers
191c0 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 might also want
191d0 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 to use the [sqli
191e0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
191f0 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 er()].** interfa
19200 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f ce to further co
19210 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 ntrol untrusted
19220 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f SQL. The size o
19230 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a f the database.*
19240 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 * created by an
19250 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 untrusted script
19260 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 can be containe
19270 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b d using the.** [
19280 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 max_page_count]
19290 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 [PRAGMA]..**.**
192a0 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d New run-time lim
192b0 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 it categories ma
192c0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
192d0 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a ture releases..*
192e0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
192f0 73 3a 0a 2a 2a 20 5b 48 31 32 37 36 32 5d 20 5b s:.** [H12762] [
19300 48 31 32 37 36 36 5d 20 5b 48 31 32 37 36 39 5d H12766] [H12769]
19310 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
19320 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 limit(sqlite3*,
19330 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 int id, int newV
19340 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 al);../*.** CAPI
19350 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 3REF: Run-Time L
19360 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 20 imit Categories
19370 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36 30 {H12790} <H12760
19380 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b >.** KEYWORDS: {
19390 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 limit category}
193a0 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 {limit categorie
193b0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 s}.**.** These c
193c0 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 onstants define
193d0 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 various performa
193e0 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 nce limits.** th
193f0 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 at can be lowere
19400 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 d at run-time us
19410 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d ing [sqlite3_lim
19420 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 it()]..** The sy
19430 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 nopsis of the me
19440 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 anings of the va
19450 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 rious limits is
19460 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 shown below..**
19470 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 Additional infor
19480 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 mation is availa
19490 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c ble at [limits |
194a0 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 Limits in SQLit
194b0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a e]..**.** <dl>.*
194c0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d * <dt>SQLITE_LIM
194d0 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a IT_LENGTH</dt>.*
194e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
194f0 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 m size of any st
19500 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 ring or BLOB or
19510 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a table row.<dd>.*
19520 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
19530 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 LIMIT_SQL_LENGTH
19540 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
19550 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 maximum length
19560 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d of an SQL statem
19570 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ent.</dd>.**.**
19580 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
19590 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 _COLUMN</dt>.**
195a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
195b0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
195c0 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 s in a table def
195d0 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 inition or in th
195e0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 e.** result set
195f0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 of a [SELECT] or
19600 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d the maximum num
19610 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
19620 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 n an index.** or
19630 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 in an ORDER BY
19640 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 or GROUP BY clau
19650 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c se.</dd>.**.** <
19660 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
19670 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a EXPR_DEPTH</dt>.
19680 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
19690 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 um depth of the
196a0 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e parse tree on an
196b0 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 y expression.</d
196c0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
196d0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 ITE_LIMIT_COMPOU
196e0 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a ND_SELECT</dt>.*
196f0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
19700 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d m number of term
19710 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 s in a compound
19720 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 SELECT statement
19730 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
19740 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 >SQLITE_LIMIT_VD
19750 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 BE_OP</dt>.** <d
19760 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
19770 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 mber of instruct
19780 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 ions in a virtua
19790 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 l machine progra
197a0 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 m.** used to imp
197b0 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 lement an SQL st
197c0 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a atement.</dd>.**
197d0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c .** <dt>SQLITE_L
197e0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
197f0 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 G</dt>.** <dd>Th
19800 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
19810 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e of arguments on
19820 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 a function.</dd
19830 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
19840 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 TE_LIMIT_ATTACHE
19850 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
19860 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
19870 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 of [ATTACH | at
19880 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 tached databases
19890 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 ].</dd>.**.** <d
198a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c t>SQLITE_LIMIT_L
198b0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
198c0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
198d0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
198e0 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e h of the pattern
198f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
19900 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 [LIKE] or.** [G
19910 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c LOB] operators.<
19920 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
19930 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
19940 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e ABLE_NUMBER</dt>
19950 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
19960 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 mum number of va
19970 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 riables in an SQ
19980 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 L statement that
19990 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 can.** be bound
199a0 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a .</dd>.** </dl>.
199b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
199c0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 E_LIMIT_LENGTH
199d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
199e0 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
199f0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e TE_LIMIT_SQL_LEN
19a00 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 GTH
19a10 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
19a20 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e ITE_LIMIT_COLUMN
19a30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
19a40 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
19a50 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
19a60 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 DEPTH
19a70 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
19a80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 QLITE_LIMIT_COMP
19a90 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 OUND_SELECT
19aa0 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 4.#define
19ab0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 SQLITE_LIMIT_VDB
19ac0 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 E_OP
19ad0 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 5.#define
19ae0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 SQLITE_LIMIT_FU
19af0 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 NCTION_ARG
19b00 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 6.#defin
19b10 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 e SQLITE_LIMIT_A
19b20 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 TTACHED
19b30 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 7.#defi
19b40 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
19b50 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e LIKE_PATTERN_LEN
19b60 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 GTH 8.#def
19b70 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
19b80 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
19b90 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 9../*
19ba0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
19bb0 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 mpiling An SQL S
19bc0 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 tatement {H13010
19bd0 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 } <S10000>.** KE
19be0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 YWORDS: {SQL sta
19bf0 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d tement compiler}
19c00 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 .**.** To execut
19c10 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 e an SQL query,
19c20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 it must first be
19c30 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 compiled into a
19c40 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 byte-code.** pr
19c50 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 ogram using one
19c60 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
19c70 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 s..**.** The fir
19c80 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 st argument, "db
19c90 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 ", is a [databas
19ca0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 e connection] ob
19cb0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a tained from a.**
19cc0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 prior successfu
19cd0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
19ce0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
19cf0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 ite3_open_v2()]
19d00 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f or.** [sqlite3_o
19d10 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 pen16()]. The d
19d20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
19d30 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 on must not have
19d40 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a been closed..**
19d50 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 .** The second a
19d60 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c rgument, "zSql",
19d70 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e is the statemen
19d80 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 t to be compiled
19d90 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 , encoded.** as
19da0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
19db0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c UTF-16. The sql
19dc0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 ite3_prepare() a
19dd0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
19de0 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 re_v2().** inter
19df0 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c faces use UTF-8,
19e00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
19e10 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c pare16() and sql
19e20 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
19e30 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 2().** use UTF-1
19e40 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6..**.** If the
19e50 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 nByte argument i
19e60 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f s less than zero
19e70 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 , then zSql is r
19e80 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a ead up to the.**
19e90 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d first zero term
19ea0 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 inator. If nByte
19eb0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
19ec0 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 , then it is the
19ed0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 maximum.** numb
19ee0 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 er of bytes rea
19ef0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 d from zSql. Wh
19f00 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d en nByte is non-
19f10 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a negative, the.**
19f20 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 zSql string end
19f30 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 s at either the
19f40 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 first '\000' or
19f50 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 '\u0000' charact
19f60 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 er or.** the nBy
19f70 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 te-th byte, whic
19f80 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 hever comes firs
19f90 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 t. If the caller
19fa0 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 knows.** that t
19fb0 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 he supplied stri
19fc0 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e ng is nul-termin
19fd0 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 ated, then there
19fe0 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 is a small.** p
19ff0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e erformance advan
1a000 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 tage to be gaine
1a010 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 d by passing an
1a020 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 nByte parameter
1a030 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c that.** is equal
1a040 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f to the number o
1a050 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 f bytes in the i
1a060 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 nput string <i>i
1a070 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 ncluding</i>.**
1a080 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 the nul-terminat
1a090 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 or bytes..**.**
1a0a0 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 If pzTail is not
1a0b0 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 NULL then *pzTa
1a0c0 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f il is made to po
1a0d0 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 int to the first
1a0e0 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 byte.** past th
1a0f0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 e end of the fir
1a100 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 st SQL statement
1a110 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 in zSql. These
1a120 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a routines only.*
1a130 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 * compile the fi
1a140 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e rst statement in
1a150 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 zSql, so *pzTai
1a160 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 l is left pointi
1a170 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 ng to.** what re
1a180 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 mains uncompiled
1a190 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 ..**.** *ppStmt
1a1a0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 is left pointing
1a1b0 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b to a compiled [
1a1c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1a1d0 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a nt] that can be.
1a1e0 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e ** executed usin
1a1f0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 g [sqlite3_step(
1a200 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 )]. If there is
1a210 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 an error, *ppSt
1a220 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 mt is set.** to
1a230 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e NULL. If the in
1a240 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e put text contain
1a250 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 s no SQL (if the
1a260 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 input is an emp
1a270 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 ty.** string or
1a280 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 a comment) then
1a290 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 *ppStmt is set t
1a2a0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 o NULL..** The c
1a2b0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 alling procedure
1a2c0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
1a2d0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 for deleting the
1a2e0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c compiled.** SQL
1a2f0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 statement using
1a300 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
1a310 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 ze()] after it h
1a320 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
1a330 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d it..** ppStmt m
1a340 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a ay not be NULL..
1a350 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 **.** On success
1a360 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 , [SQLITE_OK] is
1a370 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 returned, other
1a380 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 wise an [error c
1a390 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ode] is returned
1a3a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
1a3b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1a3c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
1a3d0 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 pare16_v2() inte
1a3e0 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 rfaces are.** re
1a3f0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c commended for al
1a400 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 l new programs.
1a410 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e The two older in
1a420 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 terfaces are ret
1a430 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 ained.** for bac
1a440 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
1a450 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 lity, but their
1a460 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 use is discourag
1a470 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 ed..** In the "v
1a480 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 2" interfaces, t
1a490 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 he prepared stat
1a4a0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 ement.** that is
1a4b0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b returned (the [
1a4c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 sqlite3_stmt] ob
1a4d0 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 ject) contains a
1a4e0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 copy of the.**
1a4f0 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 original SQL tex
1a500 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 t. This causes t
1a510 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 he [sqlite3_step
1a520 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f ()] interface to
1a530 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 .** behave a dif
1a540 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 ferently in two
1a550 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e ways:.**.** <ol>
1a560 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 .** <li>.** If t
1a570 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 he database sche
1a580 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 ma changes, inst
1a590 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 ead of returning
1a5a0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
1a5b0 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 as it.** always
1a5c0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 used to do, [sq
1a5d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
1a5e0 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ll automatically
1a5f0 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 recompile the S
1a600 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 QL.** statement
1a610 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 and try to run i
1a620 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 t again. If the
1a630 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e schema has chan
1a640 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 ged in.** a way
1a650 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 that makes the s
1a660 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 tatement no long
1a670 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 er valid, [sqlit
1a680 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 e3_step()] will
1a690 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 still.** return
1a6a0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e [SQLITE_SCHEMA].
1a6b0 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 But unlike the
1a6c0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 legacy behavior
1a6d0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 , [SQLITE_SCHEMA
1a6e0 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 ] is.** now a fa
1a6f0 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c tal error. Call
1a700 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ing [sqlite3_pre
1a710 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e pare_v2()] again
1a720 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 will not make t
1a730 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 he.** error go a
1a740 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 way. Note: use
1a750 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
1a760 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 )] to find the t
1a770 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 ext.** of the pa
1a780 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 rsing error that
1a790 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b results in an [
1a7a0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 SQLITE_SCHEMA] r
1a7b0 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a eturn..** </li>.
1a7c0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 **.** <li>.** Wh
1a7d0 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 en an error occu
1a7e0 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 rs, [sqlite3_ste
1a7f0 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e p()] will return
1a800 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 one of the deta
1a810 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 iled.** [error c
1a820 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 odes] or [extend
1a830 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e ed error codes].
1a840 20 20 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 The legacy beh
1a850 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a avior was that.*
1a860 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 * [sqlite3_step(
1a870 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 )] would only re
1a880 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b turn a generic [
1a890 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 SQLITE_ERROR] re
1a8a0 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 sult code.** and
1a8b0 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 you would have
1a8c0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 to make a second
1a8d0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
1a8e0 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 3_reset()] in or
1a8f0 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 der.** to find t
1a900 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 he underlying ca
1a910 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c use of the probl
1a920 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 em. With the "v2
1a930 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 " prepare.** int
1a940 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 erfaces, the und
1a950 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 erlying reason f
1a960 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 or the error is
1a970 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 returned immedia
1a980 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a tely..** </li>.*
1a990 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 * </ol>.**.** Re
1a9a0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
1a9b0 48 31 33 30 31 31 5d 20 5b 48 31 33 30 31 32 5d H13011] [H13012]
1a9c0 20 5b 48 31 33 30 31 33 5d 20 5b 48 31 33 30 31 [H13013] [H1301
1a9d0 34 5d 20 5b 48 31 33 30 31 35 5d 20 5b 48 31 33 4] [H13015] [H13
1a9e0 30 31 36 5d 20 5b 48 31 33 30 31 39 5d 20 5b 48 016] [H13019] [H
1a9f0 31 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74 13021].**.*/.int
1aa00 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
1aa10 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
1aa20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
1aa30 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
1aa40 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
1aa50 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
1aa60 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
1aa70 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 F-8 encoded */.
1aa80 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 int nByte,
1aa90 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
1aaa0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 mum length of zS
1aab0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a ql in bytes. */.
1aac0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a sqlite3_stmt *
1aad0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 *ppStmt, /* OUT
1aae0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 : Statement hand
1aaf0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
1ab00 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 ar **pzTail
1ab10 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 /* OUT: Pointer
1ab20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f to unused portio
1ab30 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a n of zSql */.);.
1ab40 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
1ab50 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 are_v2(. sqlite
1ab60 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
1ab70 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
1ab80 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
1ab90 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 char *zSql,
1aba0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
1abb0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 nt, UTF-8 encode
1abc0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
1abd0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
1abe0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
1abf0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
1ac00 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
1ac10 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
1ac20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
1ac30 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
1ac40 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 nst char **pzTai
1ac50 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
1ac60 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
1ac70 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
1ac80 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 */.);.int sqlite
1ac90 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 3_prepare16(. s
1aca0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
1acb0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
1acc0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
1acd0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c onst void *zSql,
1ace0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
1acf0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 atement, UTF-16
1ad00 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 encoded */. int
1ad10 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 nByte,
1ad20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
1ad30 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 length of zSql i
1ad40 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 n bytes. */. sq
1ad50 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 lite3_stmt **ppS
1ad60 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 tmt, /* OUT: St
1ad70 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a atement handle *
1ad80 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
1ad90 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f *pzTail /* O
1ada0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 UT: Pointer to u
1adb0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 nused portion of
1adc0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 zSql */.);.int
1add0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
1ade0 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 6_v2(. sqlite3
1adf0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
1ae00 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
1ae10 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
1ae20 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 id *zSql,
1ae30 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
1ae40 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 , UTF-16 encoded
1ae50 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
1ae60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
1ae70 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
1ae80 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
1ae90 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
1aea0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
1aeb0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
1aec0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
1aed0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c st void **pzTail
1aee0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
1aef0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
1af00 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
1af10 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
1af20 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 3REF: Retrieving
1af30 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b Statement SQL {
1af40 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30 3e H13100} <H13000>
1af50 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
1af60 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
1af70 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 d to retrieve a
1af80 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 saved copy of th
1af90 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 e original.** SQ
1afa0 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 L text used to c
1afb0 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 reate a [prepare
1afc0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 d statement] if
1afd0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 that statement w
1afe0 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 as.** compiled u
1aff0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c sing either [sql
1b000 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1b010 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
1b020 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a repare16_v2()]..
1b030 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
1b040 74 73 3a 0a 2a 2a 20 5b 48 31 33 31 30 31 5d 20 ts:.** [H13101]
1b050 5b 48 31 33 31 30 32 5d 20 5b 48 31 33 31 30 33 [H13102] [H13103
1b060 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 ].*/.const char
1b070 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c *sqlite3_sql(sql
1b080 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
1b090 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1b0a0 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 EF: Dynamically
1b0b0 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 Typed Value Obje
1b0c0 63 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 ct {H15000} <S20
1b0d0 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 200>.** KEYWORDS
1b0e0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c : {protected sql
1b0f0 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 ite3_value} {unp
1b100 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
1b110 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 _value}.**.** SQ
1b120 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 Lite uses the sq
1b130 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
1b140 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 ct to represent
1b150 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 all values.** th
1b160 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 at can be stored
1b170 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 in a database t
1b180 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 able. SQLite use
1b190 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 s dynamic typing
1b1a0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 .** for the valu
1b1b0 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61 es it stores. Va
1b1c0 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 lues stored in s
1b1d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
1b1e0 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 ects.** can be i
1b1f0 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e ntegers, floatin
1b200 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 g point values,
1b210 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 strings, BLOBs,
1b220 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 or NULL..**.** A
1b230 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 n sqlite3_value
1b240 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 object may be ei
1b250 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 ther "protected"
1b260 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 or "unprotected
1b270 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 "..** Some inter
1b280 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 faces require a
1b290 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
1b2a0 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 3_value. Other
1b2b0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 interfaces.** wi
1b2c0 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 ll accept either
1b2d0 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 a protected or
1b2e0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 an unprotected s
1b2f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a qlite3_value..**
1b300 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 Every interface
1b310 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 that accepts sq
1b320 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 lite3_value argu
1b330 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a ments specifies.
1b340 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f ** whether or no
1b350 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 t it requires a
1b360 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
1b370 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 3_value..**.** T
1b380 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 he terms "protec
1b390 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 ted" and "unprot
1b3a0 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 ected" refer to
1b3b0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a whether or not.*
1b3c0 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c * a mutex is hel
1b3d0 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d d. A internal m
1b3e0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 utex is held for
1b3f0 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 a protected.**
1b400 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
1b410 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 ject but no mute
1b420 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e x is held for an
1b430 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 unprotected.**
1b440 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
1b450 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 ject. If SQLite
1b460 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 is compiled to
1b470 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 be single-thread
1b480 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c ed.** (with [SQL
1b490 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
1b4a0 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 ] and with [sqli
1b4b0 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 te3_threadsafe()
1b4c0 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a ] returning 0).*
1b4d0 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 * or if SQLite i
1b4e0 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 s run in one of
1b4f0 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f reduced mutex mo
1b500 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f des .** [SQLITE_
1b510 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
1b520 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f EAD] or [SQLITE_
1b530 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
1b540 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 AD].** then ther
1b550 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 e is no distinct
1b560 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 ion between prot
1b570 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 ected and unprot
1b580 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
1b590 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 _value objects a
1b5a0 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 nd they can be u
1b5b0 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 sed interchangea
1b5c0 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a bly. However,.*
1b5d0 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f * for maximum co
1b5e0 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 de portability i
1b5f0 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 t is recommended
1b600 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f that applicatio
1b610 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 ns.** still make
1b620 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e the distinction
1b630 20 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e between between
1b640 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 protected and u
1b650 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 nprotected.** sq
1b660 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
1b670 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f cts even when no
1b680 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 t strictly requi
1b690 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 red..**.** The s
1b6a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
1b6b0 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 ects that are pa
1b6c0 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 ssed as paramete
1b6d0 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 rs into the.** i
1b6e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
1b6f0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 [application-de
1b700 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
1b710 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 ons] are protect
1b720 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 ed..** The sqlit
1b730 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
1b740 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
1b750 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
1b760 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f alue()] is unpro
1b770 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f tected..** Unpro
1b780 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
1b790 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 alue objects may
1b7a0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 only be used wi
1b7b0 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 th.** [sqlite3_r
1b7c0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 esult_value()] a
1b7d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 nd [sqlite3_bind
1b7e0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 _value()]..** Th
1b7f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
1b800 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f _blob | sqlite3_
1b810 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 value_type()] fa
1b820 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 mily of.** inter
1b830 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 faces require pr
1b840 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
1b850 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a value objects..*
1b860 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
1b870 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c Mem sqlite3_val
1b880 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ue;../*.** CAPI3
1b890 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f REF: SQL Functio
1b8a0 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 n Context Object
1b8b0 20 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32 30 {H16001} <S2020
1b8c0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 0>.**.** The con
1b8d0 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e text in which an
1b8e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 SQL function ex
1b8f0 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 ecutes is stored
1b900 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 in an.** sqlite
1b910 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 3_context object
1b920 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 . A pointer to
1b930 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 an sqlite3_conte
1b940 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 xt object.** is
1b950 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 always first par
1b960 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 ameter to [appli
1b970 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
1b980 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a QL functions]..*
1b990 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
1b9a0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
1b9b0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 nction implement
1b9c0 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 ation will pass
1b9d0 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 this.** pointer
1b9e0 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c through into cal
1b9f0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 ls to [sqlite3_r
1ba00 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 esult_int | sqli
1ba10 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a te3_result()],.*
1ba20 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 * [sqlite3_aggre
1ba30 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c gate_context()],
1ba40 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 [sqlite3_user_d
1ba50 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ata()],.** [sqli
1ba60 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 te3_context_db_h
1ba70 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 andle()], [sqlit
1ba80 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 e3_get_auxdata()
1ba90 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 ],.** and/or [sq
1baa0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
1bab0 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 a()]..*/.typedef
1bac0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
1bad0 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f context sqlite3_
1bae0 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 context;../*.**
1baf0 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e CAPI3REF: Bindin
1bb00 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 g Values To Prep
1bb10 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 ared Statements
1bb20 7b 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30 30 {H13500} <S70300
1bb30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b >.** KEYWORDS: {
1bb40 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 host parameter}
1bb50 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 {host parameters
1bb60 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 } {host paramete
1bb70 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f r name}.** KEYWO
1bb80 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 RDS: {SQL parame
1bb90 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 ter} {SQL parame
1bba0 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 ters} {parameter
1bbb0 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 binding}.**.**
1bbc0 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e In the SQL strin
1bbd0 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c gs input to [sql
1bbe0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1bbf0 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 )] and its varia
1bc00 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 nts,.** literals
1bc10 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 may be replaced
1bc20 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 by a [parameter
1bc30 5d 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 ] in one of thes
1bc40 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c e forms:.**.** <
1bc50 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a ul>.** <li> ?.*
1bc60 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 * <li> ?NNN.**
1bc70 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c <li> :VVV.** <l
1bc80 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e i> @VVV.** <li>
1bc90 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a $VVV.** </ul>.
1bca0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 **.** In the par
1bcb0 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f ameter forms sho
1bcc0 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 wn above NNN is
1bcd0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 an integer liter
1bce0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69 al,.** and VVV i
1bcf0 73 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72 s an alpha-numer
1bd00 69 63 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d ic parameter nam
1bd10 65 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 e. The values of
1bd20 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 these.** parame
1bd30 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 ters (also calle
1bd40 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 d "host paramete
1bd50 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c r names" or "SQL
1bd60 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a parameters").**
1bd70 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e can be set usin
1bd80 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 g the sqlite3_bi
1bd90 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
1bda0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a defined here..**
1bdb0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
1bdc0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 gument to the sq
1bdd0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 lite3_bind_*() r
1bde0 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 outines is alway
1bdf0 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 s.** a pointer t
1be00 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 o the [sqlite3_s
1be10 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 tmt] object retu
1be20 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 rned from.** [sq
1be30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1be40 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 ()] or its varia
1be50 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 nts..**.** The s
1be60 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
1be70 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
1be80 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 he SQL parameter
1be90 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 to be set..** T
1bea0 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 he leftmost SQL
1beb0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e parameter has an
1bec0 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68 index of 1. Wh
1bed0 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 en the same name
1bee0 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 d.** SQL paramet
1bef0 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 er is used more
1bf00 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e than once, secon
1bf10 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 d and subsequent
1bf20 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 .** occurrences
1bf30 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e have the same in
1bf40 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 dex as the first
1bf50 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 occurrence..**
1bf60 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 The index for na
1bf70 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 med parameters c
1bf80 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 an be looked up
1bf90 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 using the.** [sq
1bfa0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
1bfb0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 eter_index()] AP
1bfc0 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 I if desired. T
1bfd0 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 he index.** for
1bfe0 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 "?NNN" parameter
1bff0 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f s is the value o
1c000 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e f NNN..** The NN
1c010 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 N value must be
1c020 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 between 1 and th
1c030 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 e [sqlite3_limit
1c040 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ()].** parameter
1c050 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 [SQLITE_LIMIT_V
1c060 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 ARIABLE_NUMBER]
1c070 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 (default value:
1c080 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 999)..**.** The
1c090 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 third argument i
1c0a0 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 s the value to b
1c0b0 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d ind to the param
1c0c0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 eter..**.** In t
1c0d0 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 hose routines th
1c0e0 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 at have a fourth
1c0f0 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 argument, its v
1c100 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e alue is the.** n
1c110 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
1c120 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e n the parameter.
1c130 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 To be clear: t
1c140 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a he value is the.
1c150 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e ** number of <u>
1c160 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 bytes</u> in the
1c170 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 value, not the
1c180 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
1c190 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 ters..** If the
1c1a0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
1c1b0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
1c1c0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 e length of the
1c1d0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 string is.** the
1c1e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
1c1f0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 up to the first
1c200 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
1c210 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 ..**.** The fift
1c220 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 h argument to sq
1c230 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 lite3_bind_blob(
1c240 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f ), sqlite3_bind_
1c250 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 text(), and.** s
1c260 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
1c270 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 16() is a destru
1c280 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 ctor used to dis
1c290 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 pose of the BLOB
1c2a0 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 or.** string af
1c2b0 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 ter SQLite has f
1c2c0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e inished with it.
1c2d0 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 If the fifth ar
1c2e0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 gument is.** the
1c2f0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b special value [
1c300 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 SQLITE_STATIC],
1c310 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 then SQLite assu
1c320 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 mes that the.**
1c330 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 information is i
1c340 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 n static, unmana
1c350 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f ged space and do
1c360 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 es not need to b
1c370 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 e freed..** If t
1c380 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e he fifth argumen
1c390 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 t has the value
1c3a0 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e [SQLITE_TRANSIEN
1c3b0 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 T], then.** SQLi
1c3c0 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e te makes its own
1c3d0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 private copy of
1c3e0 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 the data immedi
1c3f0 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a ately, before.**
1c400 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
1c410 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 d_*() routine re
1c420 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 turns..**.** The
1c430 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 sqlite3_bind_ze
1c440 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 roblob() routine
1c450 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 binds a BLOB of
1c460 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a length N that.*
1c470 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 * is filled with
1c480 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f zeroes. A zero
1c490 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 blob uses a fixe
1c4a0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f d amount of memo
1c4b0 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 ry.** (just an i
1c4c0 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 nteger to hold i
1c4d0 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 ts size) while i
1c4e0 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 t is being proce
1c4f0 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f ssed..** Zeroblo
1c500 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 bs are intended
1c510 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 to serve as plac
1c520 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f eholders for BLO
1c530 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 Bs whose.** cont
1c540 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 ent is later wri
1c550 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 tten using.** [s
1c560 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e qlite3_blob_open
1c570 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 | incremental B
1c580 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 LOB I/O] routine
1c590 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 s..** A negative
1c5a0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a value for the z
1c5b0 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 eroblob results
1c5c0 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 in a zero-length
1c5d0 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 BLOB..**.** The
1c5e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
1c5f0 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 ) routines must
1c600 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a be called after.
1c610 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
1c620 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 are_v2()] (and i
1c630 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20 ts variants) or
1c640 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
1c650 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 ] and.** before
1c660 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1c670 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 ..** Bindings ar
1c680 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 e not cleared by
1c690 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 the [sqlite3_re
1c6a0 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a set()] routine..
1c6b0 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d ** Unbound param
1c6c0 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 eters are interp
1c6d0 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a reted as NULL..*
1c6e0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
1c6f0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 nes return [SQLI
1c700 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
1c710 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f s or an error co
1c720 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e de if.** anythin
1c730 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b g goes wrong. [
1c740 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 SQLITE_RANGE] is
1c750 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 returned if the
1c760 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e parameter.** in
1c770 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 dex is out of ra
1c780 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f nge. [SQLITE_NO
1c790 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 MEM] is returned
1c7a0 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 if malloc() fai
1c7b0 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d ls..** [SQLITE_M
1c7c0 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65 20 ISUSE] might be
1c7d0 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 73 returned if thes
1c7e0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 e routines are c
1c7f0 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 alled on a.** vi
1c800 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 rtual machine th
1c810 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20 at is the wrong
1c820 73 74 61 74 65 20 6f 72 20 77 68 69 63 68 20 68 state or which h
1c830 61 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 as already been
1c840 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 finalized..** De
1c850 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 tection of misus
1c860 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e e is unreliable.
1c870 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 Applications s
1c880 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 hould not depend
1c890 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 .** on SQLITE_MI
1c8a0 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20 53 SUSE returns. S
1c8b0 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73 20 QLITE_MISUSE is
1c8c0 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 intended to indi
1c8d0 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 cate a.** a logi
1c8e0 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 61 c error in the a
1c8f0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 pplication. Fut
1c900 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
1c910 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 SQLite might.**
1c920 70 61 6e 69 63 20 72 61 74 68 65 72 20 74 68 61 panic rather tha
1c930 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f n return SQLITE_
1c940 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 MISUSE..**.** Se
1c950 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
1c960 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
1c970 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 count()],.** [sq
1c980 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
1c990 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e eter_name()], an
1c9a0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f d [sqlite3_bind_
1c9b0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
1c9c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 )]..**.** Requir
1c9d0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 35 ements:.** [H135
1c9e0 30 36 5d 20 5b 48 31 33 35 30 39 5d 20 5b 48 31 06] [H13509] [H1
1c9f0 33 35 31 32 5d 20 5b 48 31 33 35 31 35 5d 20 5b 3512] [H13515] [
1ca00 48 31 33 35 31 38 5d 20 5b 48 31 33 35 32 31 5d H13518] [H13521]
1ca10 20 5b 48 31 33 35 32 34 5d 20 5b 48 31 33 35 32 [H13524] [H1352
1ca20 37 5d 0a 2a 2a 20 5b 48 31 33 35 33 30 5d 20 5b 7].** [H13530] [
1ca30 48 31 33 35 33 33 5d 20 5b 48 31 33 35 33 36 5d H13533] [H13536]
1ca40 20 5b 48 31 33 35 33 39 5d 20 5b 48 31 33 35 34 [H13539] [H1354
1ca50 32 5d 20 5b 48 31 33 35 34 35 5d 20 5b 48 31 33 2] [H13545] [H13
1ca60 35 34 38 5d 20 5b 48 31 33 35 35 31 5d 0a 2a 2a 548] [H13551].**
1ca70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
1ca80 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 bind_blob(sqlite
1ca90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
1caa0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e nst void*, int n
1cab0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
1cac0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
1cad0 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 ind_double(sqlit
1cae0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 e3_stmt*, int, d
1caf0 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 ouble);.int sqli
1cb00 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c te3_bind_int(sql
1cb10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
1cb20 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 int);.int sqlit
1cb30 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 e3_bind_int64(sq
1cb40 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
1cb50 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 , sqlite3_int64)
1cb60 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
1cb70 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f nd_null(sqlite3_
1cb80 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 stmt*, int);.int
1cb90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
1cba0 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a xt(sqlite3_stmt*
1cbb0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 , int, const cha
1cbc0 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 r*, int n, void(
1cbd0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 *)(void*));.int
1cbe0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
1cbf0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t16(sqlite3_stmt
1cc00 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f *, int, const vo
1cc10 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a id*, int, void(*
1cc20 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 )(void*));.int s
1cc30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 qlite3_bind_valu
1cc40 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
1cc50 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 int, const sqli
1cc60 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
1cc70 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 sqlite3_bind_ze
1cc80 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 roblob(sqlite3_s
1cc90 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e tmt*, int, int n
1cca0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1ccb0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 EF: Number Of SQ
1ccc0 4c 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31 L Parameters {H1
1ccd0 33 36 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 3600} <S70300>.*
1cce0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
1ccf0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
1cd00 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 find the number
1cd10 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 of [SQL paramet
1cd20 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 ers].** in a [pr
1cd30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1cd40 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 ]. SQL paramete
1cd50 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 rs are tokens of
1cd60 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 the.** form "?"
1cd70 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 , "?NNN", ":AAA"
1cd80 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 , "$AAA", or "@A
1cd90 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 AA" that serve a
1cda0 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 s.** placeholder
1cdb0 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 s for values tha
1cdc0 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 t are [sqlite3_b
1cdd0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 ind_blob | bound
1cde0 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 ].** to the para
1cdf0 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 meters at a late
1ce00 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 r time..**.** Th
1ce10 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 is routine actua
1ce20 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 lly returns the
1ce30 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 index of the lar
1ce40 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 gest (rightmost)
1ce50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 .** parameter. F
1ce60 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 or all forms exc
1ce70 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 ept ?NNN, this w
1ce80 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 ill correspond t
1ce90 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 o the.** number
1cea0 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 of unique parame
1ceb0 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 ters. If parame
1cec0 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e ters of the ?NNN
1ced0 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 are used,.** th
1cee0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 ere may be gaps
1cef0 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a in the list..**.
1cf00 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
1cf10 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
1cf20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
1cf30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
1cf40 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
1cf50 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
1cf60 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
1cf70 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a ter_index()]..**
1cf80 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
1cf90 3a 0a 2a 2a 20 5b 48 31 33 36 30 31 5d 0a 2a 2f :.** [H13601].*/
1cfa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
1cfb0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
1cfc0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 t(sqlite3_stmt*)
1cfd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1cfe0 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 F: Name Of A Hos
1cff0 74 20 50 61 72 61 6d 65 74 65 72 20 7b 48 31 33 t Parameter {H13
1d000 36 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 620} <S70300>.**
1d010 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
1d020 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
1d030 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f er to the name o
1d040 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 f the n-th.** [S
1d050 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e QL parameter] in
1d060 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
1d070 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 tement]..** SQL
1d080 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 parameters of th
1d090 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 e form "?NNN" or
1d0a0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 ":AAA" or "@AAA
1d0b0 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 " or "$AAA".** h
1d0c0 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 ave a name which
1d0d0 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 is the string "
1d0e0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 ?NNN" or ":AAA"
1d0f0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 or "@AAA" or "$A
1d100 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 AA".** respectiv
1d110 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 ely..** In other
1d120 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 words, the init
1d130 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f ial ":" or "$" o
1d140 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 r "@" or "?".**
1d150 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 is included as p
1d160 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e art of the name.
1d170 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f .** Parameters o
1d180 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 f the form "?" w
1d190 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 ithout a followi
1d1a0 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 ng integer have
1d1b0 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 no name.** and a
1d1c0 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72 65 64 re also referred
1d1d0 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 to as "anonymou
1d1e0 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a s parameters"..*
1d1f0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68 *.** The first h
1d200 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 ost parameter ha
1d210 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c s an index of 1,
1d220 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 not 0..**.** If
1d230 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20 the value n is
1d240 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 out of range or
1d250 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 if the n-th para
1d260 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 meter is.** name
1d270 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 less, then NULL
1d280 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 is returned. Th
1d290 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
1d2a0 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 g is.** always i
1d2b0 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 n UTF-8 encoding
1d2c0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d even if the nam
1d2d0 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 ed parameter was
1d2e0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 .** originally s
1d2f0 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d pecified as UTF-
1d300 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 16 in [sqlite3_p
1d310 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a repare16()] or.*
1d320 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
1d330 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a re16_v2()]..**.*
1d340 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
1d350 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
1d360 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a qlite3_bind()],.
1d370 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
1d380 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
1d390 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
1d3a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
1d3b0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a ter_index()]..**
1d3c0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
1d3d0 3a 0a 2a 2a 20 5b 48 31 33 36 32 31 5d 0a 2a 2f :.** [H13621].*/
1d3e0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
1d3f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
1d400 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 ter_name(sqlite3
1d410 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f _stmt*, int);../
1d420 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
1d430 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 ndex Of A Parame
1d440 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e ter With A Given
1d450 20 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c Name {H13640} <
1d460 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 S70300>.**.** Re
1d470 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f turn the index o
1d480 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 f an SQL paramet
1d490 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d er given its nam
1d4a0 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 e. The.** index
1d4b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
1d4c0 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 is suitable for
1d4d0 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e use as the secon
1d4e0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 d.** parameter t
1d4f0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f o [sqlite3_bind_
1d500 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
1d510 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a d()]. A zero.**
1d520 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 is returned if
1d530 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 no matching para
1d540 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 meter is found.
1d550 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a The parameter.*
1d560 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 * name must be g
1d570 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 iven in UTF-8 ev
1d580 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e en if the origin
1d590 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 al statement.**
1d5a0 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f was prepared fro
1d5b0 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 m UTF-16 text us
1d5c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ing [sqlite3_pre
1d5d0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a pare16_v2()]..**
1d5e0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
1d5f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
1d600 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
1d610 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
1d620 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
1d630 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 nt()], and.** [s
1d640 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1d650 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
1d660 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
1d670 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 34 31 5d 0a ts:.** [H13641].
1d680 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
1d690 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
1d6a0 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 dex(sqlite3_stmt
1d6b0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
1d6c0 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Name);../*.** CA
1d6d0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c PI3REF: Reset Al
1d6e0 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 l Bindings On A
1d6f0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
1d700 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 30 nt {H13660} <S70
1d710 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 300>.**.** Contr
1d720 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 ary to the intui
1d730 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 tion of many, [s
1d740 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
1d750 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a does not reset.*
1d760 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 * the [sqlite3_b
1d770 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 ind_blob | bindi
1d780 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 ngs] on a [prepa
1d790 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
1d7a0 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 ** Use this rout
1d7b0 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c ine to reset all
1d7c0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 host parameters
1d7d0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 to NULL..**.**
1d7e0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
1d7f0 20 5b 48 31 33 36 36 31 5d 0a 2a 2f 0a 69 6e 74 [H13661].*/.int
1d800 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 sqlite3_clear_b
1d810 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f indings(sqlite3_
1d820 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 stmt*);../*.** C
1d830 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 API3REF: Number
1d840 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 Of Columns In A
1d850 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 Result Set {H137
1d860 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 10} <S10700>.**.
1d870 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 ** Return the nu
1d880 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
1d890 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 in the result se
1d8a0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 t returned by th
1d8b0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
1d8c0 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 tatement]. This
1d8d0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
1d8e0 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 0 if pStmt is an
1d8f0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e SQL.** statemen
1d900 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 t that does not
1d910 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 return data (for
1d920 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 example an [UPD
1d930 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 ATE])..**.** Req
1d940 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
1d950 31 33 37 31 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 13711].*/.int sq
1d960 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 lite3_column_cou
1d970 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 nt(sqlite3_stmt
1d980 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
1d990 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e CAPI3REF: Column
1d9a0 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 Names In A Resu
1d9b0 6c 74 20 53 65 74 20 7b 48 31 33 37 32 30 7d 20 lt Set {H13720}
1d9c0 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S10700>.**.** T
1d9d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
1d9e0 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 turn the name as
1d9f0 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 signed to a part
1da00 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a icular column.**
1da10 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 in the result s
1da20 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d et of a [SELECT]
1da30 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 statement. The
1da40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
1da50 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 name().** interf
1da60 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
1da70 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d inter to a zero-
1da80 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 terminated UTF-8
1da90 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 string.** and s
1daa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
1dab0 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 me16() returns a
1dac0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 pointer to a ze
1dad0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
1dae0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 UTF-16 string.
1daf0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
1db00 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 eter is the [pre
1db10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1db20 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 .** that impleme
1db30 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d nts the [SELECT]
1db40 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 statement. The
1db50 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
1db60 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d is the.** colum
1db70 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c n number. The l
1db80 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 eftmost column i
1db90 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a s number 0..**.*
1dba0 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 * The returned s
1dbb0 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 tring pointer is
1dbc0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 valid until eit
1dbd0 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 her the [prepare
1dbe0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 d statement].**
1dbf0 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 is destroyed by
1dc00 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
1dc10 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 e()] or until th
1dc20 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a e next call to.*
1dc30 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
1dc40 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 _name() or sqlit
1dc50 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
1dc60 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 () on the same c
1dc70 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 olumn..**.** If
1dc80 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1dc90 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 fails during th
1dca0 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 e processing of
1dcb0 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a either routine.*
1dcc0 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 * (for example d
1dcd0 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 uring a conversi
1dce0 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f on from UTF-8 to
1dcf0 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a UTF-16) then a.
1dd00 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 ** NULL pointer
1dd10 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
1dd20 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 ** The name of a
1dd30 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 result column i
1dd40 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 s the value of t
1dd50 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 he "AS" clause f
1dd60 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d or.** that colum
1dd70 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 n, if there is a
1dd80 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 n AS clause. If
1dd90 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 there is no AS
1dda0 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 clause.** then t
1ddb0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 he name of the c
1ddc0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 olumn is unspeci
1ddd0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 fied and may cha
1dde0 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 nge from.** one
1ddf0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
1de00 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a e to the next..*
1de10 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
1de20 73 3a 0a 2a 2a 20 5b 48 31 33 37 32 31 5d 20 5b s:.** [H13721] [
1de30 48 31 33 37 32 33 5d 20 5b 48 31 33 37 32 34 5d H13723] [H13724]
1de40 20 5b 48 31 33 37 32 35 5d 20 5b 48 31 33 37 32 [H13725] [H1372
1de50 36 5d 20 5b 48 31 33 37 32 37 5d 0a 2a 2f 0a 63 6] [H13727].*/.c
1de60 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
1de70 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 e3_column_name(s
1de80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
1de90 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 t N);.const void
1dea0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
1deb0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
1dec0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a stmt*, int N);..
1ded0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1dee0 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 Source Of Data I
1def0 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 n A Query Result
1df00 20 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30 {H13740} <S1070
1df10 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 0>.**.** These r
1df20 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 outines provide
1df30 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 a means to deter
1df40 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e mine what column
1df50 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c of what.** tabl
1df60 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 e in which datab
1df70 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 ase a result of
1df80 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 a [SELECT] state
1df90 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e ment comes from.
1dfa0 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 .** The name of
1dfb0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 the database or
1dfc0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 table or column
1dfd0 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 can be returned
1dfe0 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 as.** either a U
1dff0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 TF-8 or UTF-16 s
1e000 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 tring. The _dat
1e010 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 abase_ routines
1e020 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 return.** the da
1e030 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 tabase name, the
1e040 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 _table_ routine
1e050 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 s return the tab
1e060 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 le name, and.**
1e070 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 the origin_ rout
1e080 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 ines return the
1e090 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 column name..**
1e0a0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
1e0b0 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 ing is valid unt
1e0c0 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 il the [prepared
1e0d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 statement] is d
1e0e0 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e estroyed.** usin
1e0f0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c g [sqlite3_final
1e100 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 ize()] or until
1e110 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 the same informa
1e120 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 tion is requeste
1e130 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 d.** again in a
1e140 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 different encodi
1e150 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 ng..**.** The na
1e160 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 mes returned are
1e170 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e the original un
1e180 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f -aliased names o
1e190 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 f the.** databas
1e1a0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f e, table, and co
1e1b0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 lumn..**.** The
1e1c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
1e1d0 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 o the following
1e1e0 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70 calls is a [prep
1e1f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
1e200 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 .** These functi
1e210 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 ons return infor
1e220 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 mation about the
1e230 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 Nth column retu
1e240 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 rned by.** the s
1e250 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 tatement, where
1e260 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 N is the second
1e270 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e function argumen
1e280 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 t..**.** If the
1e290 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 Nth column retur
1e2a0 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 ned by the state
1e2b0 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 ment is an expre
1e2c0 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 ssion or.** subq
1e2d0 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 uery and is not
1e2e0 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 a column value,
1e2f0 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 then all of thes
1e300 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
1e310 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 rn.** NULL. The
1e320 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 se routine might
1e330 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c also return NUL
1e340 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c L if a memory al
1e350 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a location error.*
1e360 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 * occurs. Other
1e370 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 wise, they retur
1e380 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 n the name of th
1e390 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 e attached datab
1e3a0 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e ase, table.** an
1e3b0 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 d column that qu
1e3c0 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d ery result colum
1e3d0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 n was extracted
1e3e0 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 from..**.** As w
1e3f0 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 ith all other SQ
1e400 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 Lite APIs, those
1e410 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 postfixed with
1e420 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 "16" return.** U
1e430 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 TF-16 encoded st
1e440 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 rings, the other
1e450 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 functions retur
1e460 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a n UTF-8. {END}.*
1e470 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 *.** These APIs
1e480 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 are only availab
1e490 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 le if the librar
1e4a0 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 y was compiled w
1e4b0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ith the.** [SQLI
1e4c0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e TE_ENABLE_COLUMN
1e4d0 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 _METADATA] C-pre
1e4e0 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c processor symbol
1e4f0 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 defined..**.**
1e500 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 {A13751}.** If t
1e510 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 wo or more threa
1e520 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d ds call one or m
1e530 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 ore of these rou
1e540 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 tines against th
1e550 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 e same.** prepar
1e560 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 ed statement and
1e570 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 column at the s
1e580 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 ame time then th
1e590 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a e results are.**
1e5a0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
1e5b0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
1e5c0 2a 2a 20 5b 48 31 33 37 34 31 5d 20 5b 48 31 33 ** [H13741] [H13
1e5d0 37 34 32 5d 20 5b 48 31 33 37 34 33 5d 20 5b 48 742] [H13743] [H
1e5e0 31 33 37 34 34 5d 20 5b 48 31 33 37 34 35 5d 20 13744] [H13745]
1e5f0 5b 48 31 33 37 34 36 5d 20 5b 48 31 33 37 34 38 [H13746] [H13748
1e600 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f ].**.** If two o
1e610 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 r more threads c
1e620 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a all one or more.
1e630 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
1e640 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 mn_database_name
1e650 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 | column metada
1e660 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a ta interfaces].*
1e670 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b * for the same [
1e680 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1e690 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 nt] and result c
1e6a0 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 olumn.** at the
1e6b0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 same time then t
1e6c0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 he results are u
1e6d0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e ndefined..*/.con
1e6e0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
1e6f0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
1e700 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
1e710 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
1e720 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
1e730 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
1e740 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
1e750 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 t*,int);.const c
1e760 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
1e770 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 umn_table_name(s
1e780 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
1e790 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
1e7a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 qlite3_column_ta
1e7b0 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 ble_name16(sqlit
1e7c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 e3_stmt*,int);.c
1e7d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
1e7e0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e e3_column_origin
1e7f0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
1e800 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
1e810 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
1e820 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 lumn_origin_name
1e830 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
1e840 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ,int);../*.** CA
1e850 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 PI3REF: Declared
1e860 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 Datatype Of A Q
1e870 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 uery Result {H13
1e880 37 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 760} <S10700>.**
1e890 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 .** The first pa
1e8a0 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 rameter is a [pr
1e8b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1e8c0 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 ]..** If this st
1e8d0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 atement is a [SE
1e8e0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 LECT] statement
1e8f0 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 and the Nth colu
1e900 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 mn of the.** ret
1e910 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 urned result set
1e920 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 of that [SELECT
1e930 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c ] is a table col
1e940 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 umn (not an.** e
1e950 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 xpression or sub
1e960 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 query) then the
1e970 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 declared type of
1e980 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f the table.** co
1e990 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 lumn is returned
1e9a0 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f . If the Nth co
1e9b0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 lumn of the resu
1e9c0 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 lt set is an.**
1e9d0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 expression or su
1e9e0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e bquery, then a N
1e9f0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
1ea00 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 eturned..** The
1ea10 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
1ea20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 is always UTF-8
1ea30 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a encoded. {END}.*
1ea40 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 *.** For example
1ea50 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 , given the data
1ea60 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a base schema:.**.
1ea70 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 ** CREATE TABLE
1ea80 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a t1(c1 VARIANT);.
1ea90 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f **.** and the fo
1eaa0 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e llowing statemen
1eab0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 t to be compiled
1eac0 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 :.**.** SELECT c
1ead0 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 1 + 1, c1 FROM t
1eae0 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 1;.**.** this ro
1eaf0 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 utine would retu
1eb00 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 rn the string "V
1eb10 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 ARIANT" for the
1eb20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a second result.**
1eb30 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 column (i==1),
1eb40 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 and a NULL point
1eb50 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 er for the first
1eb60 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 result column (
1eb70 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c i==0)..**.** SQL
1eb80 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 ite uses dynamic
1eb90 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 run-time typing
1eba0 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 . So just becau
1ebb0 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 se a column.** i
1ebc0 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f s declared to co
1ebd0 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c ntain a particul
1ebe0 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 ar type does not
1ebf0 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a mean that the.*
1ec00 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e * data stored in
1ec10 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 that column is
1ec20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 of the declared
1ec30 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 type. SQLite is
1ec40 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 .** strongly typ
1ec50 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 ed, but the typi
1ec60 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f ng is dynamic no
1ec70 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a t static. Type.
1ec80 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 ** is associated
1ec90 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c with individual
1eca0 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 values, not wit
1ecb0 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 h the containers
1ecc0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 .** used to hold
1ecd0 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a those values..*
1ece0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
1ecf0 73 3a 0a 2a 2a 20 5b 48 31 33 37 36 31 5d 20 5b s:.** [H13761] [
1ed00 48 31 33 37 36 32 5d 20 5b 48 31 33 37 36 33 5d H13762] [H13763]
1ed10 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
1ed20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
1ed30 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f ecltype(sqlite3_
1ed40 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
1ed50 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
1ed60 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 column_decltype1
1ed70 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
1ed80 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
1ed90 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 I3REF: Evaluate
1eda0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
1edb0 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30 30 30 {H13200} <S1000
1edc0 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 0>.**.** After a
1edd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1ede0 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 ment] has been p
1edf0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 repared using ei
1ee00 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ther.** [sqlite3
1ee10 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
1ee20 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
1ee30 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e re16_v2()] or on
1ee40 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a e of the legacy.
1ee50 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 ** interfaces [s
1ee60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
1ee70 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ] or [sqlite3_pr
1ee80 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 epare16()], this
1ee90 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 function.** mus
1eea0 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 t be called one
1eeb0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f or more times to
1eec0 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 evaluate the st
1eed0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 atement..**.** T
1eee0 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 he details of th
1eef0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 e behavior of th
1ef00 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 e sqlite3_step()
1ef10 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e interface depen
1ef20 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 d.** on whether
1ef30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 the statement wa
1ef40 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 s prepared using
1ef50 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 the newer "v2"
1ef60 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 interface.** [sq
1ef70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1ef80 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
1ef90 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
1efa0 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 or the older le
1efb0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 gacy.** interfac
1efc0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 e [sqlite3_prepa
1efd0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 re()] and [sqlit
1efe0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e e3_prepare16()].
1eff0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 The use of the
1f000 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 .** new "v2" int
1f010 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d erface is recomm
1f020 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 ended for new ap
1f030 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 plications but t
1f040 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 he legacy.** int
1f050 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 erface will cont
1f060 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f inue to be suppo
1f070 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 rted..**.** In t
1f080 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
1f090 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 ace, the return
1f0a0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 value will be ei
1f0b0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 ther [SQLITE_BUS
1f0c0 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 Y],.** [SQLITE_D
1f0d0 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f ONE], [SQLITE_RO
1f0e0 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f W], [SQLITE_ERRO
1f0f0 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d R], or [SQLITE_M
1f100 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 ISUSE]..** With
1f110 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
1f120 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f ce, any of the o
1f130 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 ther [result cod
1f140 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e es] or.** [exten
1f150 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
1f160 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 ] might be retur
1f170 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a ned as well..**.
1f180 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ** [SQLITE_BUSY]
1f190 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
1f1a0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 database engine
1f1b0 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 was unable to ac
1f1c0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 quire the.** dat
1f1d0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e abase locks it n
1f1e0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a eeds to do its j
1f1f0 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 ob. If the stat
1f200 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d ement is a [COMM
1f210 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 IT].** or occurs
1f220 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 outside of an e
1f230 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
1f240 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 ion, then you ca
1f250 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 n retry the.** s
1f260 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 tatement. If th
1f270 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e e statement is n
1f280 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e ot a [COMMIT] an
1f290 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 d occurs within
1f2a0 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 a.** explicit tr
1f2b0 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 ansaction then y
1f2c0 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 ou should rollba
1f2d0 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 ck the transacti
1f2e0 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e on before.** con
1f2f0 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b tinuing..**.** [
1f300 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 SQLITE_DONE] mea
1f310 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 ns that the stat
1f320 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 ement has finish
1f330 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 ed executing.**
1f340 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 successfully. s
1f350 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 qlite3_step() sh
1f360 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c ould not be call
1f370 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 ed again on this
1f380 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 virtual.** mach
1f390 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 ine without firs
1f3a0 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 t calling [sqlit
1f3b0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 e3_reset()] to r
1f3c0 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c eset the virtual
1f3d0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b .** machine back
1f3e0 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 to its initial
1f3f0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 state..**.** If
1f400 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
1f410 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 t being executed
1f420 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 returns any dat
1f430 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f a, then [SQLITE_
1f440 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 ROW].** is retur
1f450 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 ned each time a
1f460 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 new row of data
1f470 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f is ready for pro
1f480 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a cessing by the.*
1f490 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 * caller. The va
1f4a0 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 lues may be acce
1f4b0 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b ssed using the [
1f4c0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
1f4d0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c nctions]..** sql
1f4e0 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 ite3_step() is c
1f4f0 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 alled again to r
1f500 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 etrieve the next
1f510 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a row of data..**
1f520 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f .** [SQLITE_ERRO
1f530 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 R] means that a
1f540 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 run-time error (
1f550 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 such as a constr
1f560 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f aint.** violatio
1f570 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e n) has occurred.
1f580 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 sqlite3_step()
1f590 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 should not be c
1f5a0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a alled again on.*
1f5b0 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 * the VM. More i
1f5c0 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 nformation may b
1f5d0 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 e found by calli
1f5e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d ng [sqlite3_errm
1f5f0 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 sg()]..** With t
1f600 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
1f610 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 ace, a more spec
1f620 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 ific error code
1f630 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a (for example,.**
1f640 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 [SQLITE_INTERRU
1f650 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 PT], [SQLITE_SCH
1f660 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f EMA], [SQLITE_CO
1f670 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 RRUPT], and so f
1f680 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 orth).** can be
1f690 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c obtained by call
1f6a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
1f6b0 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 et()] on the.**
1f6c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1f6d0 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 ent]. In the "v
1f6e0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 2" interface,.**
1f6f0 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 the more specif
1f700 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 ic error code is
1f710 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 returned direct
1f720 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 ly by sqlite3_st
1f730 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c ep()..**.** [SQL
1f740 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e ITE_MISUSE] mean
1f750 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 s that the this
1f760 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c routine was call
1f770 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 ed inappropriate
1f780 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 ly..** Perhaps i
1f790 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 t was called on
1f7a0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
1f7b0 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a ement] that has.
1f7c0 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 ** already been
1f7d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
1f7e0 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f e | finalized] o
1f7f0 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 r on one that ha
1f800 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 d.** previously
1f810 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 returned [SQLITE
1f820 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 _ERROR] or [SQLI
1f830 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 TE_DONE]. Or it
1f840 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 could.** be the
1f850 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 case that the s
1f860 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
1f870 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 nection is being
1f880 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a used by two or.
1f890 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 ** more threads
1f8a0 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 at the same mome
1f8b0 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a nt in time..**.*
1f8c0 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 * <b>Goofy Inter
1f8d0 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 face Alert:</b>
1f8e0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e In the legacy in
1f8f0 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c terface, the sql
1f900 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 ite3_step().** A
1f910 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e PI always return
1f920 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f s a generic erro
1f930 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f r code, [SQLITE_
1f940 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e ERROR], followin
1f950 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f g any.** error o
1f960 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
1f970 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c E_BUSY] and [SQL
1f980 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f ITE_MISUSE]. Yo
1f990 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b u must call.** [
1f9a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
1f9b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e or [sqlite3_fin
1f9c0 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 alize()] in orde
1f9d0 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 r to find one of
1f9e0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 the.** specific
1f9f0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 [error codes] t
1fa00 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 hat better descr
1fa10 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a ibes the error..
1fa20 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 ** We admit that
1fa30 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 this is a goofy
1fa40 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 design. The pr
1fa50 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 oblem has been f
1fa60 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 ixed.** with the
1fa70 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e "v2" interface.
1fa80 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 If you prepare
1fa90 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c all of your SQL
1faa0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 statements.** u
1fab0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c sing either [sql
1fac0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1fad0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
1fae0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 repare16_v2()] i
1faf0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 nstead.** of the
1fb00 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 legacy [sqlite3
1fb10 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 _prepare()] and
1fb20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1fb30 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 16()] interfaces
1fb40 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f ,.** then the mo
1fb50 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 re specific [err
1fb60 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 or codes] are re
1fb70 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a turned directly.
1fb80 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 ** by sqlite3_st
1fb90 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f ep(). The use o
1fba0 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 f the "v2" inter
1fbb0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e face is recommen
1fbc0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ded..**.** Requi
1fbd0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 rements:.** [H13
1fbe0 32 30 32 5d 20 5b 48 31 35 33 30 34 5d 20 5b 48 202] [H15304] [H
1fbf0 31 35 33 30 36 5d 20 5b 48 31 35 33 30 38 5d 20 15306] [H15308]
1fc00 5b 48 31 35 33 31 30 5d 0a 2a 2f 0a 69 6e 74 20 [H15310].*/.int
1fc10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c sqlite3_step(sql
1fc20 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
1fc30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 .** CAPI3REF: Nu
1fc40 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
1fc50 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 in a result set
1fc60 7b 48 31 33 37 37 30 7d 20 3c 53 31 30 37 30 30 {H13770} <S10700
1fc70 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 >.**.** Returns
1fc80 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 the number of va
1fc90 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 lues in the curr
1fca0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 ent row of the r
1fcb0 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a esult set..**.**
1fcc0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
1fcd0 2a 20 5b 48 31 33 37 37 31 5d 20 5b 48 31 33 37 * [H13771] [H137
1fce0 37 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 72].*/.int sqlit
1fcf0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 e3_data_count(sq
1fd00 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
1fd10 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
1fd20 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c REF: Fundamental
1fd30 20 44 61 74 61 74 79 70 65 73 20 7b 48 31 30 32 Datatypes {H102
1fd40 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53 31 30 65} <S10110><S10
1fd50 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 120>.** KEYWORDS
1fd60 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a : SQLITE_TEXT.**
1fd70 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45 76 65 .** {H10266} Eve
1fd80 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 ry value in SQLi
1fd90 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 te has one of fi
1fda0 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 ve fundamental d
1fdb0 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 atatypes:.**.**
1fdc0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d <ul>.** <li> 64-
1fdd0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
1fde0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 er.** <li> 64-bi
1fdf0 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 t IEEE floating
1fe00 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 point number.**
1fe10 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c <li> string.** <
1fe20 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e li> BLOB.** <li>
1fe30 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b NULL.** </ul> {
1fe40 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 END}.**.** These
1fe50 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 constants are c
1fe60 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 odes for each of
1fe70 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a those types..**
1fe80 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 .** Note that th
1fe90 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f e SQLITE_TEXT co
1fea0 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 nstant was also
1feb0 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 used in SQLite v
1fec0 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 ersion 2.** for
1fed0 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 a completely dif
1fee0 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 ferent meaning.
1fef0 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c Software that l
1ff00 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 inks against bot
1ff10 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 h.** SQLite vers
1ff20 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 ion 2 and SQLite
1ff30 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c version 3 shoul
1ff40 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 d use SQLITE3_TE
1ff50 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 XT, not.** SQLIT
1ff60 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 E_TEXT..*/.#defi
1ff70 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 ne SQLITE_INTEGE
1ff80 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c R 1.#define SQL
1ff90 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 ITE_FLOAT 2.#
1ffa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c define SQLITE_BL
1ffb0 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 OB 4.#define
1ffc0 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 SQLITE_NULL
1ffd0 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5.#ifdef SQLITE
1ffe0 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 _TEXT.# undef SQ
1fff0 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a LITE_TEXT.#else.
20000 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
20010 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 TEXT 3.#endi
20020 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 f.#define SQLITE
20030 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 3_TEXT 3../*
20040 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
20050 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d sult Values From
20060 20 41 20 51 75 65 72 79 20 7b 48 31 33 38 30 30 A Query {H13800
20070 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 } <S10700>.** KE
20080 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 YWORDS: {column
20090 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 access functions
200a0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f }.**.** These ro
200b0 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 utines form the
200c0 22 72 65 73 75 6c 74 20 73 65 74 20 71 75 65 72 "result set quer
200d0 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a y" interface..**
200e0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
200f0 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d es return inform
20100 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 ation about a si
20110 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 ngle column of t
20120 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 he current.** re
20130 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 sult row of a qu
20140 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79 20 63 ery. In every c
20150 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 ase the first ar
20160 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
20170 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 ter.** to the [p
20180 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
20190 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 t] that is being
201a0 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 evaluated (the
201b0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a [sqlite3_stmt*].
201c0 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 ** that was retu
201d0 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 rned from [sqlit
201e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
201f0 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 or one of its v
20200 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 ariants).** and
20210 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
20220 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 ent is the index
20230 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 of the column f
20240 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 or which informa
20250 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 tion.** should b
20260 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 e returned. The
20270 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e leftmost column
20280 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
20290 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 et has the index
202a0 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 0..**.** If the
202b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 SQL statement d
202c0 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c oes not currentl
202d0 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c y point to a val
202e0 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 id row, or if th
202f0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 e.** column inde
20300 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 x is out of rang
20310 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 e, the result is
20320 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 undefined..** T
20330 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 hese routines ma
20340 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 y only be called
20350 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 when the most r
20360 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a ecent call to.**
20370 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
20380 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b ] has returned [
20390 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 SQLITE_ROW] and
203a0 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 neither.** [sqli
203b0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 te3_reset()] nor
203c0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
203d0 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 ze()] have been
203e0 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e called subsequen
203f0 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f tly..** If any o
20400 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
20410 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 are called afte
20420 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
20430 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
20440 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f e3_finalize()] o
20450 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 r after [sqlite3
20460 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 _step()] has ret
20470 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 urned.** somethi
20480 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 ng other than [S
20490 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 QLITE_ROW], the
204a0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
204b0 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 fined..** If [sq
204c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 lite3_step()] or
204d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
204e0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 )] or [sqlite3_f
204f0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 inalize()].** ar
20500 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 e called from a
20510 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
20520 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 while any of th
20530 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 ese routines.**
20540 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 are pending, the
20550 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 n the results ar
20560 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a e undefined..**.
20570 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
20580 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 olumn_type() rou
20590 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 tine returns the
205a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 .** [SQLITE_INTE
205b0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 GER | datatype c
205c0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 ode] for the ini
205d0 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a tial data type.*
205e0 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 * of the result
205f0 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 column. The ret
20600 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f urned value is o
20610 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e ne of [SQLITE_IN
20620 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 TEGER],.** [SQLI
20630 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 TE_FLOAT], [SQLI
20640 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 TE_TEXT], [SQLIT
20650 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c E_BLOB], or [SQL
20660 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 ITE_NULL]. The
20670 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 value.** returne
20680 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
20690 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e umn_type() is on
206a0 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 ly meaningful if
206b0 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 no type.** conv
206c0 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 ersions have occ
206d0 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 urred as describ
206e0 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 ed below. After
206f0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 a type conversi
20700 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 on,.** the value
20710 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
20720 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
20730 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e () is undefined.
20740 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 Future.** vers
20750 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d ions of SQLite m
20760 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 ay change the be
20770 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 havior of sqlite
20780 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 3_column_type().
20790 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 ** following a t
207a0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a ype conversion..
207b0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 **.** If the res
207c0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 ult is a BLOB or
207d0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 UTF-8 string th
207e0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 en the sqlite3_c
207f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a olumn_bytes().**
20800 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
20810 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
20820 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f ytes in that BLO
20830 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 B or string..**
20840 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
20850 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 a UTF-16 string
20860 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 , then sqlite3_c
20870 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f olumn_bytes() co
20880 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 nverts.** the st
20890 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e ring to UTF-8 an
208a0 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 d then returns t
208b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
208c0 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 es..** If the re
208d0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 sult is a numeri
208e0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c c value then sql
208f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
20900 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c s() uses.** [sql
20910 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
20920 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 to convert that
20930 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d value to a UTF-
20940 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 8 string and ret
20950 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 urns.** the numb
20960 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
20970 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 hat string..** T
20980 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
20990 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 d does not inclu
209a0 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d de the zero term
209b0 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e inator at the en
209c0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 d.** of the stri
209d0 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 ng. For clarity
209e0 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 : the value retu
209f0 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 rned is the numb
20a00 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 er of.** bytes i
20a10 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f n the string, no
20a20 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
20a30 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a characters..**.*
20a40 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e * Strings return
20a50 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
20a60 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 lumn_text() and
20a70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
20a80 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e ext16(),.** even
20a90 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 empty strings,
20aa0 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 are always zero
20ab0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 terminated. The
20ac0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 return.** value
20ad0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f from sqlite3_co
20ae0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 lumn_blob() for
20af0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c a zero-length BL
20b00 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 OB is an arbitra
20b10 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 ry.** pointer, p
20b20 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e ossibly even a N
20b30 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
20b40 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
20b50 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
20b60 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c routine is simil
20b70 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ar to sqlite3_co
20b80 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 lumn_bytes().**
20b90 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 but leaves the r
20ba0 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 esult in UTF-16
20bb0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f in native byte o
20bc0 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 rder instead of
20bd0 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 UTF-8..** The ze
20be0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 ro terminator is
20bf0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e not included in
20c00 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a this count..**.
20c10 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 ** The object re
20c20 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
20c30 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
20c40 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 )] is an.** [unp
20c50 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
20c60 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 _value] object.
20c70 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 An unprotected
20c80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
20c90 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 ject.** may only
20ca0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 be used with [s
20cb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 qlite3_bind_valu
20cc0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
20cd0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
20ce0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e ]..** If the [un
20cf0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
20d00 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
20d10 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
20d20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
20d30 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 alue()] is used
20d40 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 in any other way
20d50 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c , including call
20d60 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 s.** to routines
20d70 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 like [sqlite3_v
20d80 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 alue_int()], [sq
20d90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
20da0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 ()],.** or [sqli
20db0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
20dc0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 )], then the beh
20dd0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
20de0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ed..**.** These
20df0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 routines attempt
20e00 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 to convert the
20e10 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 value where appr
20e20 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a opriate. For.**
20e30 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 example, if the
20e40 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 internal repres
20e50 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 entation is FLOA
20e60 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 T and a text res
20e70 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 ult.** is reques
20e80 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e ted, [sqlite3_sn
20e90 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 printf()] is use
20ea0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 d internally to
20eb0 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 perform the.** c
20ec0 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 onversion automa
20ed0 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f tically. The fo
20ee0 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 llowing table de
20ef0 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 tails the conver
20f00 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 sions.** that ar
20f10 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a e applied:.**.**
20f20 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a <blockquote>.**
20f30 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 <table border="
20f40 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 1">.** <tr><th>
20f50 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 Internal<br>Type
20f60 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c <th> Requested<
20f70 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f br>Type <th> Co
20f80 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c nversion.**.** <
20f90 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
20fa0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
20fb0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 <td> Result is 0
20fc0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
20fd0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 LL <td> FLOA
20fe0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 T <td> Result
20ff0 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c is 0.0.** <tr><
21000 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 td> NULL <td
21010 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
21020 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 Result is NULL
21030 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c pointer.** <tr><
21040 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 td> NULL <td
21050 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
21060 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 Result is NULL
21070 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c pointer.** <tr><
21080 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 td> INTEGER <td
21090 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
210a0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e Convert from in
210b0 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a teger to float.*
210c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 * <tr><td> INTEG
210d0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 ER <td> TEXT
210e0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 <td> ASCII re
210f0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 ndering of the i
21100 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 nteger.** <tr><t
21110 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e d> INTEGER <td>
21120 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
21130 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d Same as INTEGER-
21140 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 >TEXT.** <tr><td
21150 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
21160 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 INTEGER <td> C
21170 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 onvert from floa
21180 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 t to integer.**
21190 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <tr><td> FLOAT
211a0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
211b0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 <td> ASCII rend
211c0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f ering of the flo
211d0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 at.** <tr><td>
211e0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 FLOAT <td> B
211f0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 LOB <td> Same
21200 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a as FLOAT->TEXT.
21210 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 ** <tr><td> TEX
21220 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 T <td> INTEGE
21230 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f R <td> Use ato
21240 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 i().** <tr><td>
21250 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 TEXT <td> F
21260 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 LOAT <td> Use
21270 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c atof().** <tr><
21280 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 td> TEXT <td
21290 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
212a0 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 No change.** <t
212b0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 r><td> BLOB
212c0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
212d0 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 td> Convert to T
212e0 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f EXT then use ato
212f0 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 i().** <tr><td>
21300 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 BLOB <td> F
21310 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e LOAT <td> Con
21320 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 vert to TEXT the
21330 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 n use atof().**
21340 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 <tr><td> BLOB
21350 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
21360 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f <td> Add a zero
21370 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e terminator if n
21380 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 eeded.** </table
21390 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 >.** </blockquot
213a0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 e>.**.** The tab
213b0 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 le above makes r
213c0 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e eference to stan
213d0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 dard C library f
213e0 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a unctions atoi().
213f0 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 ** and atof().
21400 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 SQLite does not
21410 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 really use these
21420 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 functions. It
21430 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 has its.** own e
21440 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e quivalent intern
21450 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 al routines. Th
21460 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f e atoi() and ato
21470 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a f() names are.**
21480 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 used in the tab
21490 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 le for brevity a
214a0 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 nd because they
214b0 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 are familiar to
214c0 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 most.** C progra
214d0 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 mmers..**.** Not
214e0 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 e that when type
214f0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 conversions occ
21500 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 ur, pointers ret
21510 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a urned by prior.*
21520 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 * calls to sqlit
21530 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
21540 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e , sqlite3_column
21550 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a _text(), and/or.
21560 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
21570 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 n_text16() may b
21580 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a e invalidated..*
21590 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f * Type conversio
215a0 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 ns and pointer i
215b0 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 nvalidations mig
215c0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 ht occur.** in t
215d0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 he following cas
215e0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a es:.**.** <ul>.*
215f0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 * <li> The initi
21600 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 al content is a
21610 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 BLOB and sqlite3
21620 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f _column_text() o
21630 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 r.** sqlite
21640 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
21650 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 ) is called. A
21660 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 zero-terminator
21670 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 might.** ne
21680 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 ed to be added t
21690 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c o the string.</l
216a0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 i>.** <li> The i
216b0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
216c0 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 s UTF-8 text and
216d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
216e0 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 bytes16() or.**
216f0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c sqlite3_col
21700 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 umn_text16() is
21710 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e called. The con
21720 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e tent must be con
21730 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 verted.** t
21740 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a o UTF-16.</li>.*
21750 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 * <li> The initi
21760 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 al content is UT
21770 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 F-16 text and sq
21780 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
21790 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 es() or.**
217a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
217b0 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e ext() is called.
217c0 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 The content mu
217d0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a st be converted.
217e0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 ** to UTF-8
217f0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a .</li>.** </ul>.
21800 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e **.** Conversion
21810 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 s between UTF-16
21820 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 be and UTF-16le
21830 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 are always done
21840 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a in place and do.
21850 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 ** not invalidat
21860 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 e a prior pointe
21870 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 r, though of cou
21880 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 rse the content
21890 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a of the buffer.**
218a0 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 that the prior
218b0 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 pointer points t
218c0 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e o will have been
218d0 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 modified. Othe
218e0 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f r kinds.** of co
218f0 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e nversion are don
21900 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 e in place when
21910 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 it is possible,
21920 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 but sometimes th
21930 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f ey.** are not po
21940 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 ssible and in th
21950 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 ose cases prior
21960 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 pointers are inv
21970 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 alidated..**.**
21980 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 The safest and e
21990 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 asiest to rememb
219a0 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 er policy is to
219b0 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 invoke these rou
219c0 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 tines.** in one
219d0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
219e0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c ways:.**.** <ul
219f0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 >.** <li>sqlite
21a00 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
21a10 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 followed by sqli
21a20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
21a30 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e ()</li>.** <li>
21a40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
21a50 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 lob() followed b
21a60 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
21a70 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a _bytes()</li>.**
21a80 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f <li>sqlite3_co
21a90 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f lumn_text16() fo
21aa0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 llowed by sqlite
21ab0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
21ac0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e ()</li>.** </ul>
21ad0 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 .**.** In other
21ae0 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c words, you shoul
21af0 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 d call sqlite3_c
21b00 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a olumn_text(),.**
21b10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
21b20 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 blob(), or sqlit
21b30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
21b40 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 () first to forc
21b50 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 e the result.**
21b60 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 into the desired
21b70 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e format, then in
21b80 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c voke sqlite3_col
21b90 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a umn_bytes() or.*
21ba0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
21bb0 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 _bytes16() to fi
21bc0 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 nd the size of t
21bd0 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e he result. Do n
21be0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 ot mix calls.**
21bf0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
21c00 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 n_text() or sqli
21c10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
21c20 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a ) with calls to.
21c30 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
21c40 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 n_bytes16(), and
21c50 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c do not mix call
21c60 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c s to sqlite3_col
21c70 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 umn_text16().**
21c80 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 with calls to sq
21c90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
21ca0 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 es()..**.** The
21cb0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
21cc0 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 d are valid unti
21cd0 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 l a type convers
21ce0 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a ion occurs as.**
21cf0 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 described above
21d00 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 , or until [sqli
21d10 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b te3_step()] or [
21d20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
21d30 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
21d40 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 finalize()] is c
21d50 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f alled. The memo
21d60 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f ry space used to
21d70 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a hold strings.**
21d80 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 and BLOBs is fr
21d90 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c eed automaticall
21da0 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 y. Do <b>not</b
21db0 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 > pass the point
21dc0 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 ers returned.**
21dd0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
21de0 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 blob()], [sqlite
21df0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 3_column_text()]
21e00 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b , etc. into.** [
21e10 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e sqlite3_free()].
21e20 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f .**.** If a memo
21e30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 ry allocation er
21e40 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e ror occurs durin
21e50 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e g the evaluation
21e60 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 of any.** of th
21e70 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 ese routines, a
21e80 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 default value is
21e90 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 returned. The
21ea0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a default value.**
21eb0 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 is either the i
21ec0 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c nteger 0, the fl
21ed0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d oating point num
21ee0 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 ber 0.0, or a NU
21ef0 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 LL.** pointer.
21f00 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 Subsequent calls
21f10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 to [sqlite3_err
21f20 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 code()] will ret
21f30 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e urn.** [SQLITE_N
21f40 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 OMEM]..**.** Req
21f50 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
21f60 31 33 38 30 33 5d 20 5b 48 31 33 38 30 36 5d 20 13803] [H13806]
21f70 5b 48 31 33 38 30 39 5d 20 5b 48 31 33 38 31 32 [H13809] [H13812
21f80 5d 20 5b 48 31 33 38 31 35 5d 20 5b 48 31 33 38 ] [H13815] [H138
21f90 31 38 5d 20 5b 48 31 33 38 32 31 5d 20 5b 48 31 18] [H13821] [H1
21fa0 33 38 32 34 5d 0a 2a 2a 20 5b 48 31 33 38 32 37 3824].** [H13827
21fb0 5d 20 5b 48 31 33 38 33 30 5d 0a 2a 2f 0a 63 6f ] [H13830].*/.co
21fc0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
21fd0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 3_column_blob(sq
21fe0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
21ff0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 iCol);.int sqli
22000 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
22010 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
22020 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 int iCol);.int s
22030 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
22040 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 tes16(sqlite3_st
22050 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
22060 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 double sqlite3_c
22070 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c olumn_double(sql
22080 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
22090 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 iCol);.int sqlit
220a0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 e3_column_int(sq
220b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
220c0 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f iCol);.sqlite3_
220d0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f int64 sqlite3_co
220e0 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 lumn_int64(sqlit
220f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
22100 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 ol);.const unsig
22110 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 ned char *sqlite
22120 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 3_column_text(sq
22130 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
22140 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f iCol);.const vo
22150 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
22160 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 mn_text16(sqlite
22170 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
22180 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
22190 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 column_type(sqli
221a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
221b0 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 Col);.sqlite3_va
221c0 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c lue *sqlite3_col
221d0 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 umn_value(sqlite
221e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
221f0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
22200 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 REF: Destroy A P
22210 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
22220 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 30 30 t Object {H13300
22230 7d 20 3c 53 37 30 33 30 30 3e 3c 53 33 30 31 30 } <S70300><S3010
22240 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0>.**.** The sql
22250 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 ite3_finalize()
22260 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c function is call
22270 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b ed to delete a [
22280 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
22290 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 nt]..** If the s
222a0 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65 tatement was exe
222b0 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c cuted successful
222c0 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 ly or not execut
222d0 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a ed at all, then.
222e0 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 ** SQLITE_OK is
222f0 72 65 74 75 72 6e 65 64 2e 20 49 66 20 65 78 65 returned. If exe
22300 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 cution of the st
22310 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 atement failed t
22320 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 hen an.** [error
22330 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e code] or [exten
22340 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 ded error code]
22350 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
22360 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
22370 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 can be called at
22380 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e any point durin
22390 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 g the execution
223a0 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 of the.** [prepa
223b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 red statement].
223c0 20 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 If the virtual
223d0 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a machine has not.
223e0 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 ** completed exe
223f0 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 cution when this
22400 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c routine is call
22410 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 ed, that is like
22420 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 .** encountering
22430 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 an error or an
22440 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 [sqlite3_interru
22450 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e pt | interrupt].
22460 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 .** Incomplete u
22470 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f pdates may be ro
22480 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 lled back and tr
22490 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 ansactions cance
224a0 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e led,.** dependin
224b0 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 g on the circums
224c0 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a tances, and the.
224d0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ** [error code]
224e0 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 returned will be
224f0 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e [SQLITE_ABORT].
22500 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
22510 6e 74 73 3a 0a 2a 2a 20 5b 48 31 31 33 30 32 5d nts:.** [H11302]
22520 20 5b 48 31 31 33 30 34 5d 0a 2a 2f 0a 69 6e 74 [H11304].*/.int
22530 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
22540 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a e(sqlite3_stmt *
22550 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
22560 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 API3REF: Reset A
22570 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
22580 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 ent Object {H133
22590 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 30} <S70300>.**.
225a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
225b0 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 eset() function
225c0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 is called to res
225d0 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 et a [prepared s
225e0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a tatement].** obj
225f0 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 ect back to its
22600 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 initial state, r
22610 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 eady to be re-ex
22620 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 ecuted..** Any S
22630 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 QL statement var
22640 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 iables that had
22650 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 values bound to
22660 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 them using.** th
22670 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
22680 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 blob | sqlite3_b
22690 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 ind_*() API] ret
226a0 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 ain their values
226b0 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 ..** Use [sqlite
226c0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 3_clear_bindings
226d0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 ()] to reset the
226e0 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a bindings..**.**
226f0 20 7b 48 31 31 33 33 32 7d 20 54 68 65 20 5b 73 {H11332} The [s
22700 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
22710 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 interface reset
22720 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 s the [prepared
22730 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 statement] S.**
22740 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f back to
22750 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f the beginning o
22760 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a f its program..*
22770 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49 66 *.** {H11334} If
22780 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
22790 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
227a0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 3_step(S)] for t
227b0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
227c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
227d0 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b nt] S returned [
227e0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b SQLITE_ROW] or [
227f0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a SQLITE_DONE],.**
22800 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 or if
22810 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
22820 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f ] has never befo
22830 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f re been called o
22840 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 n S,.**
22850 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 then [sqlite3_r
22860 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 eset(S)] returns
22870 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a [SQLITE_OK]..**
22880 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 66 20 .** {H11336} If
22890 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
228a0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
228b0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 _step(S)] for th
228c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 e.** [p
228d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
228e0 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 t] S indicated a
228f0 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a n error, then.**
22900 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
22910 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 e3_reset(S)] ret
22920 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 urns an appropri
22930 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ate [error code]
22940 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d ..**.** {H11338}
22950 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 The [sqlite3_re
22960 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 set(S)] interfac
22970 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 e does not chang
22980 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 e the values.**
22990 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20 of any
229a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
229b0 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 ob|bindings] on
229c0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
229d0 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 atement] S..*/.i
229e0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 nt sqlite3_reset
229f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
22a00 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
22a10 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f PI3REF: Create O
22a20 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 r Redefine SQL F
22a30 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 30 30 unctions {H16100
22a40 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 } <S20200>.** KE
22a50 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f YWORDS: {functio
22a60 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 n creation routi
22a70 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 nes}.** KEYWORDS
22a80 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 : {application-d
22a90 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
22aa0 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ion}.** KEYWORDS
22ab0 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 : {application-d
22ac0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
22ad0 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ions}.**.** Thes
22ae0 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 e two functions
22af0 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e (collectively kn
22b00 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e own as "function
22b10 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e creation routin
22b20 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 es").** are used
22b30 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 to add SQL func
22b40 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 tions or aggrega
22b50 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 tes or to redefi
22b60 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a ne the behavior.
22b70 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 ** of existing S
22b80 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 QL functions or
22b90 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 aggregates. The
22ba0 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 only difference
22bb0 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 between the.**
22bc0 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 two is that the
22bd0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
22be0 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 , the name of th
22bf0 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 e (scalar) funct
22c00 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 ion or.** aggreg
22c10 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 ate, is encoded
22c20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c in UTF-8 for sql
22c30 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
22c40 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 tion() and UTF-1
22c50 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 6.** for sqlite3
22c60 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
22c70 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 16()..**.** The
22c80 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
22c90 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 is the [database
22ca0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 connection] to
22cb0 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a which the SQL.**
22cc0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 function is to
22cd0 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 61 20 be added. If a
22ce0 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20 75 single program u
22cf0 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e ses more than on
22d00 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f e database.** co
22d10 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61 nnection interna
22d20 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 66 75 lly, then SQL fu
22d30 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 nctions must be
22d40 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c added individual
22d50 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61 ly to.** each da
22d60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
22d70 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 n..**.** The sec
22d80 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
22d90 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
22da0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f SQL function to
22db0 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a be created or.*
22dc0 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 54 68 * redefined. Th
22dd0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 e length of the
22de0 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 name is limited
22df0 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 to 255 bytes, ex
22e00 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 clusive of.** th
22e10 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f e zero-terminato
22e20 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 r. Note that th
22e30 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 e name length li
22e40 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c mit is in bytes,
22e50 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 not.** characte
22e60 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 rs. Any attempt
22e70 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e to create a fun
22e80 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e ction with a lon
22e90 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c ger name.** will
22ea0 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 result in [SQLI
22eb0 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 TE_ERROR] being
22ec0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
22ed0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 The third parame
22ee0 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 ter (nArg).** is
22ef0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 the number of a
22f00 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 rguments that th
22f10 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
22f20 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 r.** aggregate t
22f30 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 akes. If this pa
22f40 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 rameter is -1, t
22f50 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 hen the SQL func
22f60 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
22f70 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e gate may take an
22f80 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 y number of argu
22f90 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 ments between 0
22fa0 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a and the limit.**
22fb0 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 set by [sqlite3
22fc0 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f _limit]([SQLITE_
22fd0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 LIMIT_FUNCTION_A
22fe0 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 RG]). If the th
22ff0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ird.** parameter
23000 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 is less than -1
23010 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e or greater than
23020 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 127 then the be
23030 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 havior is.** und
23040 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 efined..**.** Th
23050 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
23060 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 er, eTextRep, sp
23070 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 ecifies what.**
23080 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 [SQLITE_UTF8 | t
23090 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 ext encoding] th
230a0 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 is SQL function
230b0 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 prefers for.** i
230c0 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ts parameters.
230d0 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e Any SQL function
230e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
230f0 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74 should be able t
23100 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 o work.** work w
23110 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 ith UTF-8, UTF-1
23120 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 6le, or UTF-16be
23130 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c . But some impl
23140 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 ementations may
23150 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 be.** more effic
23160 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e ient with one en
23170 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 coding than anot
23180 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f her. It is allo
23190 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 wed to.** invoke
231a0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
231b0 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 function() or sq
231c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
231d0 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 ction16() multip
231e0 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 le.** times with
231f0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 the same functi
23200 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 on but with diff
23210 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 erent values of
23220 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 eTextRep..** Whe
23230 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 n multiple imple
23240 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 mentations of th
23250 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 e same function
23260 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 are available, S
23270 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 QLite.** will pi
23280 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 ck the one that
23290 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 involves the lea
232a0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 st amount of dat
232b0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a a conversion..**
232c0 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c If there is onl
232d0 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 y a single imple
232e0 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 mentation which
232f0 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 does not care wh
23300 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 at text.** encod
23310 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 ing is used, the
23320 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 n the fourth arg
23330 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 ument should be
23340 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a [SQLITE_ANY]..**
23350 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 .** The fifth pa
23360 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 rameter is an ar
23370 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e bitrary pointer.
23380 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 The implementa
23390 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 tion of the.** f
233a0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e unction can gain
233b0 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 access to this
233c0 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 pointer using [s
233d0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 qlite3_user_data
233e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ()]..**.** The s
233f0 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 eventh, eighth a
23400 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 nd ninth paramet
23410 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 ers, xFunc, xSte
23420 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 p and xFinal, ar
23430 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f e.** pointers to
23440 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 C-language func
23450 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 tions that imple
23460 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e ment the SQL fun
23470 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
23480 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 egate. A scalar
23490 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 SQL function req
234a0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 uires an impleme
234b0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 ntation of the x
234c0 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b Func.** callback
234d0 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e only, NULL poin
234e0 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 ters should be p
234f0 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 assed as the xSt
23500 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a ep and xFinal.**
23510 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 parameters. An
23520 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
23530 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 nction requires
23540 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f an implementatio
23550 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e n of xStep.** an
23560 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c d xFinal and NUL
23570 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 L should be pass
23580 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f ed for xFunc. To
23590 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 delete an exist
235a0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 ing.** SQL funct
235b0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
235c0 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 , pass NULL for
235d0 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 all three functi
235e0 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a on callbacks..**
235f0 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 .** It is permit
23600 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 ted to register
23610 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 multiple impleme
23620 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ntations of the
23630 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e same.** function
23640 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 s with the same
23650 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 name but with ei
23660 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e ther differing n
23670 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 umbers of.** arg
23680 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 uments or differ
23690 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 ing preferred te
236a0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 xt encodings. S
236b0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a QLite will use.*
236c0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 * the implementa
236d0 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c tion most closel
236e0 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 y matches the wa
236f0 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a y in which the.*
23700 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 * SQL function i
23710 73 20 75 73 65 64 2e 20 20 41 20 66 75 6e 63 74 s used. A funct
23720 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ion implementati
23730 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 on with a non-ne
23740 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 gative.** nArg p
23750 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 arameter is a be
23760 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 tter match than
23770 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 a function imple
23780 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a mentation with.*
23790 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 * a negative nAr
237a0 67 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 g. A function w
237b0 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 here the preferr
237c0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 ed text encoding
237d0 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 .** matches the
237e0 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e database encodin
237f0 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a g is a better.**
23800 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 match than a fu
23810 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 nction where the
23820 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 encoding is dif
23830 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 41 20 66 ferent. .** A f
23840 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
23850 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 e encoding diffe
23860 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e rence is between
23870 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 UTF16le and UTF
23880 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 16be.** is a clo
23890 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 ser match than a
238a0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
238b0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 the encoding dif
238c0 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 ference is.** be
238d0 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 tween UTF8 and U
238e0 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 42 75 69 6c TF16..**.** Buil
238f0 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d t-in functions m
23900 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 ay be overloaded
23910 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 by new applicat
23920 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
23930 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 66 69 tions..** The fi
23940 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d rst application-
23950 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
23960 20 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61 with a given na
23970 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c me overrides all
23980 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e .** built-in fun
23990 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 ctions in the sa
239a0 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e me [database con
239b0 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 nection] with th
239c0 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 e same name..**
239d0 53 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69 Subsequent appli
239e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
239f0 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 unctions of the
23a00 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f same name only o
23a10 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f verride .** prio
23a20 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 r application-de
23a30 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 fined functions
23a40 74 68 61 74 20 61 72 65 20 61 6e 20 65 78 61 63 that are an exac
23a50 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a t match for the.
23a60 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 ** number of par
23a70 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65 66 ameters and pref
23a80 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a erred encoding..
23a90 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70 6c 69 63 61 **.** An applica
23aa0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
23ab0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 ction is permitt
23ac0 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 ed to call other
23ad0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 .** SQLite inter
23ae0 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c faces. However,
23af0 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 such calls must
23b00 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 not.** close th
23b10 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
23b20 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 ction nor finali
23b30 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 ze or reset the
23b40 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 prepared.** stat
23b50 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 ement in which t
23b60 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 he function is r
23b70 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 unning..**.** Re
23b80 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
23b90 48 31 36 31 30 33 5d 20 5b 48 31 36 31 30 36 5d H16103] [H16106]
23ba0 20 5b 48 31 36 31 30 39 5d 20 5b 48 31 36 31 31 [H16109] [H1611
23bb0 32 5d 20 5b 48 31 36 31 31 38 5d 20 5b 48 31 36 2] [H16118] [H16
23bc0 31 32 31 5d 20 5b 48 31 36 31 32 37 5d 0a 2a 2a 121] [H16127].**
23bd0 20 5b 48 31 36 31 33 30 5d 20 5b 48 31 36 31 33 [H16130] [H1613
23be0 33 5d 20 5b 48 31 36 31 33 36 5d 20 5b 48 31 36 3] [H16136] [H16
23bf0 31 33 39 5d 20 5b 48 31 36 31 34 32 5d 0a 2a 2f 139] [H16142].*/
23c00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
23c10 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 ate_function(.
23c20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
23c30 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 onst char *zFunc
23c40 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 tionName,. int
23c50 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 nArg,. int eTex
23c60 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 tRep,. void *pA
23c70 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 pp,. void (*xFu
23c80 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
23c90 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
23ca0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
23cb0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
23cc0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
23cd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
23ce0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
23cf0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
23d00 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 xt*).);.int sqli
23d10 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
23d20 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 ion16(. sqlite3
23d30 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f *db,. const vo
23d40 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d id *zFunctionNam
23d50 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 e,. int nArg,.
23d60 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 int eTextRep,.
23d70 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 void *pApp,. v
23d80 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c oid (*xFunc)(sql
23d90 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
23da0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
23db0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 *),. void (*xSt
23dc0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ep)(sqlite3_cont
23dd0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
23de0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
23df0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 d (*xFinal)(sqli
23e00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b te3_context*).);
23e10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
23e20 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 : Text Encodings
23e30 20 7b 48 31 30 32 36 37 7d 20 3c 53 35 30 32 30 {H10267} <S5020
23e40 30 3e 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 0> <H16100>.**.*
23e50 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
23e60 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 define integer
23e70 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 codes that repre
23e80 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 sent the various
23e90 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e .** text encodin
23ea0 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 gs supported by
23eb0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 SQLite..*/.#defi
23ec0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 ne SQLITE_UTF8
23ed0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 1.#defi
23ee0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c ne SQLITE_UTF16L
23ef0 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 E 2.#defi
23f00 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 ne SQLITE_UTF16B
23f10 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 E 3.#defi
23f20 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 ne SQLITE_UTF16
23f30 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 4 /*
23f40 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 Use native byte
23f50 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e order */.#defin
23f60 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 e SQLITE_ANY
23f70 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 5 /*
23f80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
23f90 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a unction only */.
23fa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
23fb0 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 TF16_ALIGNED 8
23fc0 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 /* sqlite3_cr
23fd0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f eate_collation o
23fe0 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 nly */../*.** CA
23ff0 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 PI3REF: Deprecat
24000 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 ed Functions.**
24010 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a DEPRECATED.**.**
24020 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 These functions
24030 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 are [deprecated
24040 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 ]. In order to
24050 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b maintain.** back
24060 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
24070 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 ity with older c
24080 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 ode, these funct
24090 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a ions continue .*
240a0 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 * to be supporte
240b0 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 d. However, new
240c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 applications sh
240d0 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 ould avoid.** th
240e0 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 e use of these f
240f0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 unctions. To he
24100 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f lp encourage peo
24110 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 ple to avoid.**
24120 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 using these func
24130 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f tions, we are no
24140 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 t going to tell
24150 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f you what they do
24160 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c ..*/.#ifndef SQL
24170 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 ITE_OMIT_DEPRECA
24180 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 TED.SQLITE_DEPRE
24190 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
241a0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 3_aggregate_coun
241b0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
241c0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 t*);.SQLITE_DEPR
241d0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
241e0 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 e3_expired(sqlit
241f0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 e3_stmt*);.SQLIT
24200 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
24210 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 sqlite3_transfe
24220 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 r_bindings(sqlit
24230 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 e3_stmt*, sqlite
24240 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 3_stmt*);.SQLITE
24250 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 _DEPRECATED int
24260 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 sqlite3_global_r
24270 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 ecover(void);.SQ
24280 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
24290 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 void sqlite3_thr
242a0 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 ead_cleanup(void
242b0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 );.SQLITE_DEPREC
242c0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 ATED int sqlite3
242d0 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f _memory_alarm(vo
242e0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 id(*)(void*,sqli
242f0 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 te3_int64,int),v
24300 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
24310 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 64);.#endif../*.
24320 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 ** CAPI3REF: Obt
24330 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 aining SQL Funct
24340 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 ion Parameter Va
24350 6c 75 65 73 20 7b 48 31 35 31 30 30 7d 20 3c 53 lues {H15100} <S
24360 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20200>.**.** The
24370 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c C-language impl
24380 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 ementation of SQ
24390 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 L functions and
243a0 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a aggregates uses.
243b0 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 ** this set of i
243c0 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 nterface routine
243d0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 s to access the
243e0 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 parameter values
243f0 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 on.** the funct
24400 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
24410 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e ..**.** The xFun
24420 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 c (for scalar fu
24430 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 nctions) or xSte
24440 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 p (for aggregate
24450 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a s) parameters.**
24460 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 to [sqlite3_cre
24470 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 ate_function()]
24480 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 and [sqlite3_cre
24490 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
244a0 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c ].** define call
244b0 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 backs that imple
244c0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e ment the SQL fun
244d0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 ctions and aggre
244e0 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 gates..** The 4t
244f0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
24500 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 hese callbacks i
24510 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
24520 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 inters to.** [pr
24530 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
24540 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 value] objects.
24550 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 There is one [s
24560 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
24570 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 ject for.** each
24580 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
24590 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 e SQL function.
245a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
245b0 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 are used to.** e
245c0 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 xtract values fr
245d0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f om the [sqlite3_
245e0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a value] objects..
245f0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
24600 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 ines work only w
24610 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 ith [protected s
24620 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
24630 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 jects..** Any at
24640 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 tempt to use the
24650 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 se routines on a
24660 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 n [unprotected s
24670 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
24680 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 object results
24690 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 in undefined beh
246a0 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 avior..**.** The
246b0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b se routines work
246c0 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 just like the c
246d0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f orresponding [co
246e0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 lumn access func
246f0 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 tions].** except
24700 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 that these rou
24710 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e tines take a sin
24720 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 gle [protected s
24730 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
24740 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 ject.** pointer
24750 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 instead of a [sq
24760 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 lite3_stmt*] poi
24770 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 nter and an inte
24780 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 ger column numbe
24790 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c r..**.** The sql
247a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
247b0 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 6() interface ex
247c0 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 tracts a UTF-16
247d0 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 string.** in the
247e0 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 native byte-ord
247f0 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d er of the host m
24800 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 achine. The.**
24810 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
24820 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c xt16be() and sql
24830 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
24840 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 6le() interfaces
24850 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d .** extract UTF-
24860 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 16 strings as bi
24870 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 g-endian and lit
24880 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 tle-endian respe
24890 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 ctively..**.** T
248a0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
248b0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 _numeric_type()
248c0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
248d0 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e ts to apply.** n
248e0 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 umeric affinity
248f0 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 to the value. T
24900 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 his means that a
24910 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 n attempt is.**
24920 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 made to convert
24930 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 the value to an
24940 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 integer or float
24950 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a ing point. If.*
24960 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 * such a convers
24970 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 ion is possible
24980 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 without loss of
24990 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 information (in
249a0 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 other.** words,
249b0 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 if the value is
249c0 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f a string that lo
249d0 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 oks like a numbe
249e0 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 r).** then the c
249f0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 onversion is per
24a00 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 formed. Otherwi
24a10 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e se no conversion
24a20 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 occurs..** The
24a30 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 [SQLITE_INTEGER
24a40 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 | datatype] afte
24a50 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 r conversion is
24a60 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
24a70 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 Please pay parti
24a80 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 cular attention
24a90 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 to the fact that
24aa0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 the pointer ret
24ab0 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 urned.** from [s
24ac0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f qlite3_value_blo
24ad0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 b()], [sqlite3_v
24ae0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 alue_text()], or
24af0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c .** [sqlite3_val
24b00 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e ue_text16()] can
24b10 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 be invalidated
24b20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 by a subsequent
24b30 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
24b40 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
24b50 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
24b60 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b ue_bytes16()], [
24b70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
24b80 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 xt()],.** or [sq
24b90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
24ba0 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 16()]..**.** The
24bb0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 se routines must
24bc0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
24bd0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
24be0 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 as.** the SQL fu
24bf0 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 nction that supp
24c00 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 lied the [sqlite
24c10 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 3_value*] parame
24c20 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 ters..**.** Requ
24c30 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
24c40 35 31 30 33 5d 20 5b 48 31 35 31 30 36 5d 20 5b 5103] [H15106] [
24c50 48 31 35 31 30 39 5d 20 5b 48 31 35 31 31 32 5d H15109] [H15112]
24c60 20 5b 48 31 35 31 31 35 5d 20 5b 48 31 35 31 31 [H15115] [H1511
24c70 38 5d 20 5b 48 31 35 31 32 31 5d 20 5b 48 31 35 8] [H15121] [H15
24c80 31 32 34 5d 0a 2a 2a 20 5b 48 31 35 31 32 37 5d 124].** [H15127]
24c90 20 5b 48 31 35 31 33 30 5d 20 5b 48 31 35 31 33 [H15130] [H1513
24ca0 33 5d 20 5b 48 31 35 31 33 36 5d 0a 2a 2f 0a 63 3] [H15136].*/.c
24cb0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
24cc0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 e3_value_blob(sq
24cd0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
24ce0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
24cf0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 _bytes(sqlite3_v
24d00 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 alue*);.int sqli
24d10 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 te3_value_bytes1
24d20 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 6(sqlite3_value*
24d30 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 );.double sqlite
24d40 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 3_value_double(s
24d50 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
24d60 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
24d70 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 e_int(sqlite3_va
24d80 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 lue*);.sqlite3_i
24d90 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c nt64 sqlite3_val
24da0 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 ue_int64(sqlite3
24db0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 _value*);.const
24dc0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 unsigned char *s
24dd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
24de0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t(sqlite3_value*
24df0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
24e00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
24e10 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 t16(sqlite3_valu
24e20 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 e*);.const void
24e30 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
24e40 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f ext16le(sqlite3_
24e50 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 value*);.const v
24e60 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c oid *sqlite3_val
24e70 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 ue_text16be(sqli
24e80 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
24e90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
24ea0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ype(sqlite3_valu
24eb0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
24ec0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 _value_numeric_t
24ed0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ype(sqlite3_valu
24ee0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 e*);../*.** CAPI
24ef0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 3REF: Obtain Agg
24f00 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 regate Function
24f10 43 6f 6e 74 65 78 74 20 7b 48 31 36 32 31 30 7d Context {H16210}
24f20 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20200>.**.**
24f30 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 The implementati
24f40 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 on of aggregate
24f50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 SQL functions us
24f60 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 e this routine t
24f70 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 o allocate.** a
24f80 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 74 structure for st
24f90 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 oring their stat
24fa0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 e..**.** The fir
24fb0 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 st time the sqli
24fc0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
24fd0 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20 ntext() routine
24fe0 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a is called for a.
24ff0 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 ** particular ag
25000 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20 gregate, SQLite
25010 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73 allocates nBytes
25020 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f of memory, zero
25030 65 73 20 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d es out that.** m
25040 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 emory, and retur
25050 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
25060 69 74 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e it. On second an
25070 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c d subsequent cal
25080 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ls to.** sqlite3
25090 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
250a0 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d xt() for the sam
250b0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 e aggregate func
250c0 74 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 tion index,.** t
250d0 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 he same buffer i
250e0 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65 20 s returned. The
250f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
25100 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 f the aggregate
25110 63 61 6e 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 can use.** the r
25120 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 eturned buffer t
25130 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 o accumulate dat
25140 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 a..**.** SQLite
25150 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 automatically fr
25160 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 ees the allocate
25170 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 74 68 d buffer when th
25180 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 e aggregate.** q
25190 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a uery concludes..
251a0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
251b0 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 parameter should
251c0 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 be a copy of th
251d0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f e.** [sqlite3_co
251e0 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 ntext | SQL func
251f0 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 tion context] th
25200 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 at is the first
25210 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 parameter.** to
25220 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 the callback rou
25230 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d tine that implem
25240 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 ents the aggrega
25250 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a te function..**.
25260 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
25270 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
25280 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
25290 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 ead in which.**
252a0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 the aggregate SQ
252b0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 L function is ru
252c0 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 nning..**.** Req
252d0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
252e0 31 36 32 31 31 5d 20 5b 48 31 36 32 31 33 5d 20 16211] [H16213]
252f0 5b 48 31 36 32 31 35 5d 20 5b 48 31 36 32 31 37 [H16215] [H16217
25300 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ].*/.void *sqlit
25310 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
25320 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e text(sqlite3_con
25330 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 text*, int nByte
25340 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 s);../*.** CAPI3
25350 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 REF: User Data F
25360 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 or Functions {H1
25370 36 32 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 6240} <S20200>.*
25380 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
25390 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 _user_data() int
253a0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
253b0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
253c0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 pointer that was
253d0 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 the pUserData p
253e0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 arameter (the 5t
253f0 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 h parameter).**
25400 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
25410 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
25420 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 )].** and [sqlit
25430 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
25440 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 on16()] routines
25450 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 that originally
25460 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 .** registered t
25470 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
25480 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
25490 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 {END}.**.** Thi
254a0 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 s routine must b
254b0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
254c0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e e same thread in
254d0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 which.** the ap
254e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
254f0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 d function is ru
25500 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 nning..**.** Req
25510 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
25520 31 36 32 34 33 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 16243].*/.void *
25530 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
25540 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
25550 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
25560 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 3REF: Database C
25570 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 onnection For Fu
25580 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d nctions {H16250}
25590 20 3c 53 36 30 36 30 30 3e 3c 53 32 30 32 30 30 <S60600><S20200
255a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
255b0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 te3_context_db_h
255c0 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 andle() interfac
255d0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 e returns a copy
255e0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 of.** the point
255f0 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 er to the [datab
25600 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
25610 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 (the 1st paramet
25620 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 er).** of the [s
25630 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
25640 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 nction()].** and
25650 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
25660 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 _function16()] r
25670 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 outines that ori
25680 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 ginally.** regis
25690 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 tered the applic
256a0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 ation defined fu
256b0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 nction..**.** Re
256c0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
256d0 48 31 36 32 35 33 5d 0a 2a 2f 0a 73 71 6c 69 74 H16253].*/.sqlit
256e0 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 e3 *sqlite3_cont
256f0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 ext_db_handle(sq
25700 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
25710 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
25720 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c : Function Auxil
25730 69 61 72 79 20 44 61 74 61 20 7b 48 31 36 32 37 iary Data {H1627
25740 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 0} <S20200>.**.*
25750 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 * The following
25760 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 two functions ma
25770 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 y be used by sca
25780 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e lar SQL function
25790 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 s to.** associat
257a0 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 e metadata with
257b0 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e argument values.
257c0 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c If the same val
257d0 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a ue is passed to.
257e0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f ** multiple invo
257f0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 cations of the s
25800 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ame SQL function
25810 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 during query ex
25820 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a ecution, under.*
25830 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 * some circumsta
25840 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 nces the associa
25850 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 ted metadata may
25860 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 be preserved. T
25870 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 his may.** be us
25880 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c ed, for example,
25890 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 to add a regula
258a0 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 r-expression mat
258b0 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 ching scalar.**
258c0 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f function. The co
258d0 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f mpiled version o
258e0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 f the regular ex
258f0 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 pression is stor
25900 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 ed as.** metadat
25910 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 a associated wit
25920 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 h the SQL value
25930 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 passed as the re
25940 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e gular expression
25950 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 .** pattern. Th
25960 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c e compiled regul
25970 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 ar expression ca
25980 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d n be reused on m
25990 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 ultiple.** invoc
259a0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
259b0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 me function so t
259c0 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c hat the original
259d0 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a pattern string.
259e0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 ** does not need
259f0 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 to be recompile
25a00 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 d on each invoca
25a10 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tion..**.** The
25a20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
25a30 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
25a40 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
25a50 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 r to the metadat
25a60 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 a.** associated
25a70 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 by the sqlite3_s
25a80 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e et_auxdata() fun
25a90 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e ction with the N
25aa0 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 th argument.** v
25ab0 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c alue to the appl
25ac0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
25ad0 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 function. If no
25ae0 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 metadata has bee
25af0 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 n ever.** been s
25b00 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 et for the Nth a
25b10 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 rgument of the f
25b20 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 unction, or if t
25b30 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
25b40 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 .** function par
25b50 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 ameter has chang
25b60 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 ed since the met
25b70 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a a-data was set,.
25b80 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ** then sqlite3_
25b90 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 get_auxdata() re
25ba0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
25bb0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nter..**.** The
25bc0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
25bd0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
25be0 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 saves the metada
25bf0 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f ta.** pointed to
25c00 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 by its 3rd para
25c10 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 meter as the met
25c20 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d adata for the N-
25c30 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f th.** argument o
25c40 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
25c50 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
25c60 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a on. Subsequent.
25c70 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ** calls to sqli
25c80 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
25c90 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 ) might return t
25ca0 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 his data, if it
25cb0 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 has.** not been
25cc0 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 destroyed..** If
25cd0 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c it is not NULL,
25ce0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 SQLite will inv
25cf0 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 oke the destruct
25d00 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 or.** function g
25d10 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 iven by the 4th
25d20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
25d30 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
25d40 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 () on.** the met
25d50 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 adata when the c
25d60 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e orresponding fun
25d70 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 ction parameter
25d80 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 changes.** or wh
25d90 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 en the SQL state
25da0 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 ment completes,
25db0 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 whichever comes
25dc0 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c first..**.** SQL
25dd0 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 ite is free to c
25de0 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 all the destruct
25df0 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 or and drop meta
25e00 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 data on any.** p
25e10 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 arameter of any
25e20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 function at any
25e30 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 time. The only
25e40 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 guarantee is tha
25e50 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 t.** the destruc
25e60 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c tor will be call
25e70 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 ed before the me
25e80 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 tadata is droppe
25e90 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 d..**.** In prac
25ea0 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 tice, metadata i
25eb0 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 s preserved betw
25ec0 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c een function cal
25ed0 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 ls for.** expres
25ee0 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 sions that are c
25ef0 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 onstant at compi
25f00 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e le time. This in
25f10 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a cludes literal.*
25f20 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c * values and SQL
25f30 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a variables..**.*
25f40 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
25f50 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
25f60 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
25f70 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a read in which.**
25f80 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
25f90 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a n is running..**
25fa0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
25fb0 3a 0a 2a 2a 20 5b 48 31 36 32 37 32 5d 20 5b 48 :.** [H16272] [H
25fc0 31 36 32 37 34 5d 20 5b 48 31 36 32 37 36 5d 20 16274] [H16276]
25fd0 5b 48 31 36 32 37 37 5d 20 5b 48 31 36 32 37 38 [H16277] [H16278
25fe0 5d 20 5b 48 31 36 32 37 39 5d 0a 2a 2f 0a 76 6f ] [H16279].*/.vo
25ff0 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f id *sqlite3_get_
26000 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f auxdata(sqlite3_
26010 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 context*, int N)
26020 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 ;.void sqlite3_s
26030 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 et_auxdata(sqlit
26040 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
26050 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 N, void*, void
26060 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f (*)(void*));.../
26070 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
26080 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e onstants Definin
26090 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 g Special Destru
260a0 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20 7b 48 ctor Behavior {H
260b0 31 30 32 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a 10280} <S30100>.
260c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 **.** These are
260d0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 special values f
260e0 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f or the destructo
260f0 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 r that is passed
26100 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 in as the.** fi
26110 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 nal argument to
26120 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 routines like [s
26130 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
26140 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 ob()]. If the d
26150 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 estructor.** arg
26160 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f ument is SQLITE_
26170 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 STATIC, it means
26180 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e that the conten
26190 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e t pointer is con
261a0 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c stant.** and wil
261b0 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 l never change.
261c0 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 It does not nee
261d0 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 d to be destroye
261e0 64 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 d. The.** SQLIT
261f0 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 E_TRANSIENT valu
26200 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 e means that the
26210 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 content will li
26220 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a kely change in.*
26230 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 * the near futur
26240 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 e and that SQLit
26250 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 e should make it
26260 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f s own private co
26270 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e py of.** the con
26280 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 tent before retu
26290 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 rning..**.** The
262a0 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 typedef is nece
262b0 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 ssary to work ar
262c0 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e ound problems in
262d0 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 certain.** C++
262e0 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 compilers. See
262f0 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f ticket #2191..*/
26300 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a .typedef void (*
26310 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
26320 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b or_type)(void*);
26330 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
26340 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 STATIC ((sq
26350 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 lite3_destructor
26360 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 _type)0).#define
26370 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e SQLITE_TRANSIEN
26380 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 T ((sqlite3_de
26390 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 structor_type)-1
263a0 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 )../*.** CAPI3RE
263b0 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 F: Setting The R
263c0 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 esult Of An SQL
263d0 46 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34 30 30 Function {H16400
263e0 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a } <S20200>.**.**
263f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
26400 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 are used by the
26410 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 xFunc or xFinal
26420 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a callbacks that.*
26430 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 * implement SQL
26440 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 functions and ag
26450 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a gregates. See.*
26460 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 * [sqlite3_creat
26470 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e e_function()] an
26480 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
26490 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a e_function16()].
264a0 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 ** for additiona
264b0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
264c0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
264d0 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d ions work very m
264e0 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 uch like the [pa
264f0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d rameter binding]
26500 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 family of.** fu
26510 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 nctions used to
26520 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 bind values to h
26530 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 ost parameters i
26540 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 n prepared state
26550 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 ments..** Refer
26560 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 to the [SQL para
26570 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 meter] documenta
26580 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f tion for additio
26590 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
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 62 6c 6f 62 28 29 e3_result_blob()
265c0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
265d0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a the result from.
265e0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f ** an applicatio
265f0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
26600 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f on to be the BLO
26610 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 B whose content
26620 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f is pointed.** to
26630 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 by the second p
26640 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 arameter and whi
26650 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f ch is N bytes lo
26660 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 ng where N is th
26670 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d e.** third param
26680 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eter..**.** The
26690 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a sqlite3_result_z
266a0 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 eroblob() interf
266b0 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 aces set the res
266c0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 ult of.** the ap
266d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
266e0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
266f0 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 a BLOB containi
26700 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 ng all zero.** b
26710 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 ytes and N bytes
26720 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 in size, where
26730 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f N is the value o
26740 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 f the 2nd parame
26750 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ter..**.** The s
26760 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f qlite3_result_do
26770 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 uble() interface
26780 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 sets the result
26790 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c from.** an appl
267a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
267b0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
267c0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
267d0 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a value specified.
267e0 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 ** by its 2nd ar
267f0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 gument..**.** Th
26800 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
26810 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c _error() and sql
26820 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
26830 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a r16() functions.
26840 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 ** cause the imp
26850 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e lemented SQL fun
26860 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 ction to throw a
26870 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 n exception..**
26880 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 SQLite uses the
26890 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 string pointed t
268a0 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 o by the.** 2nd
268b0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c parameter of sql
268c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
268d0 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 r() or sqlite3_r
268e0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a esult_error16().
268f0 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f ** as the text o
26900 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 f an error messa
26910 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65 ge. SQLite inte
26920 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 rprets the error
26930 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 .** message stri
26940 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ng from sqlite3_
26950 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 result_error() a
26960 73 20 55 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a s UTF-8. SQLite.
26970 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 ** interprets th
26980 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 e string from sq
26990 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
269a0 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 or16() as UTF-16
269b0 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 in native.** by
269c0 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68 te order. If th
269d0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
269e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 r to sqlite3_res
269f0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f ult_error().** o
26a00 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
26a10 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 _error16() is ne
26a20 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 gative then SQLi
26a30 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 te takes as the
26a40 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 error.** message
26a50 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 all text up thr
26a60 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a ough the first z
26a70 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a ero character..*
26a80 2a 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 * If the third p
26a90 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
26aa0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
26ab0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 () or.** sqlite3
26ac0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
26ad0 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 ) is non-negativ
26ae0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 e then SQLite ta
26af0 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a kes that many.**
26b00 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 bytes (not char
26b10 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 acters) from the
26b20 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 2nd parameter a
26b30 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 s the error mess
26b40 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 age..** The sqli
26b50 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
26b60 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 () and sqlite3_r
26b70 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a esult_error16().
26b80 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 ** routines make
26b90 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 a private copy
26ba0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 of the error mes
26bb0 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 sage text before
26bc0 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e .** they return.
26bd0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c Hence, the cal
26be0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 ling function ca
26bf0 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a n deallocate or.
26c00 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 ** modify the te
26c10 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 xt after they re
26c20 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 turn without har
26c30 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 m..** The sqlite
26c40 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 3_result_error_c
26c50 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 ode() function c
26c60 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 hanges the error
26c70 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 code.** returne
26c80 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 d by SQLite as a
26c90 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 result of an er
26ca0 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f ror in a functio
26cb0 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a n. By default,.
26cc0 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 ** the error cod
26cd0 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f e is SQLITE_ERRO
26ce0 52 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e 74 R. A subsequent
26cf0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
26d00 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a _result_error().
26d10 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ** or sqlite3_re
26d20 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 sult_error16() r
26d30 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 esets the error
26d40 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 code to SQLITE_E
26d50 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 RROR..**.** The
26d60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
26d70 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 oobig() interfac
26d80 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 e causes SQLite
26d90 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f to throw an erro
26da0 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 r.** indicating
26db0 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 that a string or
26dc0 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 BLOB is to long
26dd0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a to represent..*
26de0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
26df0 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 _result_nomem()
26e00 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 interface causes
26e10 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 SQLite to throw
26e20 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 an error.** ind
26e30 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d icating that a m
26e40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
26e50 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 failed..**.** T
26e60 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
26e70 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 t_int() interfac
26e80 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 e sets the retur
26e90 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 n value.** of th
26ea0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
26eb0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
26ec0 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 o be the 32-bit
26ed0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a signed integer.*
26ee0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e * value given in
26ef0 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e the 2nd argumen
26f00 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 t..** The sqlite
26f10 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 3_result_int64()
26f20 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
26f30 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
26f40 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 .** of the appli
26f50 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
26f60 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 unction to be th
26f70 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 e 64-bit signed
26f80 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 integer.** value
26f90 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e given in the 2n
26fa0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a d argument..**.*
26fb0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
26fc0 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 sult_null() inte
26fd0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
26fe0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f eturn value.** o
26ff0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
27000 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
27010 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a on to be NULL..*
27020 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
27030 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 _result_text(),
27040 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
27050 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 ext16(),.** sqli
27060 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
27070 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 6le(), and sqlit
27080 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
27090 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a be() interfaces.
270a0 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 ** set the retur
270b0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 n value of the a
270c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
270d0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
270e0 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 e.** a text stri
270f0 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 ng which is repr
27100 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 esented as UTF-8
27110 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 , UTF-16 native
27120 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 byte order,.** U
27130 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 TF-16 little end
27140 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 ian, or UTF-16 b
27150 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 ig endian, respe
27160 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 ctively..** SQLi
27170 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 te takes the tex
27180 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 t result from th
27190 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 e application fr
271a0 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 om.** the 2nd pa
271b0 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 rameter of the s
271c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
271d0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a xt* interfaces..
271e0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 ** If the 3rd pa
271f0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
27200 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
27210 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a xt* interfaces.*
27220 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 * is negative, t
27230 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 hen SQLite takes
27240 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f result text fro
27250 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 m the 2nd parame
27260 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 ter.** through t
27270 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 he first zero ch
27280 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 aracter..** If t
27290 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 he 3rd parameter
272a0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
272b0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
272c0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f erfaces.** is no
272d0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e n-negative, then
272e0 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 as many bytes (
272f0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 not characters)
27300 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 of the text.** p
27310 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 ointed to by the
27320 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 2nd parameter a
27330 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 re taken as the
27340 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
27350 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ned.** function
27360 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 result..** If th
27370 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
27380 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
27390 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
273a0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c rfaces.** or sql
273b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
273c0 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 is a non-NULL p
273d0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c ointer, then SQL
273e0 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a ite calls that.*
273f0 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 * function as th
27400 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 e destructor on
27410 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 the text or BLOB
27420 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 result when it
27430 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 has.** finished
27440 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c using that resul
27450 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 t..** If the 4th
27460 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
27470 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
27480 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
27490 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f s or.** sqlite3_
274a0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 result_blob is t
274b0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 he special const
274c0 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 ant SQLITE_STATI
274d0 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a C, then SQLite.*
274e0 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 * assumes that t
274f0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 he text or BLOB
27500 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e result is in con
27510 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 stant space and
27520 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 does not.** copy
27530 20 74 68 65 20 69 74 20 6f 72 20 63 61 6c 6c 20 the it or call
27540 61 20 64 65 73 74 72 75 63 74 6f 72 20 77 68 65 a destructor whe
27550 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 n it has finishe
27560 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 d using that res
27570 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 ult..** If the 4
27580 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
27590 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
275a0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
275b0 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 ces.** or sqlite
275c0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 3_result_blob is
275d0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e the special con
275e0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 stant SQLITE_TRA
275f0 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 NSIENT.** then S
27600 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f QLite makes a co
27610 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 py of the result
27620 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 into space obta
27630 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f ined from.** fro
27640 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
27650 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 c()] before it r
27660 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 eturns..**.** Th
27670 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
27680 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 _value() interfa
27690 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 ce sets the resu
276a0 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 lt of.** the app
276b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
276c0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
276d0 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 a copy the.** [u
276e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
276f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
27700 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
27710 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e e 2nd parameter.
27720 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 The.** sqlite3
27730 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
27740 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 interface makes
27750 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 a copy of the [s
27760 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
27770 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 so that the [sq
27780 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 lite3_value] spe
27790 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 cified in the pa
277a0 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e rameter may chan
277b0 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c ge or.** be deal
277c0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 located after sq
277d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
277e0 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 ue() returns wit
277f0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 hout harm..** A
27800 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
27810 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
27820 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 may always be u
27830 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 sed where an.**
27840 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
27850 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
27860 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 ct is required,
27870 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e so either.** kin
27880 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 d of [sqlite3_va
27890 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 lue] object can
278a0 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 be used with thi
278b0 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a s interface..**.
278c0 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 ** If these rout
278d0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
278e0 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 from within the
278f0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
27900 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 .** than the one
27910 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
27920 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
27930 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 ned function tha
27940 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 t received.** th
27950 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 e [sqlite3_conte
27960 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 xt] pointer, the
27970 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
27980 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 efined..**.** Re
27990 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
279a0 48 31 36 34 30 33 5d 20 5b 48 31 36 34 30 36 5d H16403] [H16406]
279b0 20 5b 48 31 36 34 30 39 5d 20 5b 48 31 36 34 31 [H16409] [H1641
279c0 32 5d 20 5b 48 31 36 34 31 35 5d 20 5b 48 31 36 2] [H16415] [H16
279d0 34 31 38 5d 20 5b 48 31 36 34 32 31 5d 20 5b 48 418] [H16421] [H
279e0 31 36 34 32 34 5d 0a 2a 2a 20 5b 48 31 36 34 32 16424].** [H1642
279f0 37 5d 20 5b 48 31 36 34 33 30 5d 20 5b 48 31 36 7] [H16430] [H16
27a00 34 33 33 5d 20 5b 48 31 36 34 33 36 5d 20 5b 48 433] [H16436] [H
27a10 31 36 34 33 39 5d 20 5b 48 31 36 34 34 32 5d 20 16439] [H16442]
27a20 5b 48 31 36 34 34 35 5d 20 5b 48 31 36 34 34 38 [H16445] [H16448
27a30 5d 0a 2a 2a 20 5b 48 31 36 34 35 31 5d 20 5b 48 ].** [H16451] [H
27a40 31 36 34 35 34 5d 20 5b 48 31 36 34 35 37 5d 20 16454] [H16457]
27a50 5b 48 31 36 34 36 30 5d 20 5b 48 31 36 34 36 33 [H16460] [H16463
27a60 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ].*/.void sqlite
27a70 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 3_result_blob(sq
27a80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
27a90 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
27aa0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
27ab0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
27ac0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 result_double(sq
27ad0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
27ae0 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 double);.void sq
27af0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
27b00 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 or(sqlite3_conte
27b10 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a xt*, const char*
27b20 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c , int);.void sql
27b30 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
27b40 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 r16(sqlite3_cont
27b50 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ext*, const void
27b60 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 *, int);.void sq
27b70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
27b80 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 or_toobig(sqlite
27b90 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 3_context*);.voi
27ba0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
27bb0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c _error_nomem(sql
27bc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
27bd0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
27be0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 ult_error_code(s
27bf0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
27c00 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 int);.void sqli
27c10 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 te3_result_int(s
27c20 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
27c30 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 int);.void sqli
27c40 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 te3_result_int64
27c50 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
27c60 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
27c70 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
27c80 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 result_null(sqli
27c90 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 te3_context*);.v
27ca0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
27cb0 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f lt_text(sqlite3_
27cc0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
27cd0 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 char*, int, void
27ce0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
27cf0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
27d00 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f _text16(sqlite3_
27d10 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
27d20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 void*, int, void
27d30 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
27d40 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
27d50 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 _text16le(sqlite
27d60 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
27d70 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 t void*, int,voi
27d80 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f d(*)(void*));.vo
27d90 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
27da0 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 t_text16be(sqlit
27db0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
27dc0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f st void*, int,vo
27dd0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 id(*)(void*));.v
27de0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
27df0 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 lt_value(sqlite3
27e00 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 _context*, sqlit
27e10 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 e3_value*);.void
27e20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
27e30 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 zeroblob(sqlite3
27e40 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e _context*, int n
27e50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
27e60 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 EF: Define New C
27e70 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 ollating Sequenc
27e80 65 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 es {H16600} <S20
27e90 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 300>.**.** These
27ea0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 functions are u
27eb0 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 sed to add new c
27ec0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
27ed0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 es to the.** [da
27ee0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
27ef0 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 n] specified as
27f00 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
27f10 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 nt..**.** The na
27f20 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f me of the new co
27f30 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
27f40 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73 is specified as
27f50 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a a UTF-8 string.
27f60 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 ** for sqlite3_c
27f70 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 reate_collation(
27f80 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 ) and sqlite3_cr
27f90 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
27fa0 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2().** and a UTF
27fb0 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 -16 string for s
27fc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
27fd0 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 llation16(). In
27fe0 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 all cases.** the
27ff0 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 name is passed
28000 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 as the second fu
28010 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e nction argument.
28020 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 .**.** The third
28030 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 argument may be
28040 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 one of the cons
28050 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 tants [SQLITE_UT
28060 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f F8],.** [SQLITE_
28070 55 54 46 31 36 4c 45 5d 2c 20 6f 72 20 5b 53 51 UTF16LE], or [SQ
28080 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 LITE_UTF16BE], i
28090 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 ndicating that t
280a0 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 he user-supplied
280b0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 .** routine expe
280c0 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 cts to be passed
280d0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
280e0 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 ings encoded usi
280f0 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 ng UTF-8,.** UTF
28100 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 -16 little-endia
28110 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 n, or UTF-16 big
28120 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 -endian, respect
28130 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 ively. The.** th
28140 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 ird argument mig
28150 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 ht also be [SQLI
28160 54 45 5f 55 54 46 31 36 5d 20 74 6f 20 69 6e 64 TE_UTF16] to ind
28170 69 63 61 74 65 20 74 68 61 74 20 74 68 65 20 72 icate that the r
28180 6f 75 74 69 6e 65 0a 2a 2a 20 65 78 70 65 63 74 outine.** expect
28190 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 62 65 s pointers to be
281a0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 UTF-16 strings
281b0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
281c0 74 65 20 6f 72 64 65 72 2c 20 6f 72 20 74 68 65 te order, or the
281d0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 63 61 6e .** argument can
281e0 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 be [SQLITE_UTF1
281f0 36 5f 41 4c 49 47 4e 45 44 5d 20 69 66 20 74 68 6_ALIGNED] if th
28200 65 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 e.** the routine
28210 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 expects pointer
28220 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 s to 16-bit word
28230 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 aligned strings
28240 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e .** of UTF-16 in
28250 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
28260 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 order..**.** A
28270 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 pointer to the u
28280 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 ser supplied rou
28290 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 tine must be pas
282a0 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68 sed as the fifth
282b0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 .** argument. I
282c0 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 f it is NULL, th
282d0 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 is is the same a
282e0 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 s deleting the c
282f0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 ollation.** sequ
28300 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 ence (so that SQ
28310 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c Lite cannot call
28320 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a it anymore)..**
28330 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 Each time the a
28340 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c pplication suppl
28350 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ied function is
28360 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 invoked, it is p
28370 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 assed.** as its
28380 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
28390 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f a copy of the vo
283a0 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 id* passed as th
283b0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e e fourth argumen
283c0 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f t.** to sqlite3_
283d0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
283e0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 () or sqlite3_cr
283f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 eate_collation16
28400 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 ()..**.** The re
28410 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 maining argument
28420 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 s to the applica
28430 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f tion-supplied ro
28440 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 utine are two st
28450 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 rings,.** each r
28460 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 epresented by a
28470 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 (length, data) p
28480 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 air and encoded
28490 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a in the encoding.
284a0 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73 ** that was pass
284b0 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 ed as the third
284c0 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 argument when th
284d0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 e collation sequ
284e0 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 ence was.** regi
284f0 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54 stered. {END} T
28500 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
28510 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e efined collation
28520 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a routine should.
28530 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 ** return negati
28540 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 ve, zero or posi
28550 74 69 76 65 20 69 66 20 74 68 65 20 66 69 72 73 tive if the firs
28560 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 t string is less
28570 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 than,.** equal
28580 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 to, or greater t
28590 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73 han the second s
285a0 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 tring. i.e. (STR
285b0 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e ING1 - STRING2).
285c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
285d0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
285e0 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c ion_v2() works l
285f0 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 ike sqlite3_crea
28600 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a te_collation().*
28610 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 * except that it
28620 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 takes an extra
28630 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
28640 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 s a destructor f
28650 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 or.** the collat
28660 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75 ion. The destru
28670 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 ctor is called w
28680 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f hen the collatio
28690 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 n is.** destroye
286a0 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 d and is passed
286b0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f a copy of the fo
286c0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 urth parameter v
286d0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 oid* pointer.**
286e0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 of the sqlite3_c
286f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
28700 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 v2()..** Collati
28710 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 ons are destroye
28720 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 d when they are
28730 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 overridden by la
28740 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 ter calls to the
28750 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 .** collation cr
28760 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 eation functions
28770 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61 or when the [da
28780 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
28790 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 n] is closed.**
287a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 using [sqlite3_c
287b0 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 lose()]..**.** S
287c0 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 ee also: [sqlit
287d0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
287e0 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ded()] and [sqli
287f0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
28800 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a eded16()]..**.**
28810 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
28820 2a 20 5b 48 31 36 36 30 33 5d 20 5b 48 31 36 36 * [H16603] [H166
28830 30 34 5d 20 5b 48 31 36 36 30 36 5d 20 5b 48 31 04] [H16606] [H1
28840 36 36 30 39 5d 20 5b 48 31 36 36 31 32 5d 20 5b 6609] [H16612] [
28850 48 31 36 36 31 35 5d 20 5b 48 31 36 36 31 38 5d H16615] [H16618]
28860 20 5b 48 31 36 36 32 31 5d 0a 2a 2a 20 5b 48 31 [H16621].** [H1
28870 36 36 32 34 5d 20 5b 48 31 36 36 32 37 5d 20 5b 6624] [H16627] [
28880 48 31 36 36 33 30 5d 0a 2a 2f 0a 69 6e 74 20 73 H16630].*/.int s
28890 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
288a0 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 llation(. sqlit
288b0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 e3*, . const ch
288c0 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e ar *zName, . in
288d0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 t eTextRep, . v
288e0 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f oid*,. int(*xCo
288f0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 mpare)(void*,int
28900 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 ,const void*,int
28910 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b ,const void*).);
28920 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
28930 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
28940 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 (. sqlite3*, .
28950 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
28960 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 me, . int eText
28970 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 Rep, . void*,.
28980 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 int(*xCompare)(
28990 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
289a0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
289b0 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a void*),. void(*
289c0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 xDestroy)(void*)
289d0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
289e0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
289f0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 16(. sqlite3*,
28a00 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a . const void *z
28a10 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 Name,. int eTex
28a20 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a tRep, . void*,.
28a30 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 int(*xCompare)
28a40 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
28a50 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 void*,int,const
28a60 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a void*).);../*.*
28a70 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c * CAPI3REF: Coll
28a80 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c ation Needed Cal
28a90 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 lbacks {H16700}
28aa0 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S20300>.**.** T
28ab0 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 o avoid having t
28ac0 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 o register all c
28ad0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
28ae0 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 es before a data
28af0 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 base.** can be u
28b00 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 sed, a single ca
28b10 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
28b20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 may be registere
28b30 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 d with the.** [d
28b40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
28b50 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 on] to be called
28b60 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 whenever an und
28b70 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e efined collation
28b80 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 .** sequence is
28b90 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
28ba0 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 If the function
28bb0 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 is registered us
28bc0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
28bd0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
28be0 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 () API,.** then
28bf0 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 it is passed the
28c00 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 names of undefi
28c10 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 ned collation se
28c20 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e quences as strin
28c30 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e gs.** encoded in
28c40 20 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d UTF-8. {H16703}
28c50 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c If sqlite3_coll
28c60 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 ation_needed16()
28c70 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 is used,.** the
28c80 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 names are passe
28c90 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d d as UTF-16 in m
28ca0 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 achine native by
28cb0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 te order..** A c
28cc0 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 all to either fu
28cd0 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 nction replaces
28ce0 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c any existing cal
28cf0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 lback..**.** Whe
28d00 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 n the callback i
28d10 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 s invoked, the f
28d20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 irst argument pa
28d30 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a ssed is a copy.*
28d40 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 * of the second
28d50 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
28d60 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
28d70 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c eded() or.** sql
28d80 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
28d90 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 eeded16(). The
28da0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
28db0 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a is the database.
28dc0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 ** connection.
28dd0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
28de0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 nt is one of [SQ
28df0 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c LITE_UTF8], [SQL
28e00 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a ITE_UTF16BE],.**
28e10 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 or [SQLITE_UTF1
28e20 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 6LE], indicating
28e30 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 the most desira
28e40 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 ble form of the
28e50 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 collation.** seq
28e60 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 uence function r
28e70 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f equired. The fo
28e80 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
28e90 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
28ea0 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f e.** required co
28eb0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
28ec0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c ..**.** The call
28ed0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 back function sh
28ee0 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 ould register th
28ef0 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 e desired collat
28f00 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ion using.** [sq
28f10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
28f20 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 lation()], [sqli
28f30 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
28f40 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a tion16()], or.**
28f50 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
28f60 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d _collation_v2()]
28f70 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
28f80 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 37 30 32 ents:.** [H16702
28f90 5d 20 5b 48 31 36 37 30 34 5d 20 5b 48 31 36 37 ] [H16704] [H167
28fa0 30 36 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 06].*/.int sqlit
28fb0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
28fc0 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c ded(. sqlite3*,
28fd0 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f . void*, . vo
28fe0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 id(*)(void*,sqli
28ff0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 te3*,int eTextRe
29000 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 p,const char*).)
29010 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f ;.int sqlite3_co
29020 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 llation_needed16
29030 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 (. sqlite3*, .
29040 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a void*,. void(*
29050 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a )(void*,sqlite3*
29060 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f ,int eTextRep,co
29070 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f nst void*).);../
29080 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 *.** Specify the
29090 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 key for an encr
290a0 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 ypted database.
290b0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 This routine sh
290c0 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 ould be.** calle
290d0 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 d right after sq
290e0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a lite3_open()..**
290f0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 .** The code to
29100 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 implement this A
29110 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 PI is not availa
29120 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 ble in the publi
29130 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 c release.** of
29140 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 SQLite..*/.int s
29150 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 qlite3_key(. sq
29160 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
29170 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
29180 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 Database to be r
29190 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 ekeyed */. cons
291a0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e t void *pKey, in
291b0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 t nKey /* Th
291c0 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a e key */.);../*.
291d0 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 ** Change the ke
291e0 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 y on an open dat
291f0 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 abase. If the c
29200 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 urrent database
29210 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 is not.** encryp
29220 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e ted, this routin
29230 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 e will encrypt i
29240 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f t. If pNew==0 o
29250 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a r nNew==0, the.*
29260 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 * database is de
29270 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 crypted..**.** T
29280 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 he code to imple
29290 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 ment this API is
292a0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 not available i
292b0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c n the public rel
292c0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 ease.** of SQLit
292d0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 e..*/.int sqlite
292e0 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 3_rekey(. sqlit
292f0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
29300 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
29310 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 abase to be reke
29320 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 yed */. const v
29330 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e oid *pKey, int n
29340 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e Key /* The n
29350 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a ew key */.);../*
29360 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 .** CAPI3REF: Su
29370 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 spend Execution
29380 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 For A Short Time
29390 20 7b 48 31 30 35 33 30 7d 20 3c 53 34 30 34 31 {H10530} <S4041
293a0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0>.**.** The sql
293b0 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e ite3_sleep() fun
293c0 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 ction causes the
293d0 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 current thread
293e0 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 to suspend execu
293f0 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c tion.** for at l
29400 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 east a number of
29410 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 milliseconds sp
29420 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 ecified in its p
29430 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
29440 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 If the operating
29450 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 system does not
29460 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 support sleep r
29470 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 equests with.**
29480 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 millisecond time
29490 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 resolution, the
294a0 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 n the time will
294b0 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f be rounded up to
294c0 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 .** the nearest
294d0 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 second. The numb
294e0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e er of millisecon
294f0 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 ds of sleep actu
29500 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 ally.** requeste
29510 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 d from the opera
29520 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 ting system is r
29530 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 eturned..**.** S
29540 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 QLite implements
29550 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
29560 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 by calling the x
29570 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f Sleep().** metho
29580 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 d of the default
29590 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
295a0 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 bject..**.** Req
295b0 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35 uirements: [H105
295c0 33 33 5d 20 5b 48 31 30 35 33 36 5d 0a 2a 2f 0a 33] [H10536].*/.
295d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 int sqlite3_slee
295e0 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 p(int);../*.** C
295f0 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 API3REF: Name Of
29600 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 The Folder Hold
29610 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 ing Temporary Fi
29620 6c 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 les {H10310} <S2
29630 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 0000>.**.** If t
29640 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 his global varia
29650 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 ble is made to p
29660 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 oint to a string
29670 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 which is.** the
29680 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 name of a folde
29690 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 r (a.k.a. direct
296a0 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 ory), then all t
296b0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a emporary files.*
296c0 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c * created by SQL
296d0 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 ite will be plac
296e0 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 ed in that direc
296f0 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 tory. If this v
29700 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 ariable.** is a
29710 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 NULL pointer, th
29720 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 en SQLite perfor
29730 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 ms a search for
29740 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a an appropriate.*
29750 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 * temporary file
29760 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a directory..**.*
29770 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 * It is not safe
29780 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 to read or modi
29790 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 fy this variable
297a0 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e in more than on
297b0 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 e.** thread at a
297c0 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f time. It is no
297d0 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f t safe to read o
297e0 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 r modify this va
297f0 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b riable.** if a [
29800 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
29810 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 ion] is being us
29820 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 ed at the same t
29830 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 ime in a separat
29840 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 e.** thread..**
29850 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 It is intended t
29860 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c hat this variabl
29870 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a e be set once.**
29880 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 as part of proc
29890 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 ess initializati
298a0 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e on and before an
298b0 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 y SQLite interfa
298c0 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 ce.** routines h
298d0 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 ave been called
298e0 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61 and that this va
298f0 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e riable remain un
29900 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 changed.** there
29910 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 after..**.** The
29920 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 [temp_store_dir
29930 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d ectory pragma] m
29940 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 ay modify this v
29950 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 ariable and caus
29960 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 e.** it to point
29970 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 to memory obtai
29980 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
29990 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 46 75 72 74 3_malloc]. Furt
299a0 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 hermore,.** the
299b0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
299c0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c ctory pragma] al
299d0 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 ways assumes tha
299e0 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 t any string.**
299f0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 that this variab
29a00 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 le points to is
29a10 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f held in memory o
29a20 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a btained from .**
29a30 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
29a40 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 ] and the pragma
29a50 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 may attempt to
29a60 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 free that memory
29a70 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 .** using [sqlit
29a80 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e e3_free]..** Hen
29a90 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 ce, if this vari
29aa0 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 able is modified
29ab0 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 directly, eithe
29ac0 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a r it should be.*
29ad0 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d * made NULL or m
29ae0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 ade to point to
29af0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
29b00 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
29b10 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 lloc].** or else
29b20 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 the use of the
29b30 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
29b40 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 ctory pragma] sh
29b50 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e ould be avoided.
29b60 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 .*/.SQLITE_EXTER
29b70 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f N char *sqlite3_
29b80 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a temp_directory;.
29b90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
29ba0 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 Test For Auto-C
29bb0 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 48 31 32 39 ommit Mode {H129
29bc0 33 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 30} <S60200>.**
29bd0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 KEYWORDS: {autoc
29be0 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a ommit mode}.**.*
29bf0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 * The sqlite3_ge
29c00 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 t_autocommit() i
29c10 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
29c20 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 non-zero or.**
29c30 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 zero if the give
29c40 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 n database conne
29c50 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e ction is or is n
29c60 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 ot in autocommit
29c70 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 mode,.** respec
29c80 74 69 76 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d tively. Autocom
29c90 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 mit mode is on b
29ca0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 y default..** Au
29cb0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 tocommit mode is
29cc0 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b disabled by a [
29cd0 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 BEGIN] statement
29ce0 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 ..** Autocommit
29cf0 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c mode is re-enabl
29d00 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d ed by a [COMMIT]
29d10 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a or [ROLLBACK]..
29d20 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e **.** If certain
29d30 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 kinds of errors
29d40 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 occur on a stat
29d50 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d ement within a m
29d60 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a ulti-statement.*
29d70 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 * transaction (e
29d80 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 rrors including
29d90 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b [SQLITE_FULL], [
29da0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a SQLITE_IOERR],.*
29db0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d * [SQLITE_NOMEM]
29dc0 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c , [SQLITE_BUSY],
29dd0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 and [SQLITE_INT
29de0 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 ERRUPT]) then th
29df0 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e e.** transaction
29e00 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 might be rolled
29e10 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 back automatica
29e20 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 lly. The only w
29e30 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 ay to.** find ou
29e40 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 t whether SQLite
29e50 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 automatically r
29e60 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 olled back the t
29e70 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 ransaction after
29e80 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 .** an error is
29e90 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 to use this func
29ea0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 tion..**.** If a
29eb0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68 nother thread ch
29ec0 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f anges the autoco
29ed0 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 mmit status of t
29ee0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 he database.** c
29ef0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 onnection while
29f00 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 this routine is
29f10 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 running, then th
29f20 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a e return value.*
29f30 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a * is undefined..
29f40 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
29f50 74 73 3a 20 5b 48 31 32 39 33 31 5d 20 5b 48 31 ts: [H12931] [H1
29f60 32 39 33 32 5d 20 5b 48 31 32 39 33 33 5d 20 5b 2932] [H12933] [
29f70 48 31 32 39 33 34 5d 0a 2a 2f 0a 69 6e 74 20 73 H12934].*/.int s
29f80 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 qlite3_get_autoc
29f90 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b ommit(sqlite3*);
29fa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
29fb0 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 : Find The Datab
29fc0 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 ase Handle Of A
29fd0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
29fe0 6e 74 20 7b 48 31 33 31 32 30 7d 20 3c 53 36 30 nt {H13120} <S60
29ff0 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 600>.**.** The s
2a000 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 qlite3_db_handle
2a010 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2a020 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 ns the [database
2a030 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e connection] han
2a040 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 dle.** to which
2a050 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
2a060 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 ement] belongs.
2a070 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 The [database c
2a080 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 onnection].** re
2a090 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
2a0a0 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 3_db_handle is t
2a0b0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 he same [databas
2a0c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 e connection] th
2a0d0 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74 at was the first
2a0e0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
2a0f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 the [sqlite3_pre
2a100 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 pare_v2()] call
2a110 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 (or its variants
2a120 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 ) that was used
2a130 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 to.** create the
2a140 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 statement in th
2a150 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a e first place..*
2a160 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
2a170 73 3a 20 5b 48 31 33 31 32 33 5d 0a 2a 2f 0a 73 s: [H13123].*/.s
2a180 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f qlite3 *sqlite3_
2a190 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 db_handle(sqlite
2a1a0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
2a1b0 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 CAPI3REF: Find
2a1c0 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 the next prepare
2a1d0 64 20 73 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 d statement {H13
2a1e0 31 34 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 140} <S60600>.**
2a1f0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
2a200 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
2a210 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 nter to the next
2a220 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2a230 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 ment] after.** p
2a240 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 Stmt associated
2a250 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 with the [databa
2a260 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 se connection] p
2a270 44 62 2e 20 20 49 66 20 70 53 74 6d 74 20 69 73 Db. If pStmt is
2a280 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 NULL.** then th
2a290 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 is interface ret
2a2a0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
2a2b0 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 o the first prep
2a2c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a ared statement.*
2a2d0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
2a2e0 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 h the database c
2a2f0 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 onnection pDb.
2a300 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 If no prepared s
2a310 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 tatement.** sati
2a320 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 sfies the condit
2a330 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 ions of this rou
2a340 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 tine, it returns
2a350 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 NULL..**.** The
2a360 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2a370 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 ction] pointer D
2a380 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a in a call to.**
2a390 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 [sqlite3_next_s
2a3a0 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 tmt(D,S)] must r
2a3b0 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 efer to an open
2a3c0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
2a3d0 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 ection and in pa
2a3e0 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f rticular must no
2a3f0 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e t be a NULL poin
2a400 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ter..**.** Requi
2a410 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31 34 33 rements: [H13143
2a420 5d 20 5b 48 31 33 31 34 36 5d 20 5b 48 31 33 31 ] [H13146] [H131
2a430 34 39 5d 20 5b 48 31 33 31 35 32 5d 0a 2a 2f 0a 49] [H13152].*/.
2a440 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 sqlite3_stmt *sq
2a450 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 lite3_next_stmt(
2a460 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 sqlite3 *pDb, sq
2a470 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
2a480 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2a490 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 REF: Commit And
2a4a0 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 Rollback Notific
2a4b0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 ation Callbacks
2a4c0 7b 48 31 32 39 35 30 7d 20 3c 53 36 30 34 30 30 {H12950} <S60400
2a4d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
2a4e0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 te3_commit_hook(
2a4f0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ) interface regi
2a500 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b sters a callback
2a510 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 .** function to
2a520 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 be invoked whene
2a530 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f ver a transactio
2a540 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 n is [COMMIT | c
2a550 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 41 6e ommitted]..** An
2a560 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 y callback set b
2a570 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c y a previous cal
2a580 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d l to sqlite3_com
2a590 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f mit_hook().** fo
2a5a0 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 r the same datab
2a5b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
2a5c0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a s overridden..**
2a5d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c The sqlite3_rol
2a5e0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 lback_hook() int
2a5f0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 erface registers
2a600 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 a callback.** f
2a610 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e unction to be in
2a620 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 voked whenever a
2a630 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
2a640 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c [ROLLBACK | roll
2a650 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 41 6e 79 ed back]..** Any
2a660 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 callback set by
2a670 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c a previous call
2a680 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d to sqlite3_comm
2a690 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 it_hook().** for
2a6a0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
2a6b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
2a6c0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 overridden..**
2a6d0 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e The pArg argumen
2a6e0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f t is passed thro
2a6f0 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 ugh to the callb
2a700 61 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 ack..** If the c
2a710 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d allback on a com
2a720 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f mit hook functio
2a730 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 n returns non-ze
2a740 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 ro,.** then the
2a750 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 commit is conver
2a760 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 ted into a rollb
2a770 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e ack..**.** If an
2a780 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 other function w
2a790 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 as previously re
2a7a0 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a gistered, its.**
2a7b0 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 pArg value is r
2a7c0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 eturned. Otherw
2a7d0 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 ise NULL is retu
2a7e0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rned..**.** The
2a7f0 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 callback impleme
2a800 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ntation must not
2a810 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 do anything tha
2a820 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a t will modify.**
2a830 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
2a840 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e nnection that in
2a850 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 voked the callba
2a860 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 ck. Any actions
2a870 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 .** to modify th
2a880 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
2a890 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 ction must be de
2a8a0 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 ferred until aft
2a8b0 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 er the.** comple
2a8c0 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c tion of the [sql
2a8d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c ite3_step()] cal
2a8e0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 l that triggered
2a8f0 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f the commit.** o
2a900 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 r rollback hook
2a910 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 in the first pla
2a920 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 ce..** Note that
2a930 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2a940 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c e_v2()] and [sql
2a950 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 ite3_step()] bot
2a960 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a h modify their.*
2a970 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
2a980 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d ctions for the m
2a990 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 eaning of "modif
2a9a0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 y" in this parag
2a9b0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 raph..**.** Regi
2a9c0 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 stering a NULL f
2a9d0 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 unction disables
2a9e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a the callback..*
2a9f0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 6f *.** When the co
2aa00 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 mmit hook callba
2aa10 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ck routine retur
2aa20 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f ns zero, the [CO
2aa30 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 MMIT].** operati
2aa40 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f on is allowed to
2aa50 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c continue normal
2aa60 6c 79 2e 20 20 49 66 20 74 68 65 20 63 6f 6d 6d ly. If the comm
2aa70 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 it hook.** retur
2aa80 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 ns non-zero, the
2aa90 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 n the [COMMIT] i
2aaa0 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f s converted into
2aab0 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a a [ROLLBACK]..*
2aac0 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 * The rollback h
2aad0 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f ook is invoked o
2aae0 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 n a rollback tha
2aaf0 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 t results from a
2ab00 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 commit.** hook
2ab10 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 returning non-ze
2ab20 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 ro, just as it w
2ab30 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 ould be with any
2ab40 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e other rollback.
2ab50 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 .**.** For the p
2ab60 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 urposes of this
2ab70 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 API, a transacti
2ab80 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 on is said to ha
2ab90 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 ve been.** rolle
2aba0 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 d back if an exp
2abb0 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 licit "ROLLBACK"
2abc0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 statement is ex
2abd0 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e ecuted, or.** an
2abe0 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 error or constr
2abf0 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 aint causes an i
2ac00 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b mplicit rollback
2ac10 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 to occur..** Th
2ac20 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 e rollback callb
2ac30 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b ack is not invok
2ac40 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 ed if a transact
2ac50 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 ion is.** automa
2ac60 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 tically rolled b
2ac70 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 ack because the
2ac80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2ac90 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a ion is closed..*
2aca0 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 * The rollback c
2acb0 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 allback is not i
2acc0 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e nvoked if a tran
2acd0 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f saction is.** ro
2ace0 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 lled back becaus
2acf0 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 e a commit callb
2ad00 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e ack returned non
2ad10 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e -zero..** <todo>
2ad20 20 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c Check on this <
2ad30 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 53 65 65 /todo>.**.** See
2ad40 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 also the [sqlit
2ad50 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 e3_update_hook()
2ad60 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a ] interface..**.
2ad70 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
2ad80 0a 2a 2a 20 5b 48 31 32 39 35 31 5d 20 5b 48 31 .** [H12951] [H1
2ad90 32 39 35 32 5d 20 5b 48 31 32 39 35 33 5d 20 5b 2952] [H12953] [
2ada0 48 31 32 39 35 34 5d 20 5b 48 31 32 39 35 35 5d H12954] [H12955]
2adb0 0a 2a 2a 20 5b 48 31 32 39 36 31 5d 20 5b 48 31 .** [H12961] [H1
2adc0 32 39 36 32 5d 20 5b 48 31 32 39 36 33 5d 20 5b 2962] [H12963] [
2add0 48 31 32 39 36 34 5d 0a 2a 2f 0a 76 6f 69 64 20 H12964].*/.void
2ade0 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f *sqlite3_commit_
2adf0 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 hook(sqlite3*, i
2ae00 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f nt(*)(void*), vo
2ae10 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 id*);.void *sqli
2ae20 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f te3_rollback_hoo
2ae30 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 k(sqlite3*, void
2ae40 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 (*)(void *), voi
2ae50 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
2ae60 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 3REF: Data Chang
2ae70 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 e Notification C
2ae80 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 37 30 allbacks {H12970
2ae90 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a } <S60400>.**.**
2aea0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 The sqlite3_upd
2aeb0 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 ate_hook() inter
2aec0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 face registers a
2aed0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
2aee0 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b on.** with the [
2aef0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2af00 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 ion] identified
2af10 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 by the first arg
2af20 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 ument.** to be i
2af30 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 nvoked whenever
2af40 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 a row is updated
2af50 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 , inserted or de
2af60 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 leted..** Any ca
2af70 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 llback set by a
2af80 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f previous call to
2af90 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a this function.*
2afa0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 * for the same d
2afb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2afc0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e on is overridden
2afd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f ..**.** The seco
2afe0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 nd argument is a
2aff0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
2b000 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f function to invo
2b010 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 ke when a.** row
2b020 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 is updated, ins
2b030 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 erted or deleted
2b040 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ..** The first a
2b050 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 rgument to the c
2b060 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 allback is a cop
2b070 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 y of the third a
2b080 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 rgument.** to sq
2b090 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f lite3_update_hoo
2b0a0 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f k()..** The seco
2b0b0 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 nd callback argu
2b0c0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b ment is one of [
2b0d0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 SQLITE_INSERT],
2b0e0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c [SQLITE_DELETE],
2b0f0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 .** or [SQLITE_U
2b100 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e PDATE], dependin
2b110 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 g on the operati
2b120 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 on that caused t
2b130 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 he callback.** t
2b140 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a o be invoked..**
2b150 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 The third and f
2b160 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 ourth arguments
2b170 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
2b180 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 contain pointers
2b190 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 to the.** datab
2b1a0 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 ase and table na
2b1b0 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 me containing th
2b1c0 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a e affected row..
2b1d0 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c ** The final cal
2b1e0 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 lback parameter
2b1f0 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f is the [rowid] o
2b200 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 49 6e f the row..** In
2b210 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 the case of an
2b220 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 update, this is
2b230 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 the [rowid] afte
2b240 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b r the update tak
2b250 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 es place..**.**
2b260 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 The update hook
2b270 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 is not invoked w
2b280 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 hen internal sys
2b290 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a tem tables are.*
2b2a0 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e * modified (i.e.
2b2b0 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 sqlite_master a
2b2c0 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e nd sqlite_sequen
2b2d0 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 ce)..**.** In th
2b2e0 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d e current implem
2b2f0 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70 entation, the up
2b300 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 date hook.** is
2b310 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e not invoked when
2b320 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77 duplication row
2b330 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65 s are deleted be
2b340 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b cause of an.** [
2b350 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e ON CONFLICT | ON
2b360 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43 CONFLICT REPLAC
2b370 45 5d 20 63 6c 61 75 73 65 2e 20 20 4e 6f 72 20 E] clause. Nor
2b380 69 73 20 74 68 65 20 75 70 64 61 74 65 20 68 6f is the update ho
2b390 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 ok.** invoked wh
2b3a0 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 en rows are dele
2b3b0 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 74 ted using the [t
2b3c0 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 runcate optimiza
2b3d0 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 tion]..** The ex
2b3e0 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 64 ceptions defined
2b3f0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 in this paragra
2b400 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 ph might change
2b410 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 in a future.** r
2b420 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 elease of SQLite
2b430 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 ..**.** The upda
2b440 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e te hook implemen
2b450 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 tation must not
2b460 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 do anything that
2b470 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 will modify.**
2b480 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
2b490 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 nection that inv
2b4a0 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65 20 oked the update
2b4b0 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f hook. Any actio
2b4c0 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 ns.** to modify
2b4d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
2b4e0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 nection must be
2b4f0 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 deferred until a
2b500 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 fter the.** comp
2b510 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 letion of the [s
2b520 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 qlite3_step()] c
2b530 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
2b540 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f ed the update ho
2b550 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 ok..** Note that
2b560 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2b570 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c e_v2()] and [sql
2b580 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 ite3_step()] bot
2b590 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a h modify their.*
2b5a0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
2b5b0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d ctions for the m
2b5c0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 eaning of "modif
2b5d0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 y" in this parag
2b5e0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 raph..**.** If a
2b5f0 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 nother function
2b600 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 was previously r
2b610 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 egistered, its p
2b620 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 Arg value.** is
2b630 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 returned. Other
2b640 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 wise NULL is ret
2b650 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 urned..**.** See
2b660 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 also the [sqlit
2b670 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 e3_commit_hook()
2b680 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 ] and [sqlite3_r
2b690 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a ollback_hook()].
2b6a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a ** interfaces..*
2b6b0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
2b6c0 73 3a 0a 2a 2a 20 5b 48 31 32 39 37 31 5d 20 5b s:.** [H12971] [
2b6d0 48 31 32 39 37 33 5d 20 5b 48 31 32 39 37 35 5d H12973] [H12975]
2b6e0 20 5b 48 31 32 39 37 37 5d 20 5b 48 31 32 39 37 [H12977] [H1297
2b6f0 39 5d 20 5b 48 31 32 39 38 31 5d 20 5b 48 31 32 9] [H12981] [H12
2b700 39 38 33 5d 20 5b 48 31 32 39 38 36 5d 0a 2a 2f 983] [H12986].*/
2b710 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 .void *sqlite3_u
2b720 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 pdate_hook(. sq
2b730 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 lite3*, . void(
2b740 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 *)(void *,int ,c
2b750 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 har const *,char
2b760 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 const *,sqlite3
2b770 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a _int64),. void*
2b780 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
2b790 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 REF: Enable Or D
2b7a0 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 isable Shared Pa
2b7b0 67 65 72 20 43 61 63 68 65 20 7b 48 31 30 33 33 ger Cache {H1033
2b7c0 30 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b 0} <S30900>.** K
2b7d0 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 EYWORDS: {shared
2b7e0 20 63 61 63 68 65 7d 20 7b 73 68 61 72 65 64 20 cache} {shared
2b7f0 63 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a cache mode}.**.*
2b800 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 * This routine e
2b810 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c nables or disabl
2b820 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f es the sharing o
2b830 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 f the database c
2b840 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 ache.** and sche
2b850 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 ma data structur
2b860 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 es between [data
2b870 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2b880 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a | connections].*
2b890 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 * to the same da
2b8a0 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 tabase. Sharing
2b8b0 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 is enabled if th
2b8c0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 e argument is tr
2b8d0 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c ue.** and disabl
2b8e0 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 ed if the argume
2b8f0 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a nt is false..**.
2b900 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 ** Cache sharing
2b910 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 is enabled and
2b920 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 disabled for an
2b930 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a entire process..
2b940 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61 ** This is a cha
2b950 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 nge as of SQLite
2b960 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 version 3.5.0.
2b970 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e In prior version
2b980 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 s of SQLite,.**
2b990 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62 sharing was enab
2b9a0 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 led or disabled
2b9b0 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 for each thread
2b9c0 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a separately..**.*
2b9d0 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72 * The cache shar
2b9e0 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 ing mode set by
2b9f0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 this interface e
2ba00 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 ffects all subse
2ba10 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 quent.** calls t
2ba20 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 o [sqlite3_open(
2ba30 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
2ba40 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 n_v2()], and [sq
2ba50 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e lite3_open16()].
2ba60 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 .** Existing dat
2ba70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2ba80 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 s continue use t
2ba90 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a he sharing mode.
2baa0 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65 ** that was in e
2bab0 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d ffect at the tim
2bac0 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e e they were open
2bad0 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 ed..**.** Virtua
2bae0 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 l tables cannot
2baf0 62 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73 be used with a s
2bb00 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 57 68 hared cache. Wh
2bb10 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 en shared.** cac
2bb20 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 he is enabled, t
2bb30 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
2bb40 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49 te_module()] API
2bb50 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 used to registe
2bb60 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 r.** virtual tab
2bb70 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 les will always
2bb80 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e return an error.
2bb90 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
2bba0 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ine returns [SQL
2bbb0 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 ITE_OK] if share
2bbc0 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 d cache was enab
2bbd0 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a led or disabled.
2bbe0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e ** successfully.
2bbf0 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 An [error code
2bc00 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 ] is returned ot
2bc10 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 herwise..**.** S
2bc20 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 hared cache is d
2bc30 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
2bc40 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 lt. But this mig
2bc50 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 ht change in.**
2bc60 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
2bc70 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c of SQLite. Appl
2bc80 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 ications that ca
2bc90 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a re about shared.
2bca0 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 ** cache setting
2bcb0 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 should set it e
2bcc0 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a xplicitly..**.**
2bcd0 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c See Also: [SQL
2bce0 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 ite Shared-Cache
2bcf0 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a 20 52 65 71 Mode].**.** Req
2bd00 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 33 uirements: [H103
2bd10 33 31 5d 20 5b 48 31 30 33 33 36 5d 20 5b 48 31 31] [H10336] [H1
2bd20 30 33 33 37 5d 20 5b 48 31 30 33 33 39 5d 0a 2a 0337] [H10339].*
2bd30 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e /.int sqlite3_en
2bd40 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 able_shared_cach
2bd50 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 e(int);../*.** C
2bd60 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 API3REF: Attempt
2bd70 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 To Free Heap Me
2bd80 6d 6f 72 79 20 7b 48 31 37 33 34 30 7d 20 3c 53 mory {H17340} <S
2bd90 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 30220>.**.** The
2bda0 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 sqlite3_release
2bdb0 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 _memory() interf
2bdc0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ace attempts to
2bdd0 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 free N bytes.**
2bde0 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 of heap memory b
2bdf0 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e y deallocating n
2be00 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d on-essential mem
2be10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a ory allocations.
2be20 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 ** held by the d
2be30 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e atabase library.
2be40 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 {END} Memory u
2be50 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 sed to cache dat
2be60 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 abase.** pages t
2be70 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 o improve perfor
2be80 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d mance is an exam
2be90 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e ple of non-essen
2bea0 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 tial memory..**
2beb0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f sqlite3_release_
2bec0 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 memory() returns
2bed0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
2bee0 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 ytes actually fr
2bef0 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 eed,.** which mi
2bf00 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c ght be more or l
2bf10 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f ess than the amo
2bf20 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a unt requested..*
2bf30 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
2bf40 73 3a 20 5b 48 31 37 33 34 31 5d 20 5b 48 31 37 s: [H17341] [H17
2bf50 33 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 342].*/.int sqli
2bf60 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f te3_release_memo
2bf70 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ry(int);../*.**
2bf80 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 CAPI3REF: Impose
2bf90 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 A Limit On Heap
2bfa0 20 53 69 7a 65 20 7b 48 31 37 33 35 30 7d 20 3c Size {H17350} <
2bfb0 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S30220>.**.** Th
2bfc0 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 e sqlite3_soft_h
2bfd0 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 eap_limit() inte
2bfe0 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 22 rface places a "
2bff0 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f soft" limit.** o
2c000 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 n the amount of
2c010 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 heap memory that
2c020 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 may be allocate
2c030 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 d by SQLite..**
2c040 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 If an internal a
2c050 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71 llocation is req
2c060 75 65 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c uested that woul
2c070 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 d exceed the.**
2c080 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c soft heap limit,
2c090 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 [sqlite3_releas
2c0a0 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 e_memory()] is i
2c0b0 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a nvoked one or.**
2c0c0 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66 more times to f
2c0d0 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63 ree up some spac
2c0e0 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c e before the all
2c0f0 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f ocation is perfo
2c100 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rmed..**.** The
2c110 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 limit is called
2c120 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20 "soft", because
2c130 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 if [sqlite3_rele
2c140 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a ase_memory()].**
2c150 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 cannot free suf
2c160 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 ficient memory t
2c170 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 o prevent the li
2c180 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 mit from being e
2c190 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 xceeded,.** the
2c1a0 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 memory is alloca
2c1b0 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 ted anyway and t
2c1c0 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 he current opera
2c1d0 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a tion proceeds..*
2c1e0 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 *.** A negative
2c1f0 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f or zero value fo
2c200 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 r N means that t
2c210 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 here is no soft
2c220 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a heap limit and.*
2c230 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 * [sqlite3_relea
2c240 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c se_memory()] wil
2c250 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 l only be called
2c260 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 when memory is
2c270 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 exhausted..** Th
2c280 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 e default value
2c290 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 for the soft hea
2c2a0 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e p limit is zero.
2c2b0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 .**.** SQLite ma
2c2c0 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 kes a best effor
2c2d0 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 t to honor the s
2c2e0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a oft heap limit..
2c2f0 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f ** But if the so
2c300 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 ft heap limit ca
2c310 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c nnot be honored,
2c320 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a execution will.
2c330 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 ** continue with
2c340 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 out error or not
2c350 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 ification. This
2c360 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69 is why the limi
2c370 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 t is.** called a
2c380 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 "soft" limit.
2c390 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f It is advisory o
2c3a0 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 nly..**.** Prior
2c3b0 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 to SQLite versi
2c3c0 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 on 3.5.0, this r
2c3d0 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 outine only cons
2c3e0 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f trained the memo
2c3f0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 ry.** allocated
2c400 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 by a single thre
2c410 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68 ad - the same th
2c420 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68 read in which th
2c430 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 is routine.** ru
2c440 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 ns. Beginning w
2c450 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 ith SQLite versi
2c460 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f on 3.5.0, the so
2c470 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 ft heap limit is
2c480 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61 .** applied to a
2c490 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20 ll threads. The
2c4a0 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 value specified
2c4b0 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 for the soft hea
2c4c0 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e p limit.** is an
2c4d0 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 upper bound on
2c4e0 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 the total memory
2c4f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 allocation for
2c500 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a all threads. In.
2c510 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 ** version 3.5.0
2c520 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 there is no mec
2c530 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 hanism for limit
2c540 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61 ing the heap usa
2c550 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 ge for.** indivi
2c560 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a dual threads..**
2c570 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
2c580 3a 0a 2a 2a 20 5b 48 31 36 33 35 31 5d 20 5b 48 :.** [H16351] [H
2c590 31 36 33 35 32 5d 20 5b 48 31 36 33 35 33 5d 20 16352] [H16353]
2c5a0 5b 48 31 36 33 35 34 5d 20 5b 48 31 36 33 35 35 [H16354] [H16355
2c5b0 5d 20 5b 48 31 36 33 35 38 5d 0a 2a 2f 0a 76 6f ] [H16358].*/.vo
2c5c0 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f id sqlite3_soft_
2c5d0 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b heap_limit(int);
2c5e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2c5f0 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 : Extract Metada
2c600 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d ta About A Colum
2c610 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 7b 48 31 n Of A Table {H1
2c620 32 38 35 30 7d 20 3c 53 36 30 33 30 30 3e 0a 2a 2850} <S60300>.*
2c630 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
2c640 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 e returns metada
2c650 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 ta about a speci
2c660 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 fic column of a
2c670 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 specific.** data
2c680 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 base table acces
2c690 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 sible using the
2c6a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2c6b0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 tion] handle.**
2c6c0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 passed as the fi
2c6d0 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 rst function arg
2c6e0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ument..**.** The
2c6f0 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 column is ident
2c700 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 ified by the sec
2c710 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 ond, third and f
2c720 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 ourth parameters
2c730 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 to.** this func
2c740 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 tion. The second
2c750 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 parameter is ei
2c760 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 ther the name of
2c770 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
2c780 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 (i.e. "main", "
2c790 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61 temp" or an atta
2c7a0 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63 ched database) c
2c7b0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 ontaining the sp
2c7c0 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 ecified.** table
2c7d0 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 or NULL. If it
2c7e0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c is NULL, then al
2c7f0 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 l attached datab
2c800 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65 ases are searche
2c810 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 d.** for the tab
2c820 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d le using the sam
2c830 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 e algorithm used
2c840 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 by the database
2c850 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 engine to.** re
2c860 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 solve unqualifie
2c870 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 d table referenc
2c880 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 es..**.** The th
2c890 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 ird and fourth p
2c8a0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 arameters to thi
2c8b0 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 s function are t
2c8c0 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c he table and col
2c8d0 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 umn.** name of t
2c8e0 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d he desired colum
2c8f0 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e n, respectively.
2c900 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 Neither of thes
2c910 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 e parameters.**
2c920 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a may be NULL..**.
2c930 2a 2a 20 4d 65 74 61 64 61 74 61 20 69 73 20 72 ** Metadata is r
2c940 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 eturned by writi
2c950 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 ng to the memory
2c960 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 locations passe
2c970 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 d as the 5th.**
2c980 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 and subsequent p
2c990 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 arameters to thi
2c9a0 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 s function. Any
2c9b0 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e of these argumen
2c9c0 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c ts may be.** NUL
2c9d0 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 L, in which case
2c9e0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
2c9f0 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 ng element of me
2ca00 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65 tadata is omitte
2ca10 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 d..**.** <blockq
2ca20 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 uote>.** <table
2ca30 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c border="1">.** <
2ca40 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 tr><th> Paramete
2ca50 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 r <th> Output<br
2ca60 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 >Type <th> Desc
2ca70 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 ription.**.** <t
2ca80 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 r><td> 5th <td>
2ca90 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e const char* <td>
2caa0 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 Data type.** <t
2cab0 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 r><td> 6th <td>
2cac0 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e const char* <td>
2cad0 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 Name of default
2cae0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
2caf0 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 nce.** <tr><td>
2cb00 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 7th <td> int
2cb10 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 <td> True i
2cb20 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e f column has a N
2cb30 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 OT NULL constrai
2cb40 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 nt.** <tr><td> 8
2cb50 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 th <td> int
2cb60 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 <td> True if
2cb70 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 column is part
2cb80 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b of the PRIMARY K
2cb90 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 EY.** <tr><td> 9
2cba0 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 th <td> int
2cbb0 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 <td> True if
2cbc0 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f column is [AUTO
2cbd0 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f INCREMENT].** </
2cbe0 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 table>.** </bloc
2cbf0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
2cc00 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 e memory pointed
2cc10 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 to by the chara
2cc20 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 cter pointers re
2cc30 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a turned for the.*
2cc40 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 * declaration ty
2cc50 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e pe and collation
2cc60 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c sequence is val
2cc70 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 id only until th
2cc80 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 e next.** call t
2cc90 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49 o any SQLite API
2cca0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a function..**.**
2ccb0 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 If the specifie
2ccc0 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 d table is actua
2ccd0 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b lly a view, an [
2cce0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
2ccf0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 eturned..**.** I
2cd00 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 f the specified
2cd10 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 column is "rowid
2cd20 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f ", "oid" or "_ro
2cd30 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 wid_" and an.**
2cd40 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 [INTEGER PRIMARY
2cd50 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 KEY] column has
2cd60 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 been explicitly
2cd70 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 declared, then
2cd80 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 the output.** pa
2cd90 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 rameters are set
2cda0 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 for the explici
2cdb0 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c tly declared col
2cdc0 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73 umn. If there is
2cdd0 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c no.** explicitl
2cde0 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 y declared [INTE
2cdf0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d GER PRIMARY KEY]
2ce00 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 column, then th
2ce10 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 e output.** para
2ce20 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 meters are set a
2ce30 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
2ce40 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 <pre>.** da
2ce50 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 ta type: "INTEGE
2ce60 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 R".** collat
2ce70 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 ion sequence: "B
2ce80 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f INARY".** no
2ce90 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 t null: 0.**
2cea0 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a primary key: 1.
2ceb0 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 ** auto incr
2cec0 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 ement: 0.** </pr
2ced0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 e>.**.** This fu
2cee0 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 nction may load
2cef0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 one or more sche
2cf00 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 mas from databas
2cf10 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a e files. If an.*
2cf20 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 * error occurs d
2cf30 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 uring this proce
2cf40 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 ss, or if the re
2cf50 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 quested table or
2cf60 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f column.** canno
2cf70 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b t be found, an [
2cf80 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
2cf90 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 eturned and an e
2cfa0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 rror message lef
2cfb0 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 t.** in the [dat
2cfc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2cfd0 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 ] (to be retriev
2cfe0 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 ed using sqlite3
2cff0 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a _errmsg())..**.*
2d000 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e * This API is on
2d010 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 ly available if
2d020 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 the library was
2d030 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
2d040 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 e.** [SQLITE_ENA
2d050 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 BLE_COLUMN_METAD
2d060 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 ATA] C-preproces
2d070 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e sor symbol defin
2d080 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ed..*/.int sqlit
2d090 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f e3_table_column_
2d0a0 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 metadata(. sqli
2d0b0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
2d0c0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 /* Conne
2d0d0 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a ction handle */.
2d0e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 const char *zD
2d0f0 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a bName, /*
2d100 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f Database name o
2d110 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 r NULL */. cons
2d120 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 t char *zTableNa
2d130 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 me, /* Table
2d140 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 name */. const
2d150 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 char *zColumnNa
2d160 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e me, /* Column
2d170 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 name */. char
2d180 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 const **pzDataTy
2d190 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 pe, /* OUTPUT
2d1a0 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 : Declared data
2d1b0 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 type */. char c
2d1c0 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 onst **pzCollSeq
2d1d0 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a , /* OUTPUT:
2d1e0 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 Collation seque
2d1f0 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e nce name */. in
2d200 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 t *pNotNull,
2d210 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 /* OUT
2d220 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 PUT: True if NOT
2d230 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 NULL constraint
2d240 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 exists */. int
2d250 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 *pPrimaryKey,
2d260 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 /* OUTP
2d270 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 UT: True if colu
2d280 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f mn part of PK */
2d290 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 . int *pAutoinc
2d2a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
2d2b0 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 * OUTPUT: True i
2d2c0 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f f column is auto
2d2d0 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b -increment */.);
2d2e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2d2f0 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 : Load An Extens
2d300 69 6f 6e 20 7b 48 31 32 36 30 30 7d 20 3c 53 32 ion {H12600} <S2
2d310 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0500>.**.** This
2d320 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73 interface loads
2d330 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e an SQLite exten
2d340 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f sion library fro
2d350 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 m the named file
2d360 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 31 7d ..**.** {H12601}
2d370 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 The sqlite3_loa
2d380 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e d_extension() in
2d390 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 terface attempts
2d3a0 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 20 to load an.**
2d3b0 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 65 SQLite e
2d3c0 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 xtension library
2d3d0 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 contained in th
2d3e0 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a e file zFile..**
2d3f0 0a 2a 2a 20 7b 48 31 32 36 30 32 7d 20 54 68 65 .** {H12602} The
2d400 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 entry point is
2d410 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 zProc..**.** {H1
2d420 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20 2603} zProc may
2d430 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63 be 0, in which c
2d440 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 ase the name of
2d450 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a the entry point.
2d460 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 ** defa
2d470 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 ults to "sqlite3
2d480 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 _extension_init"
2d490 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 34 7d ..**.** {H12604}
2d4a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 The sqlite3_loa
2d4b0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e d_extension() in
2d4c0 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 terface shall re
2d4d0 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 turn.**
2d4e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 [SQLITE_OK] on
2d4f0 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c success and [SQL
2d500 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f ITE_ERROR] if so
2d510 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f mething goes wro
2d520 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 ng..**.** {H1260
2d530 35 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 5} If an error o
2d540 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d ccurs and pzErrM
2d550 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 sg is not 0, the
2d560 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 n the.**
2d570 20 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f [sqlite3_load_
2d580 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 extension()] int
2d590 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 erface shall att
2d5a0 65 6d 70 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 empt to.**
2d5b0 20 20 20 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d fill *pzErrM
2d5c0 73 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65 sg with error me
2d5d0 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 ssage text store
2d5e0 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 d in memory.**
2d5f0 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 obtained
2d600 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
2d610 61 6c 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44 7d 20 alloc()]. {END}
2d620 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e The calling fun
2d630 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ction.**
2d640 20 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 should free th
2d650 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c is memory by cal
2d660 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 ling [sqlite3_fr
2d670 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ee()]..**.** {H1
2d680 32 36 30 36 7d 20 45 78 74 65 6e 73 69 6f 6e 20 2606} Extension
2d690 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 loading must be
2d6a0 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a enabled using.**
2d6b0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
2d6c0 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 e3_enable_load_e
2d6d0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f xtension()] prio
2d6e0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 r to calling thi
2d6f0 73 20 41 50 49 2c 0a 2a 2a 20 20 20 20 20 20 20 s API,.**
2d700 20 20 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 otherwise an
2d710 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 error will be re
2d720 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 turned..*/.int s
2d730 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 qlite3_load_exte
2d740 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 nsion(. sqlite3
2d750 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f *db, /
2d760 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e * Load the exten
2d770 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 sion into this d
2d780 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2d790 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 on */. const ch
2d7a0 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a ar *zFile, /*
2d7b0 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 Name of the sha
2d7c0 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 red library cont
2d7d0 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e aining extension
2d7e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
2d7f0 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 *zProc, /* E
2d800 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 ntry point. Der
2d810 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 ived from zFile
2d820 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a if 0 */. char *
2d830 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 *pzErrMsg
2d840 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 /* Put error mes
2d850 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 sage here if not
2d860 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 0 */.);../*.**
2d870 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 CAPI3REF: Enable
2d880 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 Or Disable Exte
2d890 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 48 nsion Loading {H
2d8a0 31 32 36 32 30 7d 20 3c 53 32 30 35 30 30 3e 0a 12620} <S20500>.
2d8b0 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 **.** So as not
2d8c0 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 to open security
2d8d0 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 holes in older
2d8e0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 applications tha
2d8f0 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 t are.** unprepa
2d900 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 red to deal with
2d910 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 extension loadi
2d920 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 ng, and as a mea
2d930 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a ns of disabling.
2d940 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 ** extension loa
2d950 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 ding while evalu
2d960 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 ating user-enter
2d970 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c ed SQL, the foll
2d980 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 owing API.** is
2d990 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e provided to turn
2d9a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f the [sqlite3_lo
2d9b0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 ad_extension()]
2d9c0 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 mechanism on and
2d9d0 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 off..**.** Exte
2d9e0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 nsion loading is
2d9f0 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e off by default.
2da00 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36 See ticket #186
2da10 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 31 3..**.** {H12621
2da20 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 } Call the sqlit
2da30 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 e3_enable_load_e
2da40 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 xtension() routi
2da50 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 ne with onoff==1
2da60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 .** to
2da70 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c turn extension l
2da80 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 oading on and ca
2da90 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 ll it with onoff
2daa0 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 20 ==0 to turn.**
2dab0 20 20 20 20 20 20 20 20 69 74 20 62 61 63 6b 20 it back
2dac0 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2a 0a 2a 2a off again..**.**
2dad0 20 7b 48 31 32 36 32 32 7d 20 45 78 74 65 6e 73 {H12622} Extens
2dae0 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f ion loading is o
2daf0 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a ff by default..*
2db00 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e /.int sqlite3_en
2db10 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 able_load_extens
2db20 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c ion(sqlite3 *db,
2db30 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a int onoff);../*
2db40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 .** CAPI3REF: Au
2db50 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 tomatically Load
2db60 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 73 20 7b An Extensions {
2db70 48 31 32 36 34 30 7d 20 3c 53 32 30 35 30 30 3e H12640} <S20500>
2db80 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 .**.** This API
2db90 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 can be invoked a
2dba0 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75 t program startu
2dbb0 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 p in order to re
2dbc0 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 gister.** one or
2dbd0 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79 more statically
2dbe0 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f linked extensio
2dbf0 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 ns that will be
2dc00 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 available.** to
2dc10 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62 61 73 all new [databas
2dc20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20 e connections].
2dc30 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 {END}.**.** This
2dc40 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 routine stores
2dc50 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
2dc60 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e extension in an
2dc70 20 61 72 72 61 79 20 74 68 61 74 20 69 73 0a 2a array that is.*
2dc80 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 * obtained from
2dc90 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
2dca0 29 5d 2e 20 20 49 66 20 79 6f 75 20 72 75 6e 20 )]. If you run
2dcb0 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 20 63 68 a memory leak ch
2dcc0 65 63 6b 65 72 0a 2a 2a 20 6f 6e 20 79 6f 75 72 ecker.** on your
2dcd0 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74 20 program and it
2dce0 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20 62 reports a leak b
2dcf0 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 20 61 ecause of this a
2dd00 72 72 61 79 2c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 rray, invoke.**
2dd10 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 [sqlite3_reset_a
2dd20 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d uto_extension()]
2dd30 20 70 72 69 6f 72 20 74 6f 20 73 68 75 74 64 6f prior to shutdo
2dd40 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d wn to free the m
2dd50 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 emory..**.** {H1
2dd60 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74 2641} This funct
2dd70 69 6f 6e 20 72 65 67 69 73 74 65 72 73 20 61 6e ion registers an
2dd80 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 extension entry
2dd90 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73 0a 2a point that is.*
2dda0 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d * autom
2ddb0 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 atically invoked
2ddc0 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 whenever a new
2ddd0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2dde0 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 tion].**
2ddf0 20 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e is opened usin
2de00 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 g [sqlite3_open(
2de10 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
2de20 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 n16()],.**
2de30 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f or [sqlite3_
2de40 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a open_v2()]..**.*
2de50 2a 20 7b 48 31 32 36 34 32 7d 20 44 75 70 6c 69 * {H12642} Dupli
2de60 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 cate extensions
2de70 61 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 are detected so
2de80 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 calling this rou
2de90 74 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 tine.**
2dea0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 multiple times
2deb0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 with the same ex
2dec0 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c tension is harml
2ded0 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 ess..**.** {H126
2dee0 34 33 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65 43} This routine
2def0 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 stores a pointe
2df00 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 r to the extensi
2df10 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a on in an array.*
2df20 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 * that
2df30 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d is obtained from
2df40 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
2df50 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 ()]..**.** {H126
2df60 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65 78 44} Automatic ex
2df70 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 tensions apply a
2df80 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 cross all thread
2df90 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 s..*/.int sqlite
2dfa0 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 3_auto_extension
2dfb0 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f (void (*xEntryPo
2dfc0 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a int)(void));../*
2dfd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
2dfe0 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 set Automatic Ex
2dff0 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 tension Loading
2e000 7b 48 31 32 36 36 30 7d 20 3c 53 32 30 35 30 30 {H12660} <S20500
2e010 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e >.**.** This fun
2e020 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 ction disables a
2e030 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 ll previously re
2e040 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74 gistered automat
2e050 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73 ic.** extensions
2e060 2e 20 7b 45 4e 44 7d 20 20 49 74 20 75 6e 64 6f . {END} It undo
2e070 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 es the effect of
2e080 20 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20 5b 73 all prior.** [s
2e090 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 qlite3_auto_exte
2e0a0 6e 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73 2e 0a nsion()] calls..
2e0b0 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 31 7d 20 54 **.** {H12661} T
2e0c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 his function dis
2e0d0 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f ables all previo
2e0e0 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 0a usly registered.
2e0f0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f ** auto
2e100 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 matic extensions
2e110 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 32 7d ..**.** {H12662}
2e120 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 This function d
2e130 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 isables automati
2e140 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 c extensions in
2e150 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a all threads..*/.
2e160 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
2e170 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f et_auto_extensio
2e180 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a n(void);../*.***
2e190 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c *** EXPERIMENTAL
2e1a0 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 - subject to ch
2e1b0 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 ange without not
2e1c0 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ice ************
2e1d0 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 **.**.** The int
2e1e0 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 erface to the vi
2e1f0 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 rtual-table mech
2e200 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 anism is current
2e210 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a ly considered.**
2e220 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e to be experimen
2e230 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 tal. The interf
2e240 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 ace might change
2e250 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 in incompatible
2e260 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 ways..** If thi
2e270 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 s is a problem f
2e280 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 or you, do not u
2e290 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 se the interface
2e2a0 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a at this time..*
2e2b0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 *.** When the vi
2e2c0 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 rtual-table mech
2e2d0 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 anism stabilizes
2e2e0 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 , we will declar
2e2f0 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 e the.** interfa
2e300 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 ce fixed, suppor
2e310 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c t it indefinitel
2e320 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 y, and remove th
2e330 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a is comment..*/..
2e340 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 /*.** Structures
2e350 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72 used by the vir
2e360 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 tual table inter
2e370 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 face.*/.typedef
2e380 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
2e390 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 tab sqlite3_vtab
2e3a0 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 ;.typedef struct
2e3b0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 sqlite3_index_i
2e3c0 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 nfo sqlite3_inde
2e3d0 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 x_info;.typedef
2e3e0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
2e3f0 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 tab_cursor sqlit
2e400 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a e3_vtab_cursor;.
2e410 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
2e420 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 qlite3_module sq
2e430 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f lite3_module;../
2e440 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 *.** CAPI3REF: V
2e450 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a irtual Table Obj
2e460 65 63 74 20 7b 48 31 38 30 30 30 7d 20 3c 53 32 ect {H18000} <S2
2e470 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0400>.** KEYWORD
2e480 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c S: sqlite3_modul
2e490 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 e {virtual table
2e4a0 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 20 45 58 50 45 module}.** EXPE
2e4b0 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
2e4c0 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20 73 his structure, s
2e4d0 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 20 ometimes called
2e4e0 61 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 a a "virtual tab
2e4f0 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 le module", .**
2e500 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c defines the impl
2e510 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 ementation of a
2e520 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d [virtual tables]
2e530 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 . .** This stru
2e540 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d cture consists m
2e550 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 ostly of methods
2e560 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e for the module.
2e570 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c .**.** A virtual
2e580 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73 table module is
2e590 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c created by fill
2e5a0 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 74 ing in a persist
2e5b0 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 ent.** instance
2e5c0 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 of this structur
2e5d0 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20 e and passing a
2e5e0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 pointer to that
2e5f0 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b instance.** to [
2e600 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d sqlite3_create_m
2e610 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c odule()] or [sql
2e620 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 ite3_create_modu
2e630 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 le_v2()]..** The
2e640 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65 registration re
2e650 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69 mains valid unti
2e660 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 65 64 l it is replaced
2e670 20 62 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a by a different.
2e680 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74 ** module or unt
2e690 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 il the [database
2e6a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f connection] clo
2e6b0 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e ses. The conten
2e6c0 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72 t.** of this str
2e6d0 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20 ucture must not
2e6e0 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20 change while it
2e6f0 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69 is registered wi
2e700 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61 th.** any databa
2e710 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a se connection..*
2e720 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 /.struct sqlite3
2e730 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 _module {. int
2e740 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 iVersion;. int
2e750 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 (*xCreate)(sqlit
2e760 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c e3*, void *pAux,
2e770 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
2e780 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 int argc, const
2e790 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 char *const*argv
2e7a0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
2e7b0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a sqlite3_vtab **
2e7c0 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b ppVTab, char**);
2e7d0 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 . int (*xConnec
2e7e0 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 t)(sqlite3*, voi
2e7f0 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 d *pAux,.
2e800 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 int argc
2e810 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f , const char *co
2e820 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 nst*argv,.
2e830 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 sqlite3
2e840 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 _vtab **ppVTab,
2e850 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 char**);. int (
2e860 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c *xBestIndex)(sql
2e870 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
2e880 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f , sqlite3_index_
2e890 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a info*);. int (*
2e8a0 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c xDisconnect)(sql
2e8b0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
2e8c0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 );. int (*xDest
2e8d0 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 roy)(sqlite3_vta
2e8e0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 b *pVTab);. int
2e8f0 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 (*xOpen)(sqlite
2e900 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 3_vtab *pVTab, s
2e910 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
2e920 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a or **ppCursor);.
2e930 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 int (*xClose)(
2e940 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
2e950 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sor*);. int (*x
2e960 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f Filter)(sqlite3_
2e970 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e vtab_cursor*, in
2e980 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 t idxNum, const
2e990 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 char *idxStr,.
2e9a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e in
2e9b0 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f t argc, sqlite3_
2e9c0 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 value **argv);.
2e9d0 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 int (*xNext)(sq
2e9e0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
2e9f0 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f r*);. int (*xEo
2ea00 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f f)(sqlite3_vtab_
2ea10 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 cursor*);. int
2ea20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 (*xColumn)(sqlit
2ea30 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c e3_vtab_cursor*,
2ea40 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
2ea50 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 *, int);. int (
2ea60 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 *xRowid)(sqlite3
2ea70 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 _vtab_cursor*, s
2ea80 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 qlite3_int64 *pR
2ea90 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 owid);. int (*x
2eaa0 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f Update)(sqlite3_
2eab0 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c vtab *, int, sql
2eac0 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 ite3_value **, s
2ead0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b qlite3_int64 *);
2eae0 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 . int (*xBegin)
2eaf0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
2eb00 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 VTab);. int (*x
2eb10 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 Sync)(sqlite3_vt
2eb20 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e ab *pVTab);. in
2eb30 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c t (*xCommit)(sql
2eb40 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
2eb50 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c );. int (*xRoll
2eb60 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 back)(sqlite3_vt
2eb70 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e ab *pVTab);. in
2eb80 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f t (*xFindFunctio
2eb90 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 n)(sqlite3_vtab
2eba0 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 *pVtab, int nArg
2ebb0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
2ebc0 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 ame,.
2ebd0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 void
2ebe0 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 (**pxFunc)(sqli
2ebf0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
2ec00 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
2ec10 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 ),.
2ec20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a void *
2ec30 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 *ppArg);. int (
2ec40 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 *xRename)(sqlite
2ec50 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 3_vtab *pVtab, c
2ec60 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 onst char *zNew)
2ec70 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ;.};../*.** CAPI
2ec80 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 3REF: Virtual Ta
2ec90 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 ble Indexing Inf
2eca0 6f 72 6d 61 74 69 6f 6e 20 7b 48 31 38 31 30 30 ormation {H18100
2ecb0 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 } <S20400>.** KE
2ecc0 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f YWORDS: sqlite3_
2ecd0 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58 index_info.** EX
2ece0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
2ecf0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 The sqlite3_ind
2ed00 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 ex_info structur
2ed10 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 e and its substr
2ed20 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20 uctures is used
2ed30 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 to.** pass infor
2ed40 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 mation into and
2ed50 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c receive the repl
2ed60 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73 y from the [xBes
2ed70 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f tIndex].** metho
2ed80 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 d of a [virtual
2ed90 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 table module].
2eda0 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72 The fields under
2edb0 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 **Inputs** are
2edc0 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f the.** inputs to
2edd0 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20 xBestIndex and
2ede0 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 are read-only.
2edf0 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72 xBestIndex inser
2ee00 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 ts its.** result
2ee10 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 s into the **Out
2ee20 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a puts** fields..*
2ee30 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 *.** The aConstr
2ee40 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63 aint[] array rec
2ee50 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 75 73 ords WHERE claus
2ee60 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 e constraints of
2ee70 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a the form:.**.**
2ee80 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 <pre>column OP
2ee90 65 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a expr</pre>.**.**
2eea0 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 where OP is =,
2eeb0 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 <, <=, >
2eec0 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20 20 54 68 ;, or >=. Th
2eed0 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 e particular ope
2eee0 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 rator is.** stor
2eef0 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e ed in aConstrain
2ef00 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64 t[].op. The ind
2ef10 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e ex of the column
2ef20 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a is stored in.**
2ef30 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 aConstraint[].i
2ef40 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 Column. aConstr
2ef50 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 aint[].usable is
2ef60 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 TRUE if the.**
2ef70 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68 expr on the righ
2ef80 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20 t-hand side can
2ef90 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e be evaluated (an
2efa0 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74 d thus the const
2efb0 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 raint.** is usab
2efc0 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66 le) and false if
2efd0 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a it cannot..**.*
2efe0 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 * The optimizer
2eff0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e automatically in
2f000 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 verts terms of t
2f010 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 he form "expr OP
2f020 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 column".** and
2f030 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 makes other simp
2f040 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 lifications to t
2f050 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 he WHERE clause
2f060 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f in an attempt to
2f070 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 .** get as many
2f080 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 WHERE clause ter
2f090 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d ms into the form
2f0a0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 shown above as
2f0b0 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 possible..** The
2f0c0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 aConstraint[] a
2f0d0 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 rray only report
2f0e0 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 s WHERE clause t
2f0f0 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72 erms in the corr
2f100 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74 ect.** form that
2f110 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61 refer to the pa
2f120 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c rticular virtual
2f130 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65 table being que
2f140 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f ried..**.** Info
2f150 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 rmation about th
2f160 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 e ORDER BY claus
2f170 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 e is stored in a
2f180 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 OrderBy[]..** Ea
2f190 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 ch term of aOrde
2f1a0 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f rBy records a co
2f1b0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 lumn of the ORDE
2f1c0 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a R BY clause..**.
2f1d0 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 49 6e 64 ** The [xBestInd
2f1e0 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 ex] method must
2f1f0 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 fill aConstraint
2f200 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 Usage[] with inf
2f210 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 ormation.** abou
2f220 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 t what parameter
2f230 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 s to pass to xFi
2f240 6c 74 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e lter. If argvIn
2f250 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 dex>0 then.** th
2f260 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 e right-hand sid
2f270 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 e of the corresp
2f280 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 onding aConstrai
2f290 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 nt[] is evaluate
2f2a0 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 d.** and becomes
2f2b0 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 the argvIndex-t
2f2c0 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e h entry in argv.
2f2d0 20 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 If aConstraint
2f2e0 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 Usage[].omit.**
2f2f0 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 is true, then th
2f300 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 e constraint is
2f310 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 assumed to be fu
2f320 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 lly handled by t
2f330 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 he.** virtual ta
2f340 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 ble and is not c
2f350 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 hecked again by
2f360 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 SQLite..**.** Th
2f370 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 e idxNum and idx
2f380 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 Ptr values are r
2f390 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 ecorded and pass
2f3a0 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b ed into the.** [
2f3b0 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e xFilter] method.
2f3c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 .** [sqlite3_fre
2f3d0 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 e()] is used to
2f3e0 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61 free idxPtr if a
2f3f0 6e 64 20 6f 6e 6c 79 20 69 66 66 0a 2a 2a 20 6e nd only iff.** n
2f400 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 eedToFreeIdxPtr
2f410 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 is true..**.** T
2f420 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d he orderByConsum
2f430 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 ed means that ou
2f440 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74 tput from [xFilt
2f450 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c er]/[xNext] will
2f460 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 occur in.** the
2f470 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 correct order t
2f480 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 o satisfy the OR
2f490 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f DER BY clause so
2f4a0 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 that no separat
2f4b0 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 e.** sorting ste
2f4c0 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a p is required..*
2f4d0 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61 74 *.** The estimat
2f4e0 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20 edCost value is
2f4f0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 an estimate of t
2f500 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 he cost of doing
2f510 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c the.** particul
2f520 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 ar lookup. A fu
2f530 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62 ll scan of a tab
2f540 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65 le with N entrie
2f550 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a s should have.**
2f560 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 a cost of N. A
2f570 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f binary search o
2f580 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 f a table of N e
2f590 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 ntries should ha
2f5a0 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 ve a.** cost of
2f5b0 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f approximately lo
2f5c0 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 g(N)..*/.struct
2f5d0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e sqlite3_index_in
2f5e0 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 fo {. /* Inputs
2f5f0 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 */. int nConst
2f600 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 raint;
2f610 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e /* Number of en
2f620 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 tries in aConstr
2f630 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 aint */. struct
2f640 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 sqlite3_index_c
2f650 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 onstraint {.
2f660 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 int iColumn;
2f670 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f /* Co
2f680 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e lumn on left-han
2f690 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 d side of constr
2f6a0 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 aint */. uns
2f6b0 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 igned char op;
2f6c0 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 /* Constr
2f6d0 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f aint operator */
2f6e0 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 . unsigned c
2f6f0 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 har usable;
2f700 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20 /* True if this
2f710 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 constraint is us
2f720 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 able */. int
2f730 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 iTermOffset;
2f740 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 /* Used i
2f750 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 nternally - xBes
2f760 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 tIndex should ig
2f770 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f nore */. } *aCo
2f780 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 nstraint;
2f790 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 /* Table of
2f7a0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f WHERE clause co
2f7b0 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 nstraints */. i
2f7c0 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 nt nOrderBy;
2f7d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d /* Num
2f7e0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 ber of terms in
2f7f0 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 the ORDER BY cla
2f800 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 use */. struct
2f810 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 sqlite3_index_or
2f820 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 derby {. int
2f830 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 iColumn;
2f840 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e /* Column
2f850 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 number */.
2f860 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 unsigned char de
2f870 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 sc; /* Tru
2f880 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c e for DESC. Fal
2f890 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 se for ASC. */.
2f8a0 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 } *aOrderBy;
2f8b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 /* T
2f8c0 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 he ORDER BY clau
2f8d0 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 se */. /* Outpu
2f8e0 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 ts */. struct s
2f8f0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e qlite3_index_con
2f900 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a straint_usage {.
2f910 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 int argvInde
2f920 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 x; /*
2f930 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e if >0, constrain
2f940 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 t is part of arg
2f950 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a v to xFilter */.
2f960 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 unsigned cha
2f970 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 r omit; /*
2f980 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 Do not code a te
2f990 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 st for this cons
2f9a0 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 traint */. } *a
2f9b0 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b ConstraintUsage;
2f9c0 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 . int idxNum;
2f9d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2f9e0 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 Number used to
2f9f0 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 identify the ind
2fa00 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 ex */. char *id
2fa10 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 xStr;
2fa20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f /* String, po
2fa30 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 ssibly obtained
2fa40 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c from sqlite3_mal
2fa50 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 loc */. int nee
2fa60 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 dToFreeIdxStr;
2fa70 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 /* Free idxS
2fa80 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 tr using sqlite3
2fa90 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20 _free() if true
2faa0 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 */. int orderBy
2fab0 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 Consumed;
2fac0 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 /* True if outpu
2fad0 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 t is already ord
2fae0 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 ered */. double
2faf0 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 estimatedCost;
2fb00 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 /* Estimate
2fb10 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 d cost of using
2fb20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b this index */.};
2fb30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2fb40 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
2fb50 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 _EQ 2.#define
2fb60 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
2fb70 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 NSTRAINT_GT 4
2fb80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2fb90 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
2fba0 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 _LE 8.#define
2fbb0 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
2fbc0 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 NSTRAINT_LT 1
2fbd0 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 6.#define SQLITE
2fbe0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e _INDEX_CONSTRAIN
2fbf0 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 T_GE 32.#defi
2fc00 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f ne SQLITE_INDEX_
2fc10 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 CONSTRAINT_MATCH
2fc20 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 64../*.** CAPI3
2fc30 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 REF: Register A
2fc40 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d Virtual Table Im
2fc50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 31 plementation {H1
2fc60 38 32 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 8200} <S20400>.*
2fc70 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
2fc80 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
2fc90 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 67 e is used to reg
2fca0 69 73 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72 ister a new [vir
2fcb0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c tual table modul
2fcc0 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 4d 6f 64 75 e] name..** Modu
2fcd0 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 le names must be
2fce0 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f registered befo
2fcf0 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61 re.** creating a
2fd00 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 new [virtual ta
2fd10 62 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d ble] using the m
2fd20 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 odule, or before
2fd30 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65 using a.** pree
2fd40 78 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c xisting [virtual
2fd50 20 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20 table] for the
2fd60 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 module..**.** Th
2fd70 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73 e module name is
2fd80 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74 registered on t
2fd90 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
2fda0 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 nection] specifi
2fdb0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 ed.** by the fir
2fdc0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 st parameter. T
2fdd0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d he name of the m
2fde0 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20 62 odule is given b
2fdf0 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64 y the .** second
2fe00 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 parameter. The
2fe10 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
2fe20 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
2fe30 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e .** the implemen
2fe40 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 76 tation of the [v
2fe50 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 irtual table mod
2fe60 75 6c 65 5d 2e 20 20 20 54 68 65 20 66 6f 75 72 ule]. The four
2fe70 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 th.** parameter
2fe80 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 is an arbitrary
2fe90 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e client data poin
2fea0 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 ter that is pass
2feb0 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e ed through.** in
2fec0 74 6f 20 74 68 65 20 5b 78 43 72 65 61 74 65 5d to the [xCreate]
2fed0 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 and [xConnect]
2fee0 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20 76 methods of the v
2fef0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 irtual table mod
2ff00 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65 ule.** when a ne
2ff10 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 w virtual table
2ff20 69 73 20 62 65 20 62 65 69 6e 67 20 63 72 65 61 is be being crea
2ff30 74 65 64 20 6f 72 20 72 65 69 6e 69 74 69 61 6c ted or reinitial
2ff40 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ized..**.** This
2ff50 20 69 6e 74 65 72 66 61 63 65 20 68 61 73 20 65 interface has e
2ff60 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 xactly the same
2ff70 65 66 66 65 63 74 20 61 73 20 63 61 6c 6c 69 6e effect as callin
2ff80 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 g.** [sqlite3_cr
2ff90 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 eate_module_v2()
2ffa0 5d 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 63 6c ] with a NULL cl
2ffb0 69 65 6e 74 20 64 61 74 61 20 64 65 73 74 72 75 ient data destru
2ffc0 63 74 6f 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ctor..*/.SQLITE_
2ffd0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 EXPERIMENTAL int
2ffe0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
2fff0 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65 module(. sqlite
30000 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
30010 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 /* SQLite c
30020 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 onnection to reg
30030 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 ister module wit
30040 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 h */. const cha
30050 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 r *zName,
30060 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 /* Name of the
30070 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e module */. con
30080 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c st sqlite3_modul
30090 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f e *p, /* Metho
300a0 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c ds for the modul
300b0 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c e */. void *pCl
300c0 69 65 6e 74 44 61 74 61 20 20 20 20 20 20 20 20 ientData
300d0 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 /* Client data
300e0 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f for xCreate/xCo
300f0 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a nnect */.);../*.
30100 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 ** CAPI3REF: Reg
30110 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 ister A Virtual
30120 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 Table Implementa
30130 74 69 6f 6e 20 7b 48 31 38 32 31 30 7d 20 3c 53 tion {H18210} <S
30140 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 20400>.** EXPERI
30150 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 MENTAL.**.** Thi
30160 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65 s routine is ide
30170 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 5b 73 ntical to the [s
30180 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f qlite3_create_mo
30190 64 75 6c 65 28 29 5d 20 6d 65 74 68 6f 64 2c 0a dule()] method,.
301a0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 ** except that i
301b0 74 20 68 61 73 20 61 6e 20 65 78 74 72 61 20 70 t has an extra p
301c0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 70 65 63 arameter to spec
301d0 69 66 79 20 0a 2a 2a 20 61 20 64 65 73 74 72 75 ify .** a destru
301e0 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f ctor function fo
301f0 72 20 74 68 65 20 63 6c 69 65 6e 74 20 64 61 74 r the client dat
30200 61 20 70 6f 69 6e 74 65 72 2e 20 20 53 51 4c 69 a pointer. SQLi
30210 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b te will.** invok
30220 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 e the destructor
30230 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74 function (if it
30240 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 is not NULL) wh
30250 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 en SQLite.** no
30260 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65 longer needs the
30270 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69 pClientData poi
30280 6e 74 65 72 2e 20 20 0a 2a 2f 0a 53 51 4c 49 54 nter. .*/.SQLIT
30290 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 E_EXPERIMENTAL i
302a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
302b0 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 e_module_v2(. s
302c0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
302d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c /* SQL
302e0 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ite connection t
302f0 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c o register modul
30300 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 e with */. cons
30310 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 t char *zName,
30320 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f /* Name o
30330 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a f the module */.
30340 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f const sqlite3_
30350 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 module *p, /*
30360 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 Methods for the
30370 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 module */. void
30380 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20 20 *pClientData,
30390 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 /* Client
303a0 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 data for xCreat
303b0 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 e/xConnect */.
303c0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 void(*xDestroy)(
303d0 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f void*) /* Mo
303e0 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20 dule destructor
303f0 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a function */.);..
30400 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
30410 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e Virtual Table In
30420 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 20 7b 48 stance Object {H
30430 31 38 30 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a 18010} <S20400>.
30440 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
30450 69 74 65 33 5f 76 74 61 62 0a 2a 2a 20 45 58 50 ite3_vtab.** EXP
30460 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
30470 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 Every [virtual t
30480 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 able module] imp
30490 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 lementation uses
304a0 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f a subclass.** o
304b0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
304c0 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 65 73 structure to des
304d0 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c cribe a particul
304e0 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f ar instance.** o
304f0 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 f the [virtual t
30500 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 62 able]. Each sub
30510 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 class will.** be
30520 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 tailored to the
30530 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 specific needs
30540 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d of the module im
30550 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a plementation..**
30560 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20 The purpose of
30570 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 this superclass
30580 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 is to define cer
30590 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 tain fields that
305a0 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 are.** common t
305b0 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 o all module imp
305c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a lementations..**
305d0 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c .** Virtual tabl
305e0 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 es methods can s
305f0 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 et an error mess
30600 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67 age by assigning
30610 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 a.** string obt
30620 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
30630 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74 te3_mprintf()] t
30640 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20 o zErrMsg. The
30650 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a method should.**
30660 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20 take care that
30670 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67 any prior string
30680 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63 is freed by a c
30690 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
306a0 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 free()].** prior
306b0 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 to assigning a
306c0 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 new string to zE
306d0 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74 68 rrMsg. After th
306e0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a e error message.
306f0 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 20 ** is delivered
30700 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 up to the client
30710 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 application, th
30720 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 e string will be
30730 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a automatically.*
30740 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 74 * freed by sqlit
30750 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68 e3_free() and th
30760 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20 e zErrMsg field
30770 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 0a will be zeroed..
30780 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 */.struct sqlite
30790 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 3_vtab {. const
307a0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 sqlite3_module
307b0 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 *pModule; /* Th
307c0 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 e module for thi
307d0 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 s virtual table
307e0 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 */. int nRef;
307f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
30800 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 /* Used int
30810 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 ernally */. cha
30820 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 r *zErrMsg;
30830 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
30840 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 Error message fr
30850 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e om sqlite3_mprin
30860 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 tf() */. /* Vir
30870 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 tual table imple
30880 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 mentations will
30890 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 typically add ad
308a0 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 ditional fields
308b0 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
308c0 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 I3REF: Virtual T
308d0 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 able Cursor Obje
308e0 63 74 20 20 7b 48 31 38 30 32 30 7d 20 3c 53 32 ct {H18020} <S2
308f0 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0400>.** KEYWORD
30900 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f S: sqlite3_vtab_
30910 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20 cursor {virtual
30920 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a table cursor}.**
30930 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
30940 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 .** Every [virtu
30950 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d al table module]
30960 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
30970 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 uses a subclass
30980 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 of the.** follow
30990 69 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f ing structure to
309a0 20 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72 describe cursor
309b0 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 s that point int
309c0 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 o the.** [virtua
309d0 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65 l table] and are
309e0 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 used.** to loop
309f0 20 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 through the vir
30a00 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 tual table. Cur
30a10 73 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64 sors are created
30a20 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
30a30 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f qlite3_module.xO
30a40 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 pen | xOpen] met
30a50 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c hod of the modul
30a60 65 20 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f e and are destro
30a70 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73 yed.** by the [s
30a80 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 qlite3_module.xC
30a90 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d lose | xClose] m
30aa0 65 74 68 6f 64 2e 20 20 43 75 73 73 6f 72 73 20 ethod. Cussors
30ab0 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 are used.** by t
30ac0 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78 he [xFilter], [x
30ad0 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b Next], [xEof], [
30ae0 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 xColumn], and [x
30af0 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a Rowid] methods.*
30b00 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e * of the module.
30b10 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d Each module im
30b20 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c plementation wil
30b30 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 l define.** the
30b40 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 content of a cur
30b50 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f sor structure to
30b60 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 suit its own ne
30b70 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 eds..**.** This
30b80 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 superclass exist
30b90 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 s in order to de
30ba0 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 fine fields of t
30bb0 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a he cursor that.*
30bc0 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 * are common to
30bd0 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 all implementati
30be0 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 ons..*/.struct s
30bf0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
30c00 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 or {. sqlite3_v
30c10 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 tab *pVtab;
30c20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c /* Virtual tabl
30c30 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 e of this cursor
30c40 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c */. /* Virtual
30c50 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 table implement
30c60 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 ations will typi
30c70 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 cally add additi
30c80 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d onal fields */.}
30c90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
30ca0 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53 F: Declare The S
30cb0 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75 chema Of A Virtu
30cc0 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 32 38 30 al Table {H18280
30cd0 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 } <S20400>.** EX
30ce0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
30cf0 20 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 The [xCreate] a
30d00 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 nd [xConnect] me
30d10 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 thods of a.** [v
30d20 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 irtual table mod
30d30 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69 ule] call this i
30d40 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64 nterface.** to d
30d50 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 eclare the forma
30d60 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 t (the names and
30d70 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 datatypes of th
30d80 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a e columns) of.**
30d90 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 the virtual tab
30da0 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 les they impleme
30db0 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 nt..*/.SQLITE_EX
30dc0 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 PERIMENTAL int s
30dd0 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 qlite3_declare_v
30de0 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f tab(sqlite3*, co
30df0 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b nst char *zSQL);
30e00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
30e10 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e : Overload A Fun
30e20 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 ction For A Virt
30e30 75 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 33 30 ual Table {H1830
30e40 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 0} <S20400>.** E
30e50 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
30e60 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 * Virtual tables
30e70 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 can provide alt
30e80 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 ernative impleme
30e90 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 ntations of func
30ea0 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 tions.** using t
30eb0 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f he [xFindFunctio
30ec0 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 n] method of the
30ed0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 [virtual table
30ee0 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 module]. .** Bu
30ef0 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e t global version
30f00 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 s of those funct
30f10 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 ions.** must exi
30f20 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 st in order to b
30f30 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a e overloaded..**
30f40 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b .** This API mak
30f50 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c es sure a global
30f60 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 version of a fu
30f70 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 nction with a pa
30f80 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 rticular.** name
30f90 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 and number of p
30fa0 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 arameters exists
30fb0 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 . If no such fu
30fc0 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a nction exists.**
30fd0 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 before this API
30fe0 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 is called, a ne
30ff0 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 w function is cr
31000 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c eated. The impl
31010 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 ementation.** of
31020 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f the new functio
31030 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 n always causes
31040 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 an exception to
31050 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a be thrown. So.*
31060 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 * the new functi
31070 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 on is not good f
31080 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 or anything by i
31090 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 tself. Its only
310a0 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 .** purpose is t
310b0 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c 64 o be a placehold
310c0 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 er function that
310d0 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 can be overload
310e0 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72 74 ed.** by a [virt
310f0 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 53 ual table]..*/.S
31100 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 QLITE_EXPERIMENT
31110 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f AL int sqlite3_o
31120 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e verload_function
31130 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 (sqlite3*, const
31140 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 char *zFuncName
31150 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a , int nArg);../*
31160 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 .** The interfac
31170 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c e to the virtual
31180 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d -table mechanism
31190 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 defined above (
311a0 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 back up.** to a
311b0 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 comment remarkab
311c0 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 ly similar to th
311d0 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 is one) is curre
311e0 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a ntly considered.
311f0 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d ** to be experim
31200 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 ental. The inte
31210 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e rface might chan
31220 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 ge in incompatib
31230 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 le ways..** If t
31240 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d his is a problem
31250 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 for you, do not
31260 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 use the interfa
31270 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e ce at this time.
31280 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
31290 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 virtual-table me
312a0 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a chanism stabiliz
312b0 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c es, we will decl
312c0 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 are the.** inter
312d0 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 face fixed, supp
312e0 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 ort it indefinit
312f0 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 ely, and remove
31300 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a this comment..**
31310 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 .****** EXPERIME
31320 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 NTAL - subject t
31330 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 o change without
31340 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a notice ********
31350 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a ******.*/../*.**
31360 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e CAPI3REF: A Han
31370 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 dle To An Open B
31380 4c 4f 42 20 7b 48 31 37 38 30 30 7d 20 3c 53 33 LOB {H17800} <S3
31390 30 32 33 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0230>.** KEYWORD
313a0 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d S: {BLOB handle}
313b0 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a {BLOB handles}.
313c0 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 **.** An instanc
313d0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
313e0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f represents an o
313f0 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 pen BLOB on whic
31400 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c h.** [sqlite3_bl
31410 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d ob_open | increm
31420 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 ental BLOB I/O]
31430 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 can be performed
31440 2e 0a 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66 20 ..** Objects of
31450 74 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72 this type are cr
31460 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 eated by [sqlite
31470 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 3_blob_open()].*
31480 2a 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 * and destroyed
31490 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 by [sqlite3_blob
314a0 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 _close()]..** Th
314b0 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f e [sqlite3_blob_
314c0 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c read()] and [sql
314d0 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 ite3_blob_write(
314e0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a )] interfaces.**
314f0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
31500 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d read or write sm
31510 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 all subsections
31520 6f 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 of the BLOB..**
31530 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f The [sqlite3_blo
31540 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 b_bytes()] inter
31550 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
31560 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f size of the BLO
31570 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 B in bytes..*/.t
31580 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
31590 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 lite3_blob sqlit
315a0 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 e3_blob;../*.**
315b0 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 CAPI3REF: Open A
315c0 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d BLOB For Increm
315d0 65 6e 74 61 6c 20 49 2f 4f 20 7b 48 31 37 38 31 ental I/O {H1781
315e0 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 0} <S30230>.**.*
315f0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
31600 73 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 s opens a [BLOB
31610 68 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d handle | handle]
31620 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 to the BLOB loc
31630 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 ated.** in row i
31640 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c Row, column zCol
31650 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c umn, table zTabl
31660 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 e in database zD
31670 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 b;.** in other w
31680 6f 72 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42 ords, the same B
31690 4c 4f 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62 LOB that would b
316a0 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a e selected by:.*
316b0 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 *.** <pre>.**
316c0 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e SELECT zColumn
316d0 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 FROM zDb.zTable
316e0 20 57 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d WHERE [rowid] =
316f0 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e iRow;.** </pre>
31700 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 {END}.**.** If
31710 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 the flags parame
31720 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c ter is non-zero,
31730 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 then the BLOB i
31740 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
31750 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 61 d.** and write a
31760 63 63 65 73 73 2e 20 49 66 20 69 74 20 69 73 20 ccess. If it is
31770 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69 zero, the BLOB i
31780 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
31790 64 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 d access..**.**
317a0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 64 61 Note that the da
317b0 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e tabase name is n
317c0 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 ot the filename
317d0 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a that contains.**
317e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 the database bu
317f0 74 20 72 61 74 68 65 72 20 74 68 65 20 73 79 6d t rather the sym
31800 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68 bolic name of th
31810 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74 0a e database that.
31820 2a 2a 20 69 73 20 61 73 73 69 67 6e 65 64 20 77 ** is assigned w
31830 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
31840 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 is connected us
31850 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a ing [ATTACH]..**
31860 20 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 For the main da
31870 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 tabase file, the
31880 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 database name i
31890 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 46 6f 72 s "main"..** For
318a0 20 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 TEMP tables, th
318b0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 e database name
318c0 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a is "temp"..**.**
318d0 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 On success, [SQ
318e0 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 LITE_OK] is retu
318f0 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77 rned and the new
31900 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 [BLOB handle] i
31910 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 s written.** to
31920 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 *ppBlob. Otherwi
31930 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 se an [error cod
31940 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 e] is returned a
31950 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 nd *ppBlob is se
31960 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c t.** to be a nul
31970 6c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 l pointer..** Th
31980 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 is function sets
31990 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
319a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 onnection] error
319b0 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 code and messag
319c0 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 e.** accessible
319d0 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 via [sqlite3_err
319e0 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c code()] and [sql
319f0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 ite3_errmsg()] a
31a00 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 nd related.** fu
31a10 6e 63 74 69 6f 6e 73 2e 20 20 4e 6f 74 65 20 74 nctions. Note t
31a20 68 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 hat the *ppBlob
31a30 76 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 variable is alwa
31a40 79 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 ys initialized i
31a50 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 n a.** way that
31a60 6d 61 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f makes it safe to
31a70 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 invoke [sqlite3
31a80 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f _blob_close()] o
31a90 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 n *ppBlob.** reg
31aa0 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 ardless of the s
31ab0 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 uccess or failur
31ac0 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e e of this routin
31ad0 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 e..**.** If the
31ae0 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 row that a BLOB
31af0 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f handle points to
31b00 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 is modified by
31b10 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 an.** [UPDATE],
31b20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 [DELETE], or by
31b30 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 [ON CONFLICT] si
31b40 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 de-effects.** th
31b50 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 en the BLOB hand
31b60 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 le is marked as
31b70 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 "expired"..** Th
31b80 69 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e is is true if an
31b90 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 y column of the
31ba0 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 row is changed,
31bb0 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a even a column.**
31bc0 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 other than the
31bd0 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e one the BLOB han
31be0 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a dle is open on..
31bf0 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c ** Calls to [sql
31c00 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 ite3_blob_read()
31c10 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 ] and [sqlite3_b
31c20 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 lob_write()] for
31c30 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c .** a expired BL
31c40 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 OB handle fail w
31c50 69 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f ith an return co
31c60 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 de of [SQLITE_AB
31c70 4f 52 54 5d 2e 0a 2a 2a 20 43 68 61 6e 67 65 73 ORT]..** Changes
31c80 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 written into a
31c90 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68 BLOB prior to th
31ca0 65 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 e BLOB expiring
31cb0 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 are not.** rollb
31cc0 61 63 6b 20 62 79 20 74 68 65 20 65 78 70 69 72 ack by the expir
31cd0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f ation of the BLO
31ce0 42 2e 20 20 53 75 63 68 20 63 68 61 6e 67 65 73 B. Such changes
31cf0 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 will eventually
31d00 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 .** commit if th
31d10 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f e transaction co
31d20 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c ntinues to compl
31d30 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 73 65 etion..**.** Use
31d40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c the [sqlite3_bl
31d50 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 ob_bytes()] inte
31d60 72 66 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69 rface to determi
31d70 6e 65 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a ne the size of.*
31d80 2a 20 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f * the opened blo
31d90 62 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 b. The size of
31da0 61 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 a blob may not b
31db0 65 20 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 e changed by thi
31dc0 73 0a 2a 2a 20 75 6e 64 65 72 66 61 63 65 2e 20 s.** underface.
31dd0 20 55 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 Use the [UPDATE
31de0 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f ] SQL command to
31df0 20 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 change the size
31e00 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a of a.** blob..*
31e10 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 *.** The [sqlite
31e20 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 3_bind_zeroblob(
31e30 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
31e40 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 result_zeroblob(
31e50 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a )] interfaces.**
31e60 20 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69 and the built-i
31e70 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c n [zeroblob] SQL
31e80 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 function can be
31e90 20 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65 used, if desire
31ea0 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 d,.** to create
31eb0 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 an empty, zero-f
31ec0 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 illed blob in wh
31ed0 69 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77 ich to read or w
31ee0 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 rite using.** th
31ef0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a is interface..**
31f00 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72 .** To avoid a r
31f10 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 esource leak, ev
31f20 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 ery open [BLOB h
31f30 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 andle] should ev
31f40 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 entually.** be r
31f50 65 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c eleased by a cal
31f60 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c l to [sqlite3_bl
31f70 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a ob_close()]..**.
31f80 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
31f90 0a 2a 2a 20 5b 48 31 37 38 31 33 5d 20 5b 48 31 .** [H17813] [H1
31fa0 37 38 31 34 5d 20 5b 48 31 37 38 31 36 5d 20 5b 7814] [H17816] [
31fb0 48 31 37 38 31 39 5d 20 5b 48 31 37 38 32 31 5d H17819] [H17821]
31fc0 20 5b 48 31 37 38 32 34 5d 0a 2a 2f 0a 69 6e 74 [H17824].*/.int
31fd0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 sqlite3_blob_op
31fe0 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a en(. sqlite3*,.
31ff0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 const char *zD
32000 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 b,. const char
32010 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 *zTable,. const
32020 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a char *zColumn,.
32030 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 sqlite3_int64
32040 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 iRow,. int flag
32050 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f s,. sqlite3_blo
32060 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f b **ppBlob.);../
32070 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
32080 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 lose A BLOB Hand
32090 6c 65 20 7b 48 31 37 38 33 30 7d 20 3c 53 33 30 le {H17830} <S30
320a0 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 230>.**.** Close
320b0 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 s an open [BLOB
320c0 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 handle]..**.** C
320d0 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 losing a BLOB sh
320e0 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 63 75 all cause the cu
320f0 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f rrent transactio
32100 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 n to commit.** i
32110 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f f there are no o
32120 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 ther BLOBs, no p
32130 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65 64 20 ending prepared
32140 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 statements, and
32150 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
32160 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e connection is in
32170 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 [autocommit mod
32180 65 5d 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 77 72 e]..** If any wr
32190 69 74 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 ites were made t
321a0 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 o the BLOB, they
321b0 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 might be held i
321c0 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c n cache.** until
321d0 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 the close opera
321e0 74 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c tion if they wil
321f0 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f l fit..**.** Clo
32200 73 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 sing the BLOB of
32210 74 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63 ten forces the c
32220 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f hanges.** out to
32230 20 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 disk and so if
32240 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f any I/O errors o
32250 63 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 ccur, they will
32260 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 likely occur.**
32270 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e at the time when
32280 20 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f the BLOB is clo
32290 73 65 64 2e 20 20 41 6e 79 20 65 72 72 6f 72 73 sed. Any errors
322a0 20 74 68 61 74 20 6f 63 63 75 72 20 64 75 72 69 that occur duri
322b0 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 ng.** closing ar
322c0 65 20 72 65 70 6f 72 74 65 64 20 61 73 20 61 20 e reported as a
322d0 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 non-zero return
322e0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 value..**.** The
322f0 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 BLOB is closed
32300 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e unconditionally.
32310 20 20 45 76 65 6e 20 69 66 20 74 68 69 73 20 72 Even if this r
32320 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a outine returns.*
32330 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c * an error code,
32340 20 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69 the BLOB is sti
32350 6c 6c 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a ll closed..**.**
32360 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f Calling this ro
32370 75 74 69 6e 65 20 77 69 74 68 20 61 20 6e 75 6c utine with a nul
32380 6c 20 70 6f 69 6e 74 65 72 20 28 77 68 69 63 68 l pointer (which
32390 20 61 73 20 77 6f 75 6c 64 20 62 65 20 72 65 74 as would be ret
323a0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 66 61 69 6c urned.** by fail
323b0 65 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ed call to [sqli
323c0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d te3_blob_open()]
323d0 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 ) is a harmless
323e0 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 no-op..**.** Req
323f0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
32400 31 37 38 33 33 5d 20 5b 48 31 37 38 33 36 5d 20 17833] [H17836]
32410 5b 48 31 37 38 33 39 5d 0a 2a 2f 0a 69 6e 74 20 [H17839].*/.int
32420 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f sqlite3_blob_clo
32430 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 se(sqlite3_blob
32440 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
32450 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 REF: Return The
32460 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 Size Of An Open
32470 42 4c 4f 42 20 7b 48 31 37 38 34 30 7d 20 3c 53 BLOB {H17840} <S
32480 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 30230>.**.** Ret
32490 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 69 6e urns the size in
324a0 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c bytes of the BL
324b0 4f 42 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 OB accessible vi
324c0 61 20 74 68 65 20 0a 2a 2a 20 73 75 63 63 65 73 a the .** succes
324d0 73 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42 sfully opened [B
324e0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69 LOB handle] in i
324f0 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 ts only argument
32500 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d . The.** increm
32510 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 ental blob I/O r
32520 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 outines can only
32530 20 72 65 61 64 20 6f 72 20 6f 76 65 72 77 72 69 read or overwri
32540 74 69 6e 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a ting existing.**
32550 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74 blob content; t
32560 68 65 79 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 hey cannot chang
32570 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 e the size of a
32580 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 blob..**.** This
32590 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f routine only wo
325a0 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 rks on a [BLOB h
325b0 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 andle] which has
325c0 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a been created.**
325d0 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 by a prior succ
325e0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
325f0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
32600 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 n()] and which h
32610 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 as not.** been c
32620 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 losed by [sqlite
32630 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 3_blob_close()].
32640 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 Passing any ot
32650 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a her pointer in.*
32660 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e * to this routin
32670 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 e results in und
32680 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 efined and proba
32690 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 bly undesirable
326a0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 behavior..**.**
326b0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
326c0 20 5b 48 31 37 38 34 33 5d 0a 2a 2f 0a 69 6e 74 [H17843].*/.int
326d0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 sqlite3_blob_by
326e0 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 tes(sqlite3_blob
326f0 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 *);../*.** CAPI
32700 33 52 45 46 3a 20 52 65 61 64 20 44 61 74 61 20 3REF: Read Data
32710 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 From A BLOB Incr
32720 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 35 ementally {H1785
32730 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 0} <S30230>.**.*
32740 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
32750 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 is used to read
32760 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 data from an ope
32770 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 n [BLOB handle]
32780 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 into a.** caller
32790 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 -supplied buffer
327a0 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 . N bytes of dat
327b0 61 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 a are copied int
327c0 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 o buffer Z.** fr
327d0 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 om the open BLOB
327e0 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 , starting at of
327f0 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a fset iOffset..**
32800 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f .** If offset iO
32810 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 ffset is less th
32820 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 an N bytes from
32830 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 the end of the B
32840 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f LOB,.** [SQLITE_
32850 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e ERROR] is return
32860 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 ed and no data i
32870 73 20 72 65 61 64 2e 20 20 49 66 20 4e 20 6f 72 s read. If N or
32880 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c iOffset is.** l
32890 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b ess than zero, [
328a0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 SQLITE_ERROR] is
328b0 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f returned and no
328c0 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a data is read..*
328d0 2a 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 * The size of th
328e0 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63 e blob (and henc
328f0 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 e the maximum va
32900 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 lue of N+iOffset
32910 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 ).** can be dete
32920 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 rmined using the
32930 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 [sqlite3_blob_b
32940 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 ytes()] interfac
32950 65 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 e..**.** An atte
32960 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d mpt to read from
32970 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f an expired [BLO
32980 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 B handle] fails
32990 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 with an.** error
329a0 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 code of [SQLITE
329b0 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f _ABORT]..**.** O
329c0 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 n success, SQLIT
329d0 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 E_OK is returned
329e0 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 ..** Otherwise,
329f0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
32a00 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 or an [extended
32a10 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
32a20 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 eturned..**.** T
32a30 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 his routine only
32a40 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f works on a [BLO
32a50 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 B handle] which
32a60 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 has been created
32a70 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 .** by a prior s
32a80 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
32a90 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f o [sqlite3_blob_
32aa0 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 open()] and whic
32ab0 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 h has not.** bee
32ac0 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c n closed by [sql
32ad0 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 ite3_blob_close(
32ae0 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 )]. Passing any
32af0 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 other pointer i
32b00 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 n.** to this rou
32b10 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 tine results in
32b20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 undefined and pr
32b30 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 obably undesirab
32b40 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a le behavior..**.
32b50 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
32b60 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 lite3_blob_write
32b70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ()]..**.** Requi
32b80 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 rements:.** [H17
32b90 38 35 33 5d 20 5b 48 31 37 38 35 36 5d 20 5b 48 853] [H17856] [H
32ba0 31 37 38 35 39 5d 20 5b 48 31 37 38 36 32 5d 20 17859] [H17862]
32bb0 5b 48 31 37 38 36 33 5d 20 5b 48 31 37 38 36 35 [H17863] [H17865
32bc0 5d 20 5b 48 31 37 38 36 38 5d 0a 2a 2f 0a 69 6e ] [H17868].*/.in
32bd0 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 t sqlite3_blob_r
32be0 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ead(sqlite3_blob
32bf0 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 *, void *Z, int
32c00 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 N, int iOffset)
32c10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
32c20 46 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e F: Write Data In
32c30 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d to A BLOB Increm
32c40 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 37 30 7d entally {H17870}
32c50 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 <S30230>.**.**
32c60 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 This function is
32c70 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 used to write d
32c80 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e ata into an open
32c90 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 [BLOB handle] f
32ca0 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d rom a.** caller-
32cb0 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e supplied buffer.
32cc0 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 N bytes of data
32cd0 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d are copied from
32ce0 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a the buffer Z.**
32cf0 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 into the open B
32d00 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 LOB, starting at
32d10 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e offset iOffset.
32d20 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 42 .**.** If the [B
32d30 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 LOB handle] pass
32d40 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ed as the first
32d50 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 argument was not
32d60 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 opened for.** w
32d70 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 riting (the flag
32d80 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b s parameter to [
32d90 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
32da0 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a n()] was zero),.
32db0 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e ** this function
32dc0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
32dd0 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a _READONLY]..**.*
32de0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
32df0 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 may only modify
32e00 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 the contents of
32e10 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a the BLOB; it is.
32e20 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 ** not possible
32e30 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 to increase the
32e40 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 size of a BLOB u
32e50 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a sing this API..*
32e60 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 * If offset iOff
32e70 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e set is less than
32e80 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 N bytes from th
32e90 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f e end of the BLO
32ea0 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 B,.** [SQLITE_ER
32eb0 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ROR] is returned
32ec0 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 and no data is
32ed0 77 72 69 74 74 65 6e 2e 20 20 49 66 20 4e 20 69 written. If N i
32ee0 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a s.** less than z
32ef0 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f ero [SQLITE_ERRO
32f00 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 R] is returned a
32f10 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 nd no data is wr
32f20 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69 itten..** The si
32f30 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 28 ze of the BLOB (
32f40 61 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 and hence the ma
32f50 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e ximum value of N
32f60 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e +iOffset).** can
32f70 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 be determined u
32f80 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 sing the [sqlite
32f90 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 3_blob_bytes()]
32fa0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
32fb0 20 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77 An attempt to w
32fc0 72 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72 rite to an expir
32fd0 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d ed [BLOB handle]
32fe0 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a fails with an.*
32ff0 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 * error code of
33000 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20 [SQLITE_ABORT].
33010 20 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 42 Writes to the B
33020 4c 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72 65 LOB that occurre
33030 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 d.** before the
33040 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 [BLOB handle] ex
33050 70 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f pired are not ro
33060 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 lled back by the
33070 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f .** expiration o
33080 66 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 f the handle, th
33090 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 ough of course t
330a0 68 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67 hose changes mig
330b0 68 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 ht.** have been
330c0 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 overwritten by t
330d0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 he statement tha
330e0 74 20 65 78 70 69 72 65 64 20 74 68 65 20 42 4c t expired the BL
330f0 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 OB handle.** or
33100 62 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e by other indepen
33110 64 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e dent statements.
33120 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 .**.** On succes
33130 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 s, SQLITE_OK is
33140 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 returned..** Oth
33150 65 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 erwise, an [err
33160 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b or code] or an [
33170 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
33180 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ode] is returned
33190 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
331a0 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 tine only works
331b0 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c on a [BLOB handl
331c0 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 e] which has bee
331d0 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 n created.** by
331e0 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 a prior successf
331f0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ul call to [sqli
33200 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d te3_blob_open()]
33210 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e and which has n
33220 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 ot.** been close
33230 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c d by [sqlite3_bl
33240 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 ob_close()]. Pa
33250 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 ssing any other
33260 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f pointer in.** to
33270 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 this routine re
33280 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e sults in undefin
33290 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 ed and probably
332a0 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 undesirable beha
332b0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 vior..**.** See
332c0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 also: [sqlite3_b
332d0 6c 6f 62 5f 72 65 61 64 28 29 5d 2e 0a 2a 2a 0a lob_read()]..**.
332e0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
332f0 0a 2a 2a 20 5b 48 31 37 38 37 33 5d 20 5b 48 31 .** [H17873] [H1
33300 37 38 37 34 5d 20 5b 48 31 37 38 37 35 5d 20 5b 7874] [H17875] [
33310 48 31 37 38 37 36 5d 20 5b 48 31 37 38 37 37 5d H17876] [H17877]
33320 20 5b 48 31 37 38 37 39 5d 20 5b 48 31 37 38 38 [H17879] [H1788
33330 32 5d 20 5b 48 31 37 38 38 35 5d 0a 2a 2a 20 5b 2] [H17885].** [
33340 48 31 37 38 38 38 5d 0a 2a 2f 0a 69 6e 74 20 73 H17888].*/.int s
33350 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 qlite3_blob_writ
33360 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a e(sqlite3_blob *
33370 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c , const void *z,
33380 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 int n, int iOff
33390 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 set);../*.** CAP
333a0 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46 I3REF: Virtual F
333b0 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 ile System Objec
333c0 74 73 20 7b 48 31 31 32 30 30 7d 20 3c 53 32 30 ts {H11200} <S20
333d0 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 100>.**.** A vir
333e0 74 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 tual filesystem
333f0 28 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c (VFS) is an [sql
33400 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
33410 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 .** that SQLite
33420 75 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74 uses to interact
33430 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64 .** with the und
33440 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e erlying operatin
33450 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 g system. Most
33460 53 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f SQLite builds co
33470 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e me with a.** sin
33480 67 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 gle default VFS
33490 74 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 that is appropri
334a0 61 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 ate for the host
334b0 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 computer..** Ne
334c0 77 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 w VFSes can be r
334d0 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 egistered and ex
334e0 69 73 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e isting VFSes can
334f0 20 62 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 be unregistered
33500 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 ..** The followi
33510 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 ng interfaces ar
33520 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a e provided..**.*
33530 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 * The sqlite3_vf
33540 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 s_find() interfa
33550 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
33560 6e 74 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 nter to a VFS gi
33570 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a ven its name..**
33580 20 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 Names are case
33590 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 4e 61 sensitive..** Na
335a0 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 mes are zero-ter
335b0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 minated UTF-8 st
335c0 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 rings..** If the
335d0 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 re is no match,
335e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
335f0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 s returned..** I
33600 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 f zVfsName is NU
33610 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 LL then the defa
33620 75 6c 74 20 56 46 53 20 69 73 20 72 65 74 75 72 ult VFS is retur
33630 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 ned..**.** New V
33640 46 53 65 73 20 61 72 65 20 72 65 67 69 73 74 65 FSes are registe
33650 72 65 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 red with sqlite3
33660 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e _vfs_register().
33670 0a 2a 2a 20 45 61 63 68 20 6e 65 77 20 56 46 53 .** Each new VFS
33680 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 becomes the def
33690 61 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 ault VFS if the
336a0 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 makeDflt flag is
336b0 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d set..** The sam
336c0 65 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 e VFS can be reg
336d0 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 istered multiple
336e0 20 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 times without i
336f0 6e 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b njury..** To mak
33700 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 e an existing VF
33710 53 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 S into the defau
33720 6c 74 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 lt VFS, register
33730 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 it again.** wit
33740 68 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 h the makeDflt f
33750 6c 61 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f lag set. If two
33760 20 64 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 different VFSes
33770 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d with the.** sam
33780 65 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 e name are regis
33790 74 65 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 tered, the behav
337a0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
337b0 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 . If a.** VFS i
337c0 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 s registered wit
337d0 68 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 h a name that is
337e0 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 NULL or an empt
337f0 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 y string,.** the
33800 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
33810 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
33820 2a 2a 20 55 6e 72 65 67 69 73 74 65 72 20 61 20 ** Unregister a
33830 56 46 53 20 77 69 74 68 20 74 68 65 20 73 71 6c VFS with the sql
33840 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 ite3_vfs_unregis
33850 74 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e ter() interface.
33860 0a 2a 2a 20 49 66 20 74 68 65 20 64 65 66 61 75 .** If the defau
33870 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69 lt VFS is unregi
33880 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 stered, another
33890 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73 VFS is chosen as
338a0 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e .** the default.
338b0 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72 The choice for
338c0 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20 the new VFS is
338d0 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a arbitrary..**.**
338e0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
338f0 2a 20 5b 48 31 31 32 30 33 5d 20 5b 48 31 31 32 * [H11203] [H112
33900 30 36 5d 20 5b 48 31 31 32 30 39 5d 20 5b 48 31 06] [H11209] [H1
33910 31 32 31 32 5d 20 5b 48 31 31 32 31 35 5d 20 5b 1212] [H11215] [
33920 48 31 31 32 31 38 5d 0a 2a 2f 0a 73 71 6c 69 74 H11218].*/.sqlit
33930 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f e3_vfs *sqlite3_
33940 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 vfs_find(const c
33950 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a har *zVfsName);.
33960 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f int sqlite3_vfs_
33970 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 register(sqlite3
33980 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 _vfs*, int makeD
33990 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 flt);.int sqlite
339a0 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 3_vfs_unregister
339b0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a (sqlite3_vfs*);.
339c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
339d0 20 4d 75 74 65 78 65 73 20 7b 48 31 37 30 30 30 Mutexes {H17000
339e0 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a } <S20000>.**.**
339f0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
33a00 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 uses these rout
33a10 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a ines for thread.
33a20 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 ** synchronizati
33a30 6f 6e 2e 20 54 68 6f 75 67 68 20 74 68 65 79 20 on. Though they
33a40 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 are intended for
33a50 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 internal.** use
33a60 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 by SQLite, code
33a70 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 that links agai
33a80 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a nst SQLite is.**
33a90 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73 permitted to us
33aa0 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 e any of these r
33ab0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 outines..**.** T
33ac0 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 he SQLite source
33ad0 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d code contains m
33ae0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e ultiple implemen
33af0 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 tations.** of th
33b00 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e ese mutex routin
33b10 65 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69 es. An appropri
33b20 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ate implementati
33b30 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 on.** is selecte
33b40 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 d automatically
33b50 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e at compile-time.
33b60 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a The following.
33b70 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
33b80 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 ns are available
33b90 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 in the SQLite c
33ba0 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ore:.**.** <ul>.
33bb0 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 ** <li> SQLITE
33bc0 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c _MUTEX_OS2.** <l
33bd0 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 i> SQLITE_MUTE
33be0 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 X_PTHREAD.** <li
33bf0 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 > SQLITE_MUTEX
33c00 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 _W32.** <li> S
33c10 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 QLITE_MUTEX_NOOP
33c20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
33c30 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 The SQLITE_MUTEX
33c40 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 _NOOP implementa
33c50 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66 tion is a set of
33c60 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 routines.** tha
33c70 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c t does no real l
33c80 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70 ocking and is ap
33c90 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 propriate for us
33ca0 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 e in.** a single
33cb0 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 -threaded applic
33cc0 61 74 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49 ation. The SQLI
33cd0 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a TE_MUTEX_OS2,.**
33ce0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 SQLITE_MUTEX_PT
33cf0 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 HREAD, and SQLIT
33d00 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c E_MUTEX_W32 impl
33d10 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 ementations.** a
33d20 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 re appropriate f
33d30 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 or use on OS/2,
33d40 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 Unix, and Window
33d50 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c 69 s..**.** If SQLi
33d60 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
33d70 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d ith the SQLITE_M
33d80 55 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 70 UTEX_APPDEF prep
33d90 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 rocessor.** macr
33da0 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 20 o defined (with
33db0 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f "-DSQLITE_MUTEX_
33dc0 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e APPDEF=1"), then
33dd0 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 no mutex.** imp
33de0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 lementation is i
33df0 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65 ncluded with the
33e00 20 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68 69 library. In thi
33e10 73 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 70 s case the.** ap
33e20 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 plication must s
33e30 75 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d upply a custom m
33e40 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 utex implementat
33e50 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a ion using the.**
33e60 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
33e70 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 MUTEX] option of
33e80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e the sqlite3_con
33e90 66 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a fig() function.*
33ea0 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 * before calling
33eb0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
33ec0 69 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 68 ize() or any oth
33ed0 65 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 er public sqlite
33ee0 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 3_.** function t
33ef0 68 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 hat calls sqlite
33f00 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 3_initialize()..
33f10 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 31 7d 20 54 **.** {H17011} T
33f20 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 he sqlite3_mutex
33f30 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 _alloc() routine
33f40 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 allocates a new
33f50 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 .** mutex and re
33f60 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
33f70 74 6f 20 69 74 2e 20 7b 48 31 37 30 31 32 7d 20 to it. {H17012}
33f80 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 If it returns NU
33f90 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73 LL.** that means
33fa0 20 74 68 61 74 20 61 20 6d 75 74 65 78 20 63 6f that a mutex co
33fb0 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 uld not be alloc
33fc0 61 74 65 64 2e 20 7b 48 31 37 30 31 33 7d 20 53 ated. {H17013} S
33fd0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e QLite.** will un
33fe0 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 wind its stack a
33ff0 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 nd return an err
34000 6f 72 2e 20 7b 48 31 37 30 31 34 7d 20 54 68 65 or. {H17014} The
34010 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
34020 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
34030 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 loc() is one of
34040 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f these integer co
34050 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c nstants:.**.** <
34060 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c ul>.** <li> SQL
34070 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a ITE_MUTEX_FAST.*
34080 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d * <li> SQLITE_M
34090 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a UTEX_RECURSIVE.*
340a0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d * <li> SQLITE_M
340b0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 UTEX_STATIC_MAST
340c0 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 ER.** <li> SQLI
340d0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
340e0 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c MEM.** <li> SQL
340f0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
34100 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 _MEM2.** <li> S
34110 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
34120 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 IC_PRNG.** <li>
34130 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
34140 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e ATIC_LRU.** <li>
34150 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 SQLITE_MUTEX_S
34160 54 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f TATIC_LRU2.** </
34170 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 ul>.**.** {H1701
34180 35 7d 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 5} The first two
34190 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 constants cause
341a0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 sqlite3_mutex_a
341b0 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 lloc() to create
341c0 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e .** a new mutex.
341d0 20 20 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 The new mutex
341e0 69 73 20 72 65 63 75 72 73 69 76 65 20 77 68 65 is recursive whe
341f0 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 n SQLITE_MUTEX_R
34200 45 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 ECURSIVE.** is u
34210 73 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 sed but not nece
34220 73 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 ssarily so when
34230 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 SQLITE_MUTEX_FAS
34240 54 20 69 73 20 75 73 65 64 2e 20 7b 45 4e 44 7d T is used. {END}
34250 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d .** The mutex im
34260 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 plementation doe
34270 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 s not need to ma
34280 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e ke a distinction
34290 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 .** between SQLI
342a0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 TE_MUTEX_RECURSI
342b0 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 VE and SQLITE_MU
342c0 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 64 TEX_FAST if it d
342d0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 oes.** not want
342e0 74 6f 2e 20 20 7b 48 31 37 30 31 36 7d 20 42 75 to. {H17016} Bu
342f0 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e t SQLite will on
34300 6c 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63 ly request a rec
34310 75 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a ursive mutex in.
34320 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69 ** cases where i
34330 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f t really needs o
34340 6e 65 2e 20 20 7b 45 4e 44 7d 20 49 66 20 61 20 ne. {END} If a
34350 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 faster non-recur
34360 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d sive mutex.** im
34370 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 plementation is
34380 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 available on the
34390 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 host platform,
343a0 74 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 the mutex subsys
343b0 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 tem.** might ret
343c0 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 urn such a mutex
343d0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 in response to
343e0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 SQLITE_MUTEX_FAS
343f0 54 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 37 T..**.** {H17017
34400 7d 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f } The other allo
34410 77 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 wed parameters t
34420 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f o sqlite3_mutex_
34430 61 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74 alloc() each ret
34440 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 urn.** a pointer
34450 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 to a static pre
34460 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 existing mutex.
34470 7b 45 4e 44 7d 20 20 46 6f 75 72 20 73 74 61 74 {END} Four stat
34480 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a ic mutexes are.*
34490 2a 20 75 73 65 64 20 62 79 20 74 68 65 20 63 75 * used by the cu
344a0 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 rrent version of
344b0 20 53 51 4c 69 74 65 2e 20 20 46 75 74 75 72 65 SQLite. Future
344c0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
344d0 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 ite.** may add a
344e0 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 dditional static
344f0 20 6d 75 74 65 78 65 73 2e 20 20 53 74 61 74 69 mutexes. Stati
34500 63 20 6d 75 74 65 78 65 73 20 61 72 65 20 66 6f c mutexes are fo
34510 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 r internal.** us
34520 65 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 e by SQLite only
34530 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 . Applications
34540 74 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 20 that use SQLite
34550 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a mutexes should.*
34560 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 * use only the d
34570 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 72 ynamic mutexes r
34580 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 49 54 eturned by SQLIT
34590 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f 72 0a E_MUTEX_FAST or.
345a0 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ** SQLITE_MUTEX_
345b0 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a RECURSIVE..**.**
345c0 20 7b 48 31 37 30 31 38 7d 20 4e 6f 74 65 20 74 {H17018} Note t
345d0 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 hat if one of th
345e0 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 e dynamic mutex
345f0 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 parameters (SQLI
34600 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a TE_MUTEX_FAST.**
34610 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 or SQLITE_MUTEX
34620 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75 _RECURSIVE) is u
34630 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 sed then sqlite3
34640 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a _mutex_alloc().*
34650 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 * returns a diff
34660 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 erent mutex on e
34670 76 65 72 79 20 63 61 6c 6c 2e 20 20 7b 48 31 37 very call. {H17
34680 30 33 34 7d 20 42 75 74 20 66 6f 72 20 74 68 65 034} But for the
34690 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 static.** mutex
346a0 20 74 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65 types, the same
346b0 20 6d 75 74 65 78 20 69 73 20 72 65 74 75 72 6e mutex is return
346c0 65 64 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c ed on every call
346d0 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 that has.** the
346e0 20 73 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 same type numbe
346f0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 39 r..**.** {H17019
34700 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 } The sqlite3_mu
34710 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 tex_free() routi
34720 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 ne deallocates a
34730 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 previously.** a
34740 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 llocated dynamic
34750 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 30 7d mutex. {H17020}
34760 20 53 51 4c 69 74 65 20 69 73 20 63 61 72 65 66 SQLite is caref
34770 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 ul to deallocate
34780 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 every.** dynami
34790 63 20 6d 75 74 65 78 20 74 68 61 74 20 69 74 20 c mutex that it
347a0 61 6c 6c 6f 63 61 74 65 73 2e 20 7b 41 31 37 30 allocates. {A170
347b0 32 31 7d 20 54 68 65 20 64 79 6e 61 6d 69 63 20 21} The dynamic
347c0 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 mutexes must not
347d0 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68 be in.** use wh
347e0 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 6c en they are deal
347f0 6c 6f 63 61 74 65 64 2e 20 7b 41 31 37 30 32 32 located. {A17022
34800 7d 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 } Attempting to
34810 64 65 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 deallocate a sta
34820 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 tic.** mutex res
34830 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 ults in undefine
34840 64 20 62 65 68 61 76 69 6f 72 2e 20 7b 48 31 37 d behavior. {H17
34850 30 32 33 7d 20 53 51 4c 69 74 65 20 6e 65 76 65 023} SQLite neve
34860 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a r deallocates.**
34870 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e a static mutex.
34880 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 {END}.**.** The
34890 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 sqlite3_mutex_e
348a0 6e 74 65 72 28 29 20 61 6e 64 20 73 71 6c 69 74 nter() and sqlit
348b0 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 72 e3_mutex_try() r
348c0 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 0a outines attempt.
348d0 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 ** to enter a mu
348e0 74 65 78 2e 20 7b 48 31 37 30 32 34 7d 20 49 66 tex. {H17024} If
348f0 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 another thread
34900 69 73 20 61 6c 72 65 61 64 79 20 77 69 74 68 69 is already withi
34910 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 n the mutex,.**
34920 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e sqlite3_mutex_en
34930 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b ter() will block
34940 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 and sqlite3_mut
34950 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72 65 ex_try() will re
34960 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 turn.** SQLITE_B
34970 55 53 59 2e 20 7b 48 31 37 30 32 35 7d 20 20 54 USY. {H17025} T
34980 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 he sqlite3_mutex
34990 5f 74 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 _try() interface
349a0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
349b0 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 _OK].** upon suc
349c0 63 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 cessful entry.
349d0 7b 48 31 37 30 32 36 7d 20 4d 75 74 65 78 65 73 {H17026} Mutexes
349e0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a created using.*
349f0 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 * SQLITE_MUTEX_R
34a00 45 43 55 52 53 49 56 45 20 63 61 6e 20 62 65 20 ECURSIVE can be
34a10 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 entered multiple
34a20 20 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 61 times by the sa
34a30 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20 7b 48 me thread..** {H
34a40 31 37 30 32 37 7d 20 49 6e 20 73 75 63 68 20 63 17027} In such c
34a50 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 ases the,.** mut
34a60 65 78 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 ex must be exite
34a70 64 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 d an equal numbe
34a80 72 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 r of times befor
34a90 65 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 e another thread
34aa0 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 20 20 .** can enter.
34ab0 7b 41 31 37 30 32 38 7d 20 49 66 20 74 68 65 20 {A17028} If the
34ac0 73 61 6d 65 20 74 68 72 65 61 64 20 74 72 69 65 same thread trie
34ad0 73 20 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f s to enter any o
34ae0 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 ther.** kind of
34af0 6d 75 74 65 78 20 6d 6f 72 65 20 74 68 61 6e 20 mutex more than
34b00 6f 6e 63 65 2c 20 74 68 65 20 62 65 68 61 76 69 once, the behavi
34b10 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e or is undefined.
34b20 0a 2a 2a 20 7b 48 31 37 30 32 39 7d 20 53 51 4c .** {H17029} SQL
34b30 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 ite will never e
34b40 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 xhibit.** such b
34b50 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f ehavior in its o
34b60 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 wn use of mutexe
34b70 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73 79 s..**.** Some sy
34b80 73 74 65 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 stems (for examp
34b90 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 20 le, Windows 95)
34ba0 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 do not support t
34bb0 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 he operation.**
34bc0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 implemented by s
34bd0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 qlite3_mutex_try
34be0 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 (). On those sy
34bf0 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d stems, sqlite3_m
34c00 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 utex_try().** wi
34c10 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e ll always return
34c20 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 7b SQLITE_BUSY. {
34c30 48 31 37 30 33 30 7d 20 54 68 65 20 53 51 4c 69 H17030} The SQLi
34c40 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 te core only eve
34c50 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 r uses.** sqlite
34c60 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 61 73 3_mutex_try() as
34c70 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e an optimization
34c80 20 73 6f 20 74 68 69 73 20 69 73 20 61 63 63 65 so this is acce
34c90 70 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e ptable behavior.
34ca0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 33 31 7d 20 .**.** {H17031}
34cb0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 The sqlite3_mute
34cc0 78 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e x_leave() routin
34cd0 65 20 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 e exits a mutex
34ce0 74 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 that was.** prev
34cf0 69 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 iously entered b
34d00 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 y the same threa
34d10 64 2e 20 20 7b 41 31 37 30 33 32 7d 20 54 68 65 d. {A17032} The
34d20 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 behavior.** is
34d30 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 undefined if the
34d40 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 mutex is not cu
34d50 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 rrently entered
34d60 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e by the.** callin
34d70 67 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e g thread or is n
34d80 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c ot currently all
34d90 6f 63 61 74 65 64 2e 20 20 7b 48 31 37 30 33 33 ocated. {H17033
34da0 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a } SQLite will.**
34db0 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65 72 never do either
34dc0 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 . {END}.**.** If
34dd0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f the argument to
34de0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 sqlite3_mutex_e
34df0 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 65 33 5f nter(), sqlite3_
34e00 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a mutex_try(), or.
34e10 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ** sqlite3_mutex
34e20 5f 6c 65 61 76 65 28 29 20 69 73 20 61 20 4e 55 _leave() is a NU
34e30 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e LL pointer, then
34e40 20 61 6c 6c 20 74 68 72 65 65 20 72 6f 75 74 69 all three routi
34e50 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 nes.** behave as
34e60 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 no-ops..**.** S
34e70 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
34e80 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 3_mutex_held()]
34e90 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 and [sqlite3_mut
34ea0 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a ex_notheld()]..*
34eb0 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 /.sqlite3_mutex
34ec0 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 *sqlite3_mutex_a
34ed0 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 lloc(int);.void
34ee0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 sqlite3_mutex_fr
34ef0 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ee(sqlite3_mutex
34f00 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 *);.void sqlite3
34f10 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c _mutex_enter(sql
34f20 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e ite3_mutex*);.in
34f30 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f t sqlite3_mutex_
34f40 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 try(sqlite3_mute
34f50 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 x*);.void sqlite
34f60 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71 3_mutex_leave(sq
34f70 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a lite3_mutex*);..
34f80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
34f90 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20 4f 62 Mutex Methods Ob
34fa0 6a 65 63 74 20 7b 48 31 37 31 32 30 7d 20 3c 53 ject {H17120} <S
34fb0 32 30 31 33 30 3e 0a 2a 2a 20 45 58 50 45 52 49 20130>.** EXPERI
34fc0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 MENTAL.**.** An
34fd0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
34fe0 20 73 74 72 75 63 74 75 72 65 20 64 65 66 69 6e structure defin
34ff0 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c es the low-level
35000 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 routines.** use
35010 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e d to allocate an
35020 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a d use mutexes..*
35030 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68 *.** Usually, th
35040 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 e default mutex
35050 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
35060 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69 provided by SQLi
35070 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63 te are.** suffic
35080 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68 ient, however th
35090 65 20 75 73 65 72 20 68 61 73 20 74 68 65 20 6f e user has the o
350a0 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74 ption of substit
350b0 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a uting a custom.*
350c0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
350d0 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64 for specialized
350e0 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 deployments or
350f0 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63 systems for whic
35100 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 h SQLite.** does
35110 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73 not provide a s
35120 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e uitable implemen
35130 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20 tation. In this
35140 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a case, the user.*
35150 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f * creates and po
35160 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61 pulates an insta
35170 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 nce of this stru
35180 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a cture to pass.**
35190 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to sqlite3_conf
351a0 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20 ig() along with
351b0 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 the [SQLITE_CONF
351c0 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e IG_MUTEX] option
351d0 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c ..** Additionall
351e0 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f y, an instance o
351f0 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 f this structure
35200 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 can be used as
35210 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72 an.** output var
35220 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79 iable when query
35230 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20 66 ing the system f
35240 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d or the current m
35250 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e utex.** implemen
35260 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68 tation, using th
35270 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 e [SQLITE_CONFIG
35280 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f _GETMUTEX] optio
35290 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 n..**.** The xMu
352a0 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 64 texInit method d
352b0 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 efined by this s
352c0 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f tructure is invo
352d0 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f ked as.** part o
352e0 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61 6c f system initial
352f0 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20 73 ization by the s
35300 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
35310 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a e() function..**
35320 20 7b 48 31 37 30 30 31 7d 20 54 68 65 20 78 4d {H17001} The xM
35330 75 74 65 78 49 6e 69 74 20 72 6f 75 74 69 6e 65 utexInit routine
35340 20 73 68 61 6c 6c 20 62 65 20 63 61 6c 6c 65 64 shall be called
35350 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 63 65 20 by SQLite once
35360 66 6f 72 20 65 61 63 68 0a 2a 2a 20 65 66 66 65 for each.** effe
35370 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 5b 73 ctive call to [s
35380 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
35390 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 e()]..**.** The
353a0 78 4d 75 74 65 78 45 6e 64 20 6d 65 74 68 6f 64 xMutexEnd method
353b0 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 defined by this
353c0 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e structure is in
353d0 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 voked as.** part
353e0 20 6f 66 20 73 79 73 74 65 6d 20 73 68 75 74 64 of system shutd
353f0 6f 77 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74 own by the sqlit
35400 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 66 75 e3_shutdown() fu
35410 6e 63 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 nction. The.** i
35420 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
35430 20 74 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 this method is
35440 65 78 70 65 63 74 65 64 20 74 6f 20 72 65 6c 65 expected to rele
35450 61 73 65 20 61 6c 6c 20 6f 75 74 73 74 61 6e 64 ase all outstand
35460 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 ing.** resources
35470 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 obtained by the
35480 20 6d 75 74 65 78 20 6d 65 74 68 6f 64 73 20 69 mutex methods i
35490 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 mplementation, e
354a0 73 70 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f specially.** tho
354b0 73 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 se obtained by t
354c0 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 he xMutexInit me
354d0 74 68 6f 64 2e 20 7b 48 31 37 30 30 33 7d 20 54 thod. {H17003} T
354e0 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 0a 2a he xMutexEnd().*
354f0 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c * interface shal
35500 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 l be invoked onc
35510 65 20 66 6f 72 20 65 61 63 68 20 63 61 6c 6c 20 e for each call
35520 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 to [sqlite3_shut
35530 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 down()]..**.** T
35540 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 73 65 76 he remaining sev
35550 65 6e 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e en methods defin
35560 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63 ed by this struc
35570 74 75 72 65 20 28 78 4d 75 74 65 78 41 6c 6c 6f ture (xMutexAllo
35580 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 46 72 65 65 c,.** xMutexFree
35590 2c 20 78 4d 75 74 65 78 45 6e 74 65 72 2c 20 78 , xMutexEnter, x
355a0 4d 75 74 65 78 54 72 79 2c 20 78 4d 75 74 65 78 MutexTry, xMutex
355b0 4c 65 61 76 65 2c 20 78 4d 75 74 65 78 48 65 6c Leave, xMutexHel
355c0 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 74 65 78 4e d and.** xMutexN
355d0 6f 74 68 65 6c 64 29 20 69 6d 70 6c 65 6d 65 6e otheld) implemen
355e0 74 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 t the following
355f0 69 6e 74 65 72 66 61 63 65 73 20 28 72 65 73 70 interfaces (resp
35600 65 63 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a ectively):.**.**
35610 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 <ul>.** <li>
35620 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
35630 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a alloc()] </li>.*
35640 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 * <li> [sqlit
35650 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 5d e3_mutex_free()]
35660 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e </li>.** <li>
35670 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 [sqlite3_mutex
35680 5f 65 6e 74 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a _enter()] </li>.
35690 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 ** <li> [sqli
356a0 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 5d te3_mutex_try()]
356b0 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e </li>.** <li>
356c0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 [sqlite3_mutex
356d0 5f 6c 65 61 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a _leave()] </li>.
356e0 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 ** <li> [sqli
356f0 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 te3_mutex_held()
35700 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 ] </li>.** <li
35710 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 > [sqlite3_mute
35720 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 20 3c 2f 6c x_notheld()] </l
35730 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a i>.** </ul>.**.*
35740 2a 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 * The only diffe
35750 72 65 6e 63 65 20 69 73 20 74 68 61 74 20 74 68 rence is that th
35760 65 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33 e public sqlite3
35770 5f 58 58 58 20 66 75 6e 63 74 69 6f 6e 73 20 65 _XXX functions e
35780 6e 75 6d 65 72 61 74 65 64 0a 2a 2a 20 61 62 6f numerated.** abo
35790 76 65 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f ve silently igno
357a0 72 65 20 61 6e 79 20 69 6e 76 6f 63 61 74 69 6f re any invocatio
357b0 6e 73 20 74 68 61 74 20 70 61 73 73 20 61 20 4e ns that pass a N
357c0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 ULL pointer inst
357d0 65 61 64 0a 2a 2a 20 6f 66 20 61 20 76 61 6c 69 ead.** of a vali
357e0 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 2e 20 d mutex handle.
357f0 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 The implementati
35800 6f 6e 73 20 6f 66 20 74 68 65 20 6d 65 74 68 6f ons of the metho
35810 64 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 ds defined.** by
35820 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 this structure
35830 61 72 65 20 6e 6f 74 20 72 65 71 75 69 72 65 64 are not required
35840 20 74 6f 20 68 61 6e 64 6c 65 20 74 68 69 73 20 to handle this
35850 63 61 73 65 2c 20 74 68 65 20 72 65 73 75 6c 74 case, the result
35860 73 0a 2a 2a 20 6f 66 20 70 61 73 73 69 6e 67 20 s.** of passing
35870 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
35880 6e 73 74 65 61 64 20 6f 66 20 61 20 76 61 6c 69 nstead of a vali
35890 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 20 61 d mutex handle a
358a0 72 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 re undefined.**
358b0 28 69 2e 65 2e 20 69 74 20 69 73 20 61 63 63 65 (i.e. it is acce
358c0 70 74 61 62 6c 65 20 74 6f 20 70 72 6f 76 69 64 ptable to provid
358d0 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e an implementat
358e0 69 6f 6e 20 74 68 61 74 20 73 65 67 66 61 75 6c ion that segfaul
358f0 74 73 20 69 66 0a 2a 2a 20 69 74 20 69 73 20 70 ts if.** it is p
35900 61 73 73 65 64 20 61 20 4e 55 4c 4c 20 70 6f 69 assed a NULL poi
35910 6e 74 65 72 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 nter)..*/.typede
35920 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
35930 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 73 _mutex_methods s
35940 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
35950 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c hods;.struct sql
35960 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
35970 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 ds {. int (*xMu
35980 74 65 78 49 6e 69 74 29 28 76 6f 69 64 29 3b 0a texInit)(void);.
35990 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 45 6e int (*xMutexEn
359a0 64 29 28 76 6f 69 64 29 3b 0a 20 20 73 71 6c 69 d)(void);. sqli
359b0 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d 75 te3_mutex *(*xMu
359c0 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29 3b 0a texAlloc)(int);.
359d0 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 46 void (*xMutexF
359e0 72 65 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 ree)(sqlite3_mut
359f0 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a ex *);. void (*
35a00 78 4d 75 74 65 78 45 6e 74 65 72 29 28 73 71 6c xMutexEnter)(sql
35a10 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 ite3_mutex *);.
35a20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 54 72 79 int (*xMutexTry
35a30 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 )(sqlite3_mutex
35a40 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 *);. void (*xMu
35a50 74 65 78 4c 65 61 76 65 29 28 73 71 6c 69 74 65 texLeave)(sqlite
35a60 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 3_mutex *);. in
35a70 74 20 28 2a 78 4d 75 74 65 78 48 65 6c 64 29 28 t (*xMutexHeld)(
35a80 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 sqlite3_mutex *)
35a90 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 ;. int (*xMutex
35aa0 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69 74 65 33 Notheld)(sqlite3
35ab0 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a 0a 2f _mutex *);.};../
35ac0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
35ad0 75 74 65 78 20 56 65 72 69 66 69 63 61 74 69 6f utex Verificatio
35ae0 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31 37 30 n Routines {H170
35af0 38 30 7d 20 3c 53 32 30 31 33 30 3e 20 3c 53 33 80} <S20130> <S3
35b00 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0800>.**.** The
35b10 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 sqlite3_mutex_he
35b20 6c 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 ld() and sqlite3
35b30 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 _mutex_notheld()
35b40 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 routines.** are
35b50 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
35b60 65 20 69 6e 73 69 64 65 20 61 73 73 65 72 74 28 e inside assert(
35b70 29 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 7b 48 ) statements. {H
35b80 31 37 30 38 31 7d 20 54 68 65 20 53 51 4c 69 74 17081} The SQLit
35b90 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20 e core.** never
35ba0 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 uses these routi
35bb0 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 69 64 nes except insid
35bc0 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 61 6e e an assert() an
35bd0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a d applications.*
35be0 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 74 6f * are advised to
35bf0 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64 follow the lead
35c00 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20 7b of the core. {
35c10 48 31 37 30 38 32 7d 20 54 68 65 20 63 6f 72 65 H17082} The core
35c20 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65 only.** provide
35c30 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e s implementation
35c40 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 s for these rout
35c50 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73 20 ines when it is
35c60 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 compiled.** with
35c70 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42 55 the SQLITE_DEBU
35c80 47 20 66 6c 61 67 2e 20 20 7b 41 31 37 30 38 37 G flag. {A17087
35c90 7d 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 78 } External mutex
35ca0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
35cb0 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 71 .** are only req
35cc0 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 uired to provide
35cd0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
35ce0 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 if SQLITE_DEBUG
35cf0 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e is.** defined an
35d00 64 20 69 66 20 4e 44 45 42 55 47 20 69 73 20 6e d if NDEBUG is n
35d10 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a ot defined..**.*
35d20 2a 20 7b 48 31 37 30 38 33 7d 20 54 68 65 73 65 * {H17083} These
35d30 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 routines should
35d40 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 return true if
35d50 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68 65 the mutex in the
35d60 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 ir argument.** i
35d70 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65 s held or not he
35d80 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 ld, respectively
35d90 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e 67 , by the calling
35da0 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b thread..**.** {
35db0 58 31 37 30 38 34 7d 20 54 68 65 20 69 6d 70 6c X17084} The impl
35dc0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f ementation is no
35dd0 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 t required to pr
35de0 6f 76 69 64 65 64 20 76 65 72 73 69 6f 6e 73 20 ovided versions
35df0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74 of these.** rout
35e00 69 6e 65 73 20 74 68 61 74 20 61 63 74 75 61 6c ines that actual
35e10 6c 79 20 77 6f 72 6b 2e 20 49 66 20 74 68 65 20 ly work. If the
35e20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 implementation d
35e30 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 oes not provide
35e40 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 69 working.** versi
35e50 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f 75 ons of these rou
35e60 74 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c 64 tines, it should
35e70 20 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69 64 at least provid
35e80 65 20 73 74 75 62 73 20 74 68 61 74 20 61 6c 77 e stubs that alw
35e90 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 72 ays.** return tr
35ea0 75 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20 64 ue so that one d
35eb0 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75 72 oes not get spur
35ec0 69 6f 75 73 20 61 73 73 65 72 74 69 6f 6e 20 66 ious assertion f
35ed0 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b ailures..**.** {
35ee0 48 31 37 30 38 35 7d 20 49 66 20 74 68 65 20 61 H17085} If the a
35ef0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
35f00 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 e3_mutex_held()
35f10 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
35f20 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f r then.** the ro
35f30 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 utine should ret
35f40 75 72 6e 20 31 2e 20 20 7b 45 4e 44 7d 20 54 68 urn 1. {END} Th
35f50 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 is seems counter
35f60 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65 -intuitive since
35f70 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20 .** clearly the
35f80 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 mutex cannot be
35f90 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20 held if it does
35fa0 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74 20 not exist. But
35fb0 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f the.** the reaso
35fc0 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65 73 n the mutex does
35fd0 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62 65 not exist is be
35fe0 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 64 20 cause the build
35ff0 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 is not.** using
36000 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20 77 65 mutexes. And we
36010 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 do not want the
36020 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74 61 69 assert() contai
36030 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c ning the.** call
36040 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 to sqlite3_mute
36050 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 69 6c x_held() to fail
36060 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 , so a non-zero
36070 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 return is.** the
36080 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 68 69 appropriate thi
36090 6e 67 20 74 6f 20 64 6f 2e 20 20 7b 48 31 37 30 ng to do. {H170
360a0 38 36 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 86} The sqlite3_
360b0 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 0a mutex_notheld().
360c0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f ** interface sho
360d0 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 uld also return
360e0 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61 20 4e 1 when given a N
360f0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a ULL pointer..*/.
36100 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 int sqlite3_mute
36110 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d x_held(sqlite3_m
36120 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 utex*);.int sqli
36130 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c te3_mutex_nothel
36140 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a d(sqlite3_mutex*
36150 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
36160 45 46 3a 20 4d 75 74 65 78 20 54 79 70 65 73 20 EF: Mutex Types
36170 7b 48 31 37 30 30 31 7d 20 3c 48 31 37 30 30 30 {H17001} <H17000
36180 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c >.**.** The [sql
36190 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 ite3_mutex_alloc
361a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 61 ()] interface ta
361b0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
361c0 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20 69 ument.** which i
361d0 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 s one of these i
361e0 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
361f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 74 20 ..**.** The set
36200 6f 66 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 of static mutexe
36210 73 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f s may change fro
36220 6d 20 6f 6e 65 20 53 51 4c 69 74 65 20 72 65 6c m one SQLite rel
36230 65 61 73 65 20 74 6f 20 74 68 65 0a 2a 2a 20 6e ease to the.** n
36240 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ext. Applicatio
36250 6e 73 20 74 68 61 74 20 6f 76 65 72 72 69 64 65 ns that override
36260 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 75 the built-in mu
36270 74 65 78 20 6c 6f 67 69 63 20 6d 75 73 74 20 62 tex logic must b
36280 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 74 6f e.** prepared to
36290 20 61 63 63 6f 6d 6d 6f 64 61 74 65 20 61 64 64 accommodate add
362a0 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d itional static m
362b0 75 74 65 78 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 utexes..*/.#defi
362c0 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ne SQLITE_MUTEX_
362d0 46 41 53 54 20 20 20 20 20 20 20 20 20 20 20 20 FAST
362e0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
362f0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 E_MUTEX_RECURSIV
36300 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 E 1.#defi
36310 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ne SQLITE_MUTEX_
36320 53 54 41 54 49 43 5f 4d 41 53 54 45 52 20 20 20 STATIC_MASTER
36330 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
36340 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d E_MUTEX_STATIC_M
36350 45 4d 20 20 20 20 20 20 20 33 20 20 2f 2a 20 73 EM 3 /* s
36360 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
36370 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
36380 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d E_MUTEX_STATIC_M
36390 45 4d 32 20 20 20 20 20 20 34 20 20 2f 2a 20 4e EM2 4 /* N
363a0 4f 54 20 55 53 45 44 20 2a 2f 0a 23 64 65 66 69 OT USED */.#defi
363b0 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ne SQLITE_MUTEX_
363c0 53 54 41 54 49 43 5f 4f 50 45 4e 20 20 20 20 20 STATIC_OPEN
363d0 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 42 74 4 /* sqlite3Bt
363e0 72 65 65 4f 70 65 6e 28 29 20 2a 2f 0a 23 64 65 reeOpen() */.#de
363f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 fine SQLITE_MUTE
36400 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 20 20 20 X_STATIC_PRNG
36410 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5 /* sqlite3
36420 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 _random() */.#de
36430 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 fine SQLITE_MUTE
36440 58 5f 53 54 41 54 49 43 5f 4c 52 55 20 20 20 20 X_STATIC_LRU
36450 20 20 20 36 20 20 2f 2a 20 6c 72 75 20 70 61 67 6 /* lru pag
36460 65 20 6c 69 73 74 20 2a 2f 0a 23 64 65 66 69 6e e list */.#defin
36470 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 e SQLITE_MUTEX_S
36480 54 41 54 49 43 5f 4c 52 55 32 20 20 20 20 20 20 TATIC_LRU2
36490 37 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 7 /* lru page l
364a0 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 ist */../*.** CA
364b0 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 65 PI3REF: Retrieve
364c0 20 74 68 65 20 6d 75 74 65 78 20 66 6f 72 20 61 the mutex for a
364d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
364e0 74 69 6f 6e 20 7b 48 31 37 30 30 32 7d 20 3c 48 tion {H17002} <H
364f0 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 17000>.**.** Thi
36500 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 s interface retu
36510 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 68 rns a pointer th
36520 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
36530 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 0a 2a ] object that .*
36540 2a 20 73 65 72 69 61 6c 69 7a 65 73 20 61 63 63 * serializes acc
36550 65 73 73 20 74 6f 20 74 68 65 20 5b 64 61 74 61 ess to the [data
36560 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
36570 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 61 72 given in the ar
36580 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 74 gument.** when t
36590 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f he [threading mo
365a0 64 65 5d 20 69 73 20 53 65 72 69 61 6c 69 7a 65 de] is Serialize
365b0 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 74 68 d..** If the [th
365c0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 reading mode] is
365d0 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 6f Single-thread o
365e0 72 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 74 r Multi-thread t
365f0 68 65 6e 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 hen this.** rout
36600 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 ine returns a NU
36610 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 LL pointer..*/.s
36620 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 qlite3_mutex *sq
36630 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 28 73 lite3_db_mutex(s
36640 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
36650 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 77 2d 4c CAPI3REF: Low-L
36660 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f 66 20 evel Control Of
36670 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 20 7b Database Files {
36680 48 31 31 33 30 30 7d 20 3c 53 33 30 38 30 30 3e H11300} <S30800>
36690 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 31 7d 20 .**.** {H11301}
366a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c The [sqlite3_fil
366b0 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 e_control()] int
366c0 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64 erface makes a d
366d0 69 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 irect call to th
366e0 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f e.** xFileContro
366f0 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65 l method for the
36700 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
36710 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 hods] object ass
36720 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 ociated.** with
36730 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 a particular dat
36740 61 62 61 73 65 20 69 64 65 6e 74 69 66 69 65 64 abase identified
36750 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 by the second a
36760 72 67 75 6d 65 6e 74 2e 20 7b 48 31 31 33 30 32 rgument. {H11302
36770 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 } The.** name of
36780 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
36790 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e the name assign
367a0 65 64 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 ed to the databa
367b0 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61 20 se by the.** <a
367c0 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61 63 href="lang_attac
367d0 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c 2f h.html">ATTACH</
367e0 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 a> SQL command t
367f0 68 61 74 20 6f 70 65 6e 65 64 20 74 68 65 0a 2a hat opened the.*
36800 2a 20 64 61 74 61 62 61 73 65 2e 20 7b 48 31 31 * database. {H11
36810 33 30 33 7d 20 54 6f 20 63 6f 6e 74 72 6f 6c 20 303} To control
36820 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 the main databas
36830 65 20 66 69 6c 65 2c 20 75 73 65 20 74 68 65 20 e file, use the
36840 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a 20 6f name "main".** o
36850 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 r a NULL pointer
36860 2e 20 7b 48 31 31 33 30 34 7d 20 54 68 65 20 74 . {H11304} The t
36870 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 hird and fourth
36880 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 parameters to th
36890 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 72 is routine.** ar
368a0 65 20 70 61 73 73 65 64 20 64 69 72 65 63 74 6c e passed directl
368b0 79 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 y through to the
368c0 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 second and thir
368d0 64 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 0a d parameters of.
368e0 2a 2a 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 ** the xFileCont
368f0 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 7b 48 31 rol method. {H1
36900 31 33 30 35 7d 20 54 68 65 20 72 65 74 75 72 6e 1305} The return
36910 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 78 46 value of the xF
36920 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 ileControl.** me
36930 74 68 6f 64 20 62 65 63 6f 6d 65 73 20 74 68 65 thod becomes the
36940 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
36950 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a this routine..*
36960 2a 0a 2a 2a 20 7b 48 31 31 33 30 36 7d 20 49 66 *.** {H11306} If
36970 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
36980 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d 65 29 20 meter (zDbName)
36990 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 74 does not match t
369a0 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a 2a he name of any.*
369b0 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 * open database
369c0 66 69 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49 54 file, then SQLIT
369d0 45 5f 45 52 52 4f 52 20 69 73 20 72 65 74 75 72 E_ERROR is retur
369e0 6e 65 64 2e 20 7b 48 31 31 33 30 37 7d 20 54 68 ned. {H11307} Th
369f0 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 is error.** code
36a00 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72 is not remember
36a10 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 ed and will not
36a20 62 65 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b be recalled by [
36a30 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
36a40 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 )].** or [sqlite
36a50 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20 7b 41 31 3_errmsg()]. {A1
36a60 31 33 30 38 7d 20 54 68 65 20 75 6e 64 65 72 6c 1308} The underl
36a70 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72 6f ying xFileContro
36a80 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a 2a l method might.*
36a90 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 53 51 * also return SQ
36aa0 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 7b 41 31 LITE_ERROR. {A1
36ab0 31 33 30 39 7d 20 54 68 65 72 65 20 69 73 20 6e 1309} There is n
36ac0 6f 20 77 61 79 20 74 6f 20 64 69 73 74 69 6e 67 o way to disting
36ad0 75 69 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 uish between.**
36ae0 61 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 an incorrect zDb
36af0 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 Name and an SQLI
36b00 54 45 5f 45 52 52 4f 52 20 72 65 74 75 72 6e 20 TE_ERROR return
36b10 66 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 from the underly
36b20 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 ing.** xFileCont
36b30 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b 45 4e 44 rol method. {END
36b40 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f }.**.** See also
36b50 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f : [SQLITE_FCNTL_
36b60 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69 6e LOCKSTATE].*/.in
36b70 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 t sqlite3_file_c
36b80 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a 2c ontrol(sqlite3*,
36b90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 const char *zDb
36ba0 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76 6f Name, int op, vo
36bb0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
36bc0 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 49 I3REF: Testing I
36bd0 6e 74 65 72 66 61 63 65 20 7b 48 31 31 34 30 30 nterface {H11400
36be0 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a } <S30800>.**.**
36bf0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 65 73 The sqlite3_tes
36c00 74 5f 63 6f 6e 74 72 6f 6c 28 29 20 69 6e 74 65 t_control() inte
36c10 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
36c20 20 72 65 61 64 20 6f 75 74 20 69 6e 74 65 72 6e read out intern
36c30 61 6c 0a 2a 2a 20 73 74 61 74 65 20 6f 66 20 53 al.** state of S
36c40 51 4c 69 74 65 20 61 6e 64 20 74 6f 20 69 6e 6a QLite and to inj
36c50 65 63 74 20 66 61 75 6c 74 73 20 69 6e 74 6f 20 ect faults into
36c60 53 51 4c 69 74 65 20 66 6f 72 20 74 65 73 74 69 SQLite for testi
36c70 6e 67 0a 2a 2a 20 70 75 72 70 6f 73 65 73 2e 20 ng.** purposes.
36c80 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
36c90 65 74 65 72 20 69 73 20 61 6e 20 6f 70 65 72 61 eter is an opera
36ca0 74 69 6f 6e 20 63 6f 64 65 20 74 68 61 74 20 64 tion code that d
36cb0 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 74 68 65 etermines.** the
36cc0 20 6e 75 6d 62 65 72 2c 20 6d 65 61 6e 69 6e 67 number, meaning
36cd0 2c 20 61 6e 64 20 6f 70 65 72 61 74 69 6f 6e 20 , and operation
36ce0 6f 66 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e of all subsequen
36cf0 74 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a t parameters..**
36d00 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
36d10 63 65 20 69 73 20 6e 6f 74 20 66 6f 72 20 75 73 ce is not for us
36d20 65 20 62 79 20 61 70 70 6c 69 63 61 74 69 6f 6e e by application
36d30 73 2e 20 20 49 74 20 65 78 69 73 74 73 20 73 6f s. It exists so
36d40 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20 76 65 72 69 lely.** for veri
36d50 66 79 69 6e 67 20 74 68 65 20 63 6f 72 72 65 63 fying the correc
36d60 74 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 t operation of t
36d70 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
36d80 79 2e 20 20 44 65 70 65 6e 64 69 6e 67 0a 2a 2a y. Depending.**
36d90 20 6f 6e 20 68 6f 77 20 74 68 65 20 53 51 4c 69 on how the SQLi
36da0 74 65 20 6c 69 62 72 61 72 79 20 69 73 20 63 6f te library is co
36db0 6d 70 69 6c 65 64 2c 20 74 68 69 73 20 69 6e 74 mpiled, this int
36dc0 65 72 66 61 63 65 20 6d 69 67 68 74 20 6e 6f 74 erface might not
36dd0 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 exist..**.** Th
36de0 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 e details of the
36df0 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 73 operation codes
36e00 2c 20 74 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 , their meanings
36e10 2c 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 , the parameters
36e20 0a 2a 2a 20 74 68 65 79 20 74 61 6b 65 2c 20 61 .** they take, a
36e30 6e 64 20 77 68 61 74 20 74 68 65 79 20 64 6f 20 nd what they do
36e40 61 72 65 20 61 6c 6c 20 73 75 62 6a 65 63 74 20 are all subject
36e50 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
36e60 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20 55 6e 6c t notice..** Unl
36e70 69 6b 65 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 ike most of the
36e80 53 51 4c 69 74 65 20 41 50 49 2c 20 74 68 69 73 SQLite API, this
36e90 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 function is not
36ea0 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 0a 2a guaranteed to.*
36eb0 2a 20 6f 70 65 72 61 74 65 20 63 6f 6e 73 69 73 * operate consis
36ec0 74 65 6e 74 6c 79 20 66 72 6f 6d 20 6f 6e 65 20 tently from one
36ed0 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e release to the n
36ee0 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ext..*/.int sqli
36ef0 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c te3_test_control
36f00 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a (int op, ...);..
36f10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
36f20 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 Testing Interfac
36f30 65 20 4f 70 65 72 61 74 69 6f 6e 20 43 6f 64 65 e Operation Code
36f40 73 20 7b 48 31 31 34 31 30 7d 20 3c 48 31 31 34 s {H11410} <H114
36f50 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 00>.**.** These
36f60 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 constants are th
36f70 65 20 76 61 6c 69 64 20 6f 70 65 72 61 74 69 6f e valid operatio
36f80 6e 20 63 6f 64 65 20 70 61 72 61 6d 65 74 65 72 n code parameter
36f90 73 20 75 73 65 64 0a 2a 2a 20 61 73 20 74 68 65 s used.** as the
36fa0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
36fb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 to [sqlite3_test
36fc0 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a 2a 0a _control()]..**.
36fd0 2a 2a 20 54 68 65 73 65 20 70 61 72 61 6d 65 74 ** These paramet
36fe0 65 72 73 20 61 6e 64 20 74 68 65 69 72 20 6d 65 ers and their me
36ff0 61 6e 69 6e 67 73 20 61 72 65 20 73 75 62 6a 65 anings are subje
37000 63 74 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 ct to change.**
37010 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 20 without notice.
37020 20 54 68 65 73 65 20 76 61 6c 75 65 73 20 61 72 These values ar
37030 65 20 66 6f 72 20 74 65 73 74 69 6e 67 20 70 75 e for testing pu
37040 72 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a 2a 20 rposes only..**
37050 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f Applications sho
37060 75 6c 64 20 6e 6f 74 20 75 73 65 20 61 6e 79 20 uld not use any
37070 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 of these paramet
37080 65 72 73 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 ers or the.** [s
37090 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 qlite3_test_cont
370a0 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 rol()] interface
370b0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
370c0 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e ITE_TESTCTRL_PRN
370d0 47 5f 53 41 56 45 20 20 20 20 20 20 20 20 20 20 G_SAVE
370e0 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 5.#define
370f0 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f SQLITE_TESTCTRL_
37100 50 52 4e 47 5f 52 45 53 54 4f 52 45 20 20 20 20 PRNG_RESTORE
37110 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6.#defi
37120 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 ne SQLITE_TESTCT
37130 52 4c 5f 50 52 4e 47 5f 52 45 53 45 54 20 20 20 RL_PRNG_RESET
37140 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 7.#d
37150 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 efine SQLITE_TES
37160 54 43 54 52 4c 5f 42 49 54 56 45 43 5f 54 45 53 TCTRL_BITVEC_TES
37170 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 38 T 8
37180 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
37190 54 45 53 54 43 54 52 4c 5f 46 41 55 4c 54 5f 49 TESTCTRL_FAULT_I
371a0 4e 53 54 41 4c 4c 20 20 20 20 20 20 20 20 20 20 NSTALL
371b0 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 9.#define SQLI
371c0 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 45 4e 49 TE_TESTCTRL_BENI
371d0 47 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f 4b 53 20 GN_MALLOC_HOOKS
371e0 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 10.#define S
371f0 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 QLITE_TESTCTRL_P
37200 45 4e 44 49 4e 47 5f 42 59 54 45 20 20 20 20 20 ENDING_BYTE
37210 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 11.#defin
37220 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 e SQLITE_TESTCTR
37230 4c 5f 41 53 53 45 52 54 20 20 20 20 20 20 20 20 L_ASSERT
37240 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 12.#de
37250 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 fine SQLITE_TEST
37260 43 54 52 4c 5f 41 4c 57 41 59 53 20 20 20 20 20 CTRL_ALWAYS
37270 20 20 20 20 20 20 20 20 20 20 20 20 20 31 33 0a 13.
37280 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
37290 20 53 51 4c 69 74 65 20 52 75 6e 74 69 6d 65 20 SQLite Runtime
372a0 53 74 61 74 75 73 20 7b 48 31 37 32 30 30 7d 20 Status {H17200}
372b0 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 <S60200>.** EXPE
372c0 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
372d0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
372e0 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 used to retriev
372f0 65 20 72 75 6e 74 69 6d 65 20 73 74 61 74 75 73 e runtime status
37300 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 information.**
37310 61 62 6f 75 74 20 74 68 65 20 70 72 65 66 6f 72 about the prefor
37320 6d 61 6e 63 65 20 6f 66 20 53 51 4c 69 74 65 2c mance of SQLite,
37330 20 61 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 and optionally
37340 74 6f 20 72 65 73 65 74 20 76 61 72 69 6f 75 73 to reset various
37350 0a 2a 2a 20 68 69 67 68 77 61 74 65 72 20 6d 61 .** highwater ma
37360 72 6b 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 rks. The first
37370 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 argument is an i
37380 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f 72 0a nteger code for.
37390 2a 2a 20 74 68 65 20 73 70 65 63 69 66 69 63 20 ** the specific
373a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 6d 65 61 parameter to mea
373b0 73 75 72 65 2e 20 20 52 65 63 6f 67 6e 69 7a 65 sure. Recognize
373c0 64 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 0a d integer codes.
373d0 2a 2a 20 61 72 65 20 6f 66 20 74 68 65 20 66 6f ** are of the fo
373e0 72 6d 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 55 rm [SQLITE_STATU
373f0 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 7c 20 S_MEMORY_USED |
37400 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 2e 2e SQLITE_STATUS_..
37410 2e 5d 2e 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 .]..** The curre
37420 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 nt value of the
37430 70 61 72 61 6d 65 74 65 72 20 69 73 20 72 65 74 parameter is ret
37440 75 72 6e 65 64 20 69 6e 74 6f 20 2a 70 43 75 72 urned into *pCur
37450 72 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 68 69 67 rent..** The hig
37460 68 65 73 74 20 72 65 63 6f 72 64 65 64 20 76 61 hest recorded va
37470 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 lue is returned
37480 69 6e 20 2a 70 48 69 67 68 77 61 74 65 72 2e 20 in *pHighwater.
37490 20 49 66 20 74 68 65 0a 2a 2a 20 72 65 73 65 74 If the.** reset
374a0 46 6c 61 67 20 69 73 20 74 72 75 65 2c 20 74 68 Flag is true, th
374b0 65 6e 20 74 68 65 20 68 69 67 68 65 73 74 20 72 en the highest r
374c0 65 63 6f 72 64 20 76 61 6c 75 65 20 69 73 20 72 ecord value is r
374d0 65 73 65 74 20 61 66 74 65 72 0a 2a 2a 20 2a 70 eset after.** *p
374e0 48 69 67 68 77 61 74 65 72 20 69 73 20 77 72 69 Highwater is wri
374f0 74 74 65 6e 2e 20 53 6f 6d 65 20 70 61 72 61 6d tten. Some param
37500 65 74 65 72 73 20 64 6f 20 6e 6f 74 20 72 65 63 eters do not rec
37510 6f 72 64 20 74 68 65 20 68 69 67 68 65 73 74 0a ord the highest.
37520 2a 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 ** value. For t
37530 68 6f 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a hose parameters.
37540 2a 2a 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 ** nothing is wr
37550 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48 69 67 itten into *pHig
37560 68 77 61 74 65 72 20 61 6e 64 20 74 68 65 20 72 hwater and the r
37570 65 73 65 74 46 6c 61 67 20 69 73 20 69 67 6e 6f esetFlag is igno
37580 72 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 20 70 61 red..** Other pa
37590 72 61 6d 65 74 65 72 73 20 72 65 63 6f 72 64 20 rameters record
375a0 6f 6e 6c 79 20 74 68 65 20 68 69 67 68 77 61 74 only the highwat
375b0 65 72 20 6d 61 72 6b 20 61 6e 64 20 6e 6f 74 20 er mark and not
375c0 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 76 the current.** v
375d0 61 6c 75 65 2e 20 20 46 6f 72 20 74 68 65 73 65 alue. For these
375e0 20 6c 61 74 74 65 72 20 70 61 72 61 6d 65 74 65 latter paramete
375f0 72 73 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 rs nothing is wr
37600 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72 itten into *pCur
37610 72 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 rent..**.** This
37620 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
37630 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 SQLITE_OK on su
37640 63 63 65 73 73 20 61 6e 64 20 61 20 6e 6f 6e 2d ccess and a non-
37650 7a 65 72 6f 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 zero.** [error c
37660 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e ode] on failure.
37670 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
37680 69 6e 65 20 69 73 20 74 68 72 65 61 64 73 61 66 ine is threadsaf
37690 65 20 62 75 74 20 69 73 20 6e 6f 74 20 61 74 6f e but is not ato
376a0 6d 69 63 2e 20 20 54 68 69 73 20 72 6f 75 74 69 mic. This routi
376b0 6e 65 20 63 61 6e 0a 2a 2a 20 63 61 6c 6c 65 64 ne can.** called
376c0 20 77 68 69 6c 65 20 6f 74 68 65 72 20 74 68 72 while other thr
376d0 65 61 64 73 20 61 72 65 20 72 75 6e 6e 69 6e 67 eads are running
376e0 20 74 68 65 20 73 61 6d 65 20 6f 72 20 64 69 66 the same or dif
376f0 66 65 72 65 6e 74 20 53 51 4c 69 74 65 0a 2a 2a ferent SQLite.**
37700 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f interfaces. Ho
37710 77 65 76 65 72 20 74 68 65 20 76 61 6c 75 65 73 wever the values
37720 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 43 returned in *pC
37730 75 72 72 65 6e 74 20 61 6e 64 0a 2a 2a 20 2a 70 urrent and.** *p
37740 48 69 67 68 77 61 74 65 72 20 72 65 66 6c 65 63 Highwater reflec
37750 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 t the status of
37760 53 51 4c 69 74 65 20 61 74 20 64 69 66 66 65 72 SQLite at differ
37770 65 6e 74 20 70 6f 69 6e 74 73 20 69 6e 20 74 69 ent points in ti
37780 6d 65 0a 2a 2a 20 61 6e 64 20 69 74 20 69 73 20 me.** and it is
37790 70 6f 73 73 69 62 6c 65 20 74 68 61 74 20 61 6e possible that an
377a0 6f 74 68 65 72 20 74 68 72 65 61 64 20 6d 69 67 other thread mig
377b0 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 70 61 ht change the pa
377c0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 20 62 65 rameter.** in be
377d0 74 77 65 65 6e 20 74 68 65 20 74 69 6d 65 73 20 tween the times
377e0 77 68 65 6e 20 2a 70 43 75 72 72 65 6e 74 20 61 when *pCurrent a
377f0 6e 64 20 2a 70 48 69 67 68 77 61 74 65 72 20 61 nd *pHighwater a
37800 72 65 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a re written..**.*
37810 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
37820 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 ite3_db_status()
37830 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 ].*/.SQLITE_EXPE
37840 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c RIMENTAL int sql
37850 69 74 65 33 5f 73 74 61 74 75 73 28 69 6e 74 20 ite3_status(int
37860 6f 70 2c 20 69 6e 74 20 2a 70 43 75 72 72 65 6e op, int *pCurren
37870 74 2c 20 69 6e 74 20 2a 70 48 69 67 68 77 61 74 t, int *pHighwat
37880 65 72 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 61 er, int resetFla
37890 67 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 g);.../*.** CAPI
378a0 33 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 3REF: Status Par
378b0 61 6d 65 74 65 72 73 20 7b 48 31 37 32 35 30 7d ameters {H17250}
378c0 20 3c 48 31 37 32 30 30 3e 0a 2a 2a 20 45 58 50 <H17200>.** EXP
378d0 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
378e0 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f These integer co
378f0 6e 73 74 61 6e 74 73 20 64 65 73 69 67 6e 61 74 nstants designat
37900 65 20 76 61 72 69 6f 75 73 20 72 75 6e 2d 74 69 e various run-ti
37910 6d 65 20 73 74 61 74 75 73 20 70 61 72 61 6d 65 me status parame
37920 74 65 72 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e ters.** that can
37930 20 62 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 be returned by
37940 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 [sqlite3_status(
37950 29 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a )]..**.** <dl>.*
37960 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 * <dt>SQLITE_STA
37970 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 3c TUS_MEMORY_USED<
37980 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
37990 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
379a0 65 20 63 75 72 72 65 6e 74 20 61 6d 6f 75 6e 74 e current amount
379b0 20 6f 66 20 6d 65 6d 6f 72 79 20 63 68 65 63 6b of memory check
379c0 65 64 20 6f 75 74 0a 2a 2a 20 75 73 69 6e 67 20 ed out.** using
379d0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
379e0 29 5d 2c 20 65 69 74 68 65 72 20 64 69 72 65 63 )], either direc
379f0 74 6c 79 20 6f 72 20 69 6e 64 69 72 65 63 74 6c tly or indirectl
37a00 79 2e 20 20 54 68 65 0a 2a 2a 20 66 69 67 75 72 y. The.** figur
37a10 65 20 69 6e 63 6c 75 64 65 73 20 63 61 6c 6c 73 e includes calls
37a20 20 6d 61 64 65 20 74 6f 20 5b 73 71 6c 69 74 65 made to [sqlite
37a30 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 79 20 74 3_malloc()] by t
37a40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a he application.*
37a50 2a 20 61 6e 64 20 69 6e 74 65 72 6e 61 6c 20 6d * and internal m
37a60 65 6d 6f 72 79 20 75 73 61 67 65 20 62 79 20 74 emory usage by t
37a70 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
37a80 79 2e 20 20 53 63 72 61 74 63 68 20 6d 65 6d 6f y. Scratch memo
37a90 72 79 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 6c 65 64 ry.** controlled
37aa0 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 by [SQLITE_CONF
37ab0 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 IG_SCRATCH] and
37ac0 61 75 78 69 6c 69 61 72 79 20 70 61 67 65 2d 63 auxiliary page-c
37ad0 61 63 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 63 ache.** memory c
37ae0 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51 ontrolled by [SQ
37af0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
37b00 43 41 43 48 45 5d 20 69 73 20 6e 6f 74 20 69 6e CACHE] is not in
37b10 63 6c 75 64 65 64 20 69 6e 0a 2a 2a 20 74 68 69 cluded in.** thi
37b20 73 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 s parameter. Th
37b30 65 20 61 6d 6f 75 6e 74 20 72 65 74 75 72 6e 65 e amount returne
37b40 64 20 69 73 20 74 68 65 20 73 75 6d 20 6f 66 20 d is the sum of
37b50 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a the allocation.*
37b60 2a 20 73 69 7a 65 73 20 61 73 20 72 65 70 6f 72 * sizes as repor
37b70 74 65 64 20 62 79 20 74 68 65 20 78 53 69 7a 65 ted by the xSize
37b80 20 6d 65 74 68 6f 64 20 69 6e 20 5b 73 71 6c 69 method in [sqli
37b90 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
37ba0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
37bb0 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d >SQLITE_STATUS_M
37bc0 41 4c 4c 4f 43 5f 53 49 5a 45 3c 2f 64 74 3e 0a ALLOC_SIZE</dt>.
37bd0 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 ** <dd>This para
37be0 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 meter records th
37bf0 65 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 e largest memory
37c00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 allocation requ
37c10 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f est.** handed to
37c20 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
37c30 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
37c40 72 65 61 6c 6c 6f 63 28 29 5d 20 28 6f 72 20 74 realloc()] (or t
37c50 68 65 69 72 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c heir.** internal
37c60 20 65 71 75 69 76 61 6c 65 6e 74 73 29 2e 20 20 equivalents).
37c70 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 Only the value r
37c80 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a eturned in the.*
37c90 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 * *pHighwater pa
37ca0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
37cb0 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 te3_status()] is
37cc0 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a of interest. .
37cd0 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 ** The value wri
37ce0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 tten into the *p
37cf0 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 Current paramete
37d00 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c r is undefined.<
37d10 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
37d20 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 QLITE_STATUS_PAG
37d30 45 43 41 43 48 45 5f 55 53 45 44 3c 2f 64 74 3e ECACHE_USED</dt>
37d40 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 .** <dd>This par
37d50 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 ameter returns t
37d60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 he number of pag
37d70 65 73 20 75 73 65 64 20 6f 75 74 20 6f 66 20 74 es used out of t
37d80 68 65 0a 2a 2a 20 5b 70 61 67 65 63 61 63 68 65 he.** [pagecache
37d90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
37da0 72 5d 20 74 68 61 74 20 77 61 73 20 63 6f 6e 66 r] that was conf
37db0 69 67 75 72 65 64 20 75 73 69 6e 67 20 0a 2a 2a igured using .**
37dc0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
37dd0 50 41 47 45 43 41 43 48 45 5d 2e 20 20 54 68 65 PAGECACHE]. The
37de0 0a 2a 2a 20 76 61 6c 75 65 20 72 65 74 75 72 6e .** value return
37df0 65 64 20 69 73 20 69 6e 20 70 61 67 65 73 2c 20 ed is in pages,
37e00 6e 6f 74 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 not in bytes.</d
37e10 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
37e20 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 ITE_STATUS_PAGEC
37e30 41 43 48 45 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 ACHE_OVERFLOW</d
37e40 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 t>.** <dd>This p
37e50 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 arameter returns
37e60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
37e70 79 74 65 73 20 6f 66 20 70 61 67 65 20 63 61 63 ytes of page cac
37e80 68 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e he.** allocation
37e90 20 77 68 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74 which could not
37ea0 20 62 65 20 73 74 61 74 69 73 66 69 65 64 20 62 be statisfied b
37eb0 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f y the [SQLITE_CO
37ec0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 0a NFIG_PAGECACHE].
37ed0 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 20 77 68 ** buffer and wh
37ee0 65 72 65 20 66 6f 72 63 65 64 20 74 6f 20 6f 76 ere forced to ov
37ef0 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74 erflow to [sqlit
37f00 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 e3_malloc()]. T
37f10 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 76 he.** returned v
37f20 61 6c 75 65 20 69 6e 63 6c 75 64 65 73 20 61 6c alue includes al
37f30 6c 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f locations that o
37f40 76 65 72 66 6c 6f 77 65 64 20 62 65 63 61 75 73 verflowed becaus
37f50 65 20 74 68 65 79 0a 2a 2a 20 77 68 65 72 65 20 e they.** where
37f60 74 6f 6f 20 6c 61 72 67 65 20 28 74 68 65 79 20 too large (they
37f70 77 65 72 65 20 6c 61 72 67 65 72 20 74 68 61 6e were larger than
37f80 20 74 68 65 20 22 73 7a 22 20 70 61 72 61 6d 65 the "sz" parame
37f90 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 ter to.** [SQLIT
37fa0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
37fb0 48 45 5d 29 20 61 6e 64 20 61 6c 6c 6f 63 61 74 HE]) and allocat
37fc0 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 66 6c ions that overfl
37fd0 6f 77 65 64 20 62 65 63 61 75 73 65 0a 2a 2a 20 owed because.**
37fe0 6e 6f 20 73 70 61 63 65 20 77 61 73 20 6c 65 66 no space was lef
37ff0 74 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 t in the page ca
38000 63 68 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 che.</dd>.**.**
38010 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 <dt>SQLITE_STATU
38020 53 5f 50 41 47 45 43 41 43 48 45 5f 53 49 5a 45 S_PAGECACHE_SIZE
38030 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
38040 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f s parameter reco
38050 72 64 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 rds the largest
38060 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
38070 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e n request.** han
38080 64 65 64 20 74 6f 20 5b 70 61 67 65 63 61 63 68 ded to [pagecach
38090 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
380a0 6f 72 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 or]. Only the v
380b0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e alue returned in
380c0 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 the.** *pHighwa
380d0 74 65 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f ter parameter to
380e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 [sqlite3_status
380f0 28 29 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65 ()] is of intere
38100 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c st. .** The val
38110 75 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 ue written into
38120 74 68 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61 the *pCurrent pa
38130 72 61 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66 rameter is undef
38140 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ined.</dd>.**.**
38150 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 <dt>SQLITE_STAT
38160 55 53 5f 53 43 52 41 54 43 48 5f 55 53 45 44 3c US_SCRATCH_USED<
38170 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
38180 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 parameter retur
38190 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
381a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 75 73 65 allocations use
381b0 64 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 d out of the.**
381c0 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 [scratch memory
381d0 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 allocator] confi
381e0 67 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b gured using.** [
381f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
38200 52 41 54 43 48 5d 2e 20 20 54 68 65 20 76 61 6c RATCH]. The val
38210 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 69 ue returned is i
38220 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 20 6e n allocations, n
38230 6f 74 0a 2a 2a 20 69 6e 20 62 79 74 65 73 2e 20 ot.** in bytes.
38240 20 53 69 6e 63 65 20 61 20 73 69 6e 67 6c 65 20 Since a single
38250 74 68 72 65 61 64 20 6d 61 79 20 6f 6e 6c 79 20 thread may only
38260 68 61 76 65 20 6f 6e 65 20 73 63 72 61 74 63 68 have one scratch
38270 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f allocation.** o
38280 75 74 73 74 61 6e 64 69 6e 67 20 61 74 20 74 69 utstanding at ti
38290 6d 65 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 me, this paramet
382a0 65 72 20 61 6c 73 6f 20 72 65 70 6f 72 74 73 20 er also reports
382b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 the number of th
382c0 72 65 61 64 73 0a 2a 2a 20 75 73 69 6e 67 20 73 reads.** using s
382d0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 74 cratch memory at
382e0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 3c the same time.<
382f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
38300 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 QLITE_STATUS_SCR
38310 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57 3c 2f 64 ATCH_OVERFLOW</d
38320 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 t>.** <dd>This p
38330 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 arameter returns
38340 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
38350 79 74 65 73 20 6f 66 20 73 63 72 61 74 63 68 20 ytes of scratch
38360 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
38370 74 69 6f 6e 20 77 68 69 63 68 20 63 6f 75 6c 64 tion which could
38380 20 6e 6f 74 20 62 65 20 73 74 61 74 69 73 66 69 not be statisfi
38390 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 ed by the [SQLIT
383a0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
383b0 5d 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 20 ].** buffer and
383c0 77 68 65 72 65 20 66 6f 72 63 65 64 20 74 6f 20 where forced to
383d0 6f 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 6c overflow to [sql
383e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 ite3_malloc()].
383f0 20 54 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 72 The values.** r
38400 65 74 75 72 6e 65 64 20 69 6e 63 6c 75 64 65 20 eturned include
38410 6f 76 65 72 66 6c 6f 77 73 20 62 65 63 61 75 73 overflows becaus
38420 65 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 e the requested
38430 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 74 allocation was t
38440 6f 6f 0a 2a 2a 20 6c 61 72 67 65 72 20 28 74 68 oo.** larger (th
38450 61 74 20 69 73 2c 20 62 65 63 61 75 73 65 20 74 at is, because t
38460 68 65 20 72 65 71 75 65 73 74 65 64 20 61 6c 6c he requested all
38470 6f 63 61 74 69 6f 6e 20 77 61 73 20 6c 61 72 67 ocation was larg
38480 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 22 er than the.** "
38490 73 7a 22 20 70 61 72 61 6d 65 74 65 72 20 74 6f sz" parameter to
384a0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
384b0 53 43 52 41 54 43 48 5d 29 20 61 6e 64 20 62 65 SCRATCH]) and be
384c0 63 61 75 73 65 20 6e 6f 20 73 63 72 61 74 63 68 cause no scratch
384d0 20 62 75 66 66 65 72 0a 2a 2a 20 73 6c 6f 74 73 buffer.** slots
384e0 20 77 65 72 65 20 61 76 61 69 6c 61 62 6c 65 2e were available.
384f0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .** </dd>.**.**
38500 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 <dt>SQLITE_STATU
38510 53 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 3c 2f S_SCRATCH_SIZE</
38520 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
38530 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 parameter record
38540 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 s the largest me
38550 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
38560 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 request.** hande
38570 64 20 74 6f 20 5b 73 63 72 61 74 63 68 20 6d 65 d to [scratch me
38580 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e mory allocator].
38590 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 Only the value
385a0 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 returned in the
385b0 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 .** *pHighwater
385c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
385d0 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 lite3_status()]
385e0 69 73 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 is of interest.
385f0 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77 .** The value w
38600 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 ritten into the
38610 2a 70 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65 *pCurrent parame
38620 74 65 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ter is undefined
38630 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
38640 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 >SQLITE_STATUS_P
38650 41 52 53 45 52 5f 53 54 41 43 4b 3c 2f 64 74 3e ARSER_STACK</dt>
38660 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 .** <dd>This par
38670 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 ameter records t
38680 68 65 20 64 65 65 70 65 73 74 20 70 61 72 73 65 he deepest parse
38690 72 20 73 74 61 63 6b 2e 20 20 49 74 20 69 73 20 r stack. It is
386a0 6f 6e 6c 79 0a 2a 2a 20 6d 65 61 6e 69 6e 67 66 only.** meaningf
386b0 75 6c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 ul if SQLite is
386c0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 59 compiled with [Y
386d0 59 54 52 41 43 4b 4d 41 58 53 54 41 43 4b 44 45 YTRACKMAXSTACKDE
386e0 50 54 48 5d 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f PTH].</dd>.** </
386f0 64 6c 3e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 73 74 dl>.**.** New st
38700 61 74 75 73 20 70 61 72 61 6d 65 74 65 72 73 20 atus parameters
38710 6d 61 79 20 62 65 20 61 64 64 65 64 20 66 72 6f may be added fro
38720 6d 20 74 69 6d 65 20 74 6f 20 74 69 6d 65 2e 0a m time to time..
38730 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
38740 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f E_STATUS_MEMORY_
38750 55 53 45 44 20 20 20 20 20 20 20 20 20 20 30 0a USED 0.
38760 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
38770 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f TATUS_PAGECACHE_
38780 55 53 45 44 20 20 20 20 20 20 20 31 0a 23 64 65 USED 1.#de
38790 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 fine SQLITE_STAT
387a0 55 53 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 45 US_PAGECACHE_OVE
387b0 52 46 4c 4f 57 20 20 20 32 0a 23 64 65 66 69 6e RFLOW 2.#defin
387c0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f e SQLITE_STATUS_
387d0 53 43 52 41 54 43 48 5f 55 53 45 44 20 20 20 20 SCRATCH_USED
387e0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
387f0 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 QLITE_STATUS_SCR
38800 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57 20 20 20 ATCH_OVERFLOW
38810 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
38820 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 TE_STATUS_MALLOC
38830 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 35 _SIZE 5
38840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
38850 53 54 41 54 55 53 5f 50 41 52 53 45 52 5f 53 54 STATUS_PARSER_ST
38860 41 43 4b 20 20 20 20 20 20 20 20 20 36 0a 23 64 ACK 6.#d
38870 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 efine SQLITE_STA
38880 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 53 49 TUS_PAGECACHE_SI
38890 5a 45 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 ZE 7.#defi
388a0 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 ne SQLITE_STATUS
388b0 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 20 20 20 _SCRATCH_SIZE
388c0 20 20 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 8../*.** C
388d0 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 API3REF: Databas
388e0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 53 74 61 e Connection Sta
388f0 74 75 73 20 7b 48 31 37 35 30 30 7d 20 3c 53 36 tus {H17500} <S6
38900 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 0200>.** EXPERIM
38910 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ENTAL.**.** This
38920 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 interface is us
38930 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 72 ed to retrieve r
38940 75 6e 74 69 6d 65 20 73 74 61 74 75 73 20 69 6e untime status in
38950 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 61 62 formation .** ab
38960 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 5b 64 61 out a single [da
38970 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
38980 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 n]. The first a
38990 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a rgument is the.*
389a0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
389b0 63 74 69 6f 6e 20 6f 62 6a 65 63 74 20 74 6f 20 ction object to
389c0 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e be interrogated.
389d0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 The second arg
389e0 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 74 68 65 20 ument.** is the
389f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 69 6e 74 parameter to int
38a00 65 72 72 6f 67 61 74 65 2e 20 20 43 75 72 72 65 errogate. Curre
38a10 6e 74 6c 79 2c 20 74 68 65 20 6f 6e 6c 79 20 61 ntly, the only a
38a20 6c 6c 6f 77 65 64 20 76 61 6c 75 65 0a 2a 2a 20 llowed value.**
38a30 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 70 for the second p
38a40 61 72 61 6d 65 74 65 72 20 69 73 20 5b 53 51 4c arameter is [SQL
38a50 49 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f ITE_DBSTATUS_LOO
38a60 4b 41 53 49 44 45 5f 55 53 45 44 5d 2e 0a 2a 2a KASIDE_USED]..**
38a70 20 41 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 Additional opti
38a80 6f 6e 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 ons will likely
38a90 61 70 70 65 61 72 20 69 6e 20 66 75 74 75 72 65 appear in future
38aa0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
38ab0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ite..**.** The c
38ac0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 urrent value of
38ad0 74 68 65 20 72 65 71 75 65 73 74 65 64 20 70 61 the requested pa
38ae0 72 61 6d 65 74 65 72 20 69 73 20 77 72 69 74 74 rameter is writt
38af0 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72 0a 2a 2a en into *pCur.**
38b00 20 61 6e 64 20 74 68 65 20 68 69 67 68 65 73 74 and the highest
38b10 20 69 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 76 instantaneous v
38b20 61 6c 75 65 20 69 73 20 77 72 69 74 74 65 6e 20 alue is written
38b30 69 6e 74 6f 20 2a 70 48 69 77 74 72 2e 20 20 49 into *pHiwtr. I
38b40 66 0a 2a 2a 20 74 68 65 20 72 65 73 65 74 46 6c f.** the resetFl
38b50 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 g is true, then
38b60 74 68 65 20 68 69 67 68 65 73 74 20 69 6e 73 74 the highest inst
38b70 61 6e 74 61 6e 65 6f 75 73 20 76 61 6c 75 65 20 antaneous value
38b80 69 73 0a 2a 2a 20 72 65 73 65 74 20 62 61 63 6b is.** reset back
38b90 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 63 75 72 down to the cur
38ba0 72 65 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a rent value..**.*
38bb0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
38bc0 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 61 ite3_status()] a
38bd0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 nd [sqlite3_stmt
38be0 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2f 0a 53 _status()]..*/.S
38bf0 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 QLITE_EXPERIMENT
38c00 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 AL int sqlite3_d
38c10 62 5f 73 74 61 74 75 73 28 73 71 6c 69 74 65 33 b_status(sqlite3
38c20 2a 2c 20 69 6e 74 20 6f 70 2c 20 69 6e 74 20 2a *, int op, int *
38c30 70 43 75 72 2c 20 69 6e 74 20 2a 70 48 69 77 74 pCur, int *pHiwt
38c40 72 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 67 29 r, int resetFlg)
38c50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
38c60 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d 65 F: Status Parame
38c70 74 65 72 73 20 66 6f 72 20 64 61 74 61 62 61 73 ters for databas
38c80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 7b 48 e connections {H
38c90 31 37 35 32 30 7d 20 3c 48 31 37 35 30 30 3e 0a 17520} <H17500>.
38ca0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
38cb0 2a 2a 0a 2a 2a 20 53 74 61 74 75 73 20 76 65 72 **.** Status ver
38cc0 62 73 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f bs for [sqlite3_
38cd0 64 62 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2a db_status()]..**
38ce0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e .** <dl>.** <dt>
38cf0 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f SQLITE_DBSTATUS_
38d00 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 3c 2f LOOKASIDE_USED</
38d10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
38d20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e parameter return
38d30 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
38d40 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
38d50 20 73 6c 6f 74 73 20 63 75 72 72 65 6e 74 6c 79 slots currently
38d60 0a 2a 2a 20 63 68 65 63 6b 65 64 20 6f 75 74 2e .** checked out.
38d70 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a </dd>.** </dl>.*
38d80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
38d90 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 _DBSTATUS_LOOKAS
38da0 49 44 45 5f 55 53 45 44 20 20 20 20 20 30 0a 0a IDE_USED 0..
38db0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
38dc0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
38dd0 65 6e 74 20 53 74 61 74 75 73 20 7b 48 31 37 35 ent Status {H175
38de0 35 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 50} <S60200>.**
38df0 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
38e00 2a 2a 20 45 61 63 68 20 70 72 65 70 61 72 65 64 ** Each prepared
38e10 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 69 6e 74 statement maint
38e20 61 69 6e 73 20 76 61 72 69 6f 75 73 0a 2a 2a 20 ains various.**
38e30 5b 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 [SQLITE_STMTSTAT
38e40 55 53 5f 53 4f 52 54 20 7c 20 63 6f 75 6e 74 65 US_SORT | counte
38e50 72 73 5d 20 74 68 61 74 20 6d 65 61 73 75 72 65 rs] that measure
38e60 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f the number.** o
38e70 66 20 74 69 6d 65 73 20 69 74 20 68 61 73 20 70 f times it has p
38e80 65 72 66 6f 72 6d 65 64 20 73 70 65 63 69 66 69 erformed specifi
38e90 63 20 6f 70 65 72 61 74 69 6f 6e 73 2e 20 20 54 c operations. T
38ea0 68 65 73 65 20 63 6f 75 6e 74 65 72 73 20 63 61 hese counters ca
38eb0 6e 0a 2a 2a 20 62 65 20 75 73 65 64 20 74 6f 20 n.** be used to
38ec0 6d 6f 6e 69 74 6f 72 20 74 68 65 20 70 65 72 66 monitor the perf
38ed0 6f 72 6d 61 6e 63 65 20 63 68 61 72 61 63 74 65 ormance characte
38ee0 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 70 ristics of the p
38ef0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 repared.** state
38f00 6d 65 6e 74 73 2e 20 20 46 6f 72 20 65 78 61 6d ments. For exam
38f10 70 6c 65 2c 20 69 66 20 74 68 65 20 6e 75 6d 62 ple, if the numb
38f20 65 72 20 6f 66 20 74 61 62 6c 65 20 73 74 65 70 er of table step
38f30 73 20 67 72 65 61 74 6c 79 20 65 78 63 65 65 64 s greatly exceed
38f40 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
38f50 6f 66 20 74 61 62 6c 65 20 73 65 61 72 63 68 65 of table searche
38f60 73 20 6f 72 20 72 65 73 75 6c 74 20 72 6f 77 73 s or result rows
38f70 2c 20 74 68 61 74 20 77 6f 75 6c 64 20 74 65 6e , that would ten
38f80 64 20 74 6f 20 69 6e 64 69 63 61 74 65 0a 2a 2a d to indicate.**
38f90 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 that the prepar
38fa0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 ed statement is
38fb0 75 73 69 6e 67 20 61 20 66 75 6c 6c 20 74 61 62 using a full tab
38fc0 6c 65 20 73 63 61 6e 20 72 61 74 68 65 72 20 74 le scan rather t
38fd0 68 61 6e 0a 2a 2a 20 61 6e 20 69 6e 64 65 78 2e han.** an index.
38fe0 20 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e .**.** This in
38ff0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
39000 74 6f 20 72 65 74 72 69 65 76 65 20 61 6e 64 20 to retrieve and
39010 72 65 73 65 74 20 63 6f 75 6e 74 65 72 20 76 61 reset counter va
39020 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 61 20 5b lues from.** a [
39030 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
39040 6e 74 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 nt]. The first
39050 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
39060 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
39070 6e 74 0a 2a 2a 20 6f 62 6a 65 63 74 20 74 6f 20 nt.** object to
39080 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e be interrogated.
39090 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 The second arg
390a0 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69 ument.** is an i
390b0 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f 72 20 nteger code for
390c0 61 20 73 70 65 63 69 66 69 63 20 5b 53 51 4c 49 a specific [SQLI
390d0 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f TE_STMTSTATUS_SO
390e0 52 54 20 7c 20 63 6f 75 6e 74 65 72 5d 0a 2a 2a RT | counter].**
390f0 20 74 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 to be interroga
39100 74 65 64 2e 20 0a 2a 2a 20 54 68 65 20 63 75 72 ted. .** The cur
39110 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 rent value of th
39120 65 20 72 65 71 75 65 73 74 65 64 20 63 6f 75 6e e requested coun
39130 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ter is returned.
39140 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 65 74 .** If the reset
39150 46 6c 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 Flg is true, the
39160 6e 20 74 68 65 20 63 6f 75 6e 74 65 72 20 69 73 n the counter is
39170 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 20 61 reset to zero a
39180 66 74 65 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 fter this.** int
39190 65 72 66 61 63 65 20 63 61 6c 6c 20 72 65 74 75 erface call retu
391a0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 rns..**.** See a
391b0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 73 74 lso: [sqlite3_st
391c0 61 74 75 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c atus()] and [sql
391d0 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 ite3_db_status()
391e0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 ]..*/.SQLITE_EXP
391f0 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 ERIMENTAL int sq
39200 6c 69 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 lite3_stmt_statu
39210 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c s(sqlite3_stmt*,
39220 20 69 6e 74 20 6f 70 2c 69 6e 74 20 72 65 73 65 int op,int rese
39230 74 46 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tFlg);../*.** CA
39240 50 49 33 52 45 46 3a 20 53 74 61 74 75 73 20 50 PI3REF: Status P
39250 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 70 72 arameters for pr
39260 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
39270 73 20 7b 48 31 37 35 37 30 7d 20 3c 48 31 37 35 s {H17570} <H175
39280 35 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 50>.** EXPERIMEN
39290 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TAL.**.** These
392a0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 preprocessor mac
392b0 72 6f 73 20 64 65 66 69 6e 65 20 69 6e 74 65 67 ros define integ
392c0 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 6e 61 er codes that na
392d0 6d 65 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 76 61 me counter.** va
392e0 6c 75 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 lues associated
392f0 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 with the [sqlite
39300 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 29 5d 3_stmt_status()]
39310 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 interface..** T
39320 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 he meanings of t
39330 68 65 20 76 61 72 69 6f 75 73 20 63 6f 75 6e 74 he various count
39340 65 72 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f ers are as follo
39350 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a ws:.**.** <dl>.*
39360 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 4d * <dt>SQLITE_STM
39370 54 53 54 41 54 55 53 5f 46 55 4c 4c 53 43 41 4e TSTATUS_FULLSCAN
39380 5f 53 54 45 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 _STEP</dt>.** <d
39390 64 3e 54 68 69 73 20 69 73 20 74 68 65 20 6e 75 d>This is the nu
393a0 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 mber of times th
393b0 61 74 20 53 51 4c 69 74 65 20 68 61 73 20 73 74 at SQLite has st
393c0 65 70 70 65 64 20 66 6f 72 77 61 72 64 20 69 6e epped forward in
393d0 0a 2a 2a 20 61 20 74 61 62 6c 65 20 61 73 20 70 .** a table as p
393e0 61 72 74 20 6f 66 20 61 20 66 75 6c 6c 20 74 61 art of a full ta
393f0 62 6c 65 20 73 63 61 6e 2e 20 20 4c 61 72 67 65 ble scan. Large
39400 20 6e 75 6d 62 65 72 73 20 66 6f 72 20 74 68 69 numbers for thi
39410 73 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 6d 61 79 s counter.** may
39420 20 69 6e 64 69 63 61 74 65 20 6f 70 70 6f 72 74 indicate opport
39430 75 6e 69 74 69 65 73 20 66 6f 72 20 70 65 72 66 unities for perf
39440 6f 72 6d 61 6e 63 65 20 69 6d 70 72 6f 76 65 6d ormance improvem
39450 65 6e 74 20 74 68 72 6f 75 67 68 20 0a 2a 2a 20 ent through .**
39460 63 61 72 65 66 75 6c 20 75 73 65 20 6f 66 20 69 careful use of i
39470 6e 64 69 63 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a ndices.</dd>.**.
39480 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 ** <dt>SQLITE_ST
39490 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 3c 2f 64 MTSTATUS_SORT</d
394a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 69 t>.** <dd>This i
394b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
394c0 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 sort operations
394d0 74 68 61 74 20 68 61 76 65 20 6f 63 63 75 72 72 that have occurr
394e0 65 64 2e 0a 2a 2a 20 41 20 6e 6f 6e 2d 7a 65 72 ed..** A non-zer
394f0 6f 20 76 61 6c 75 65 20 69 6e 20 74 68 69 73 20 o value in this
39500 63 6f 75 6e 74 65 72 20 6d 61 79 20 69 6e 64 69 counter may indi
39510 63 61 74 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e cate an opportun
39520 69 74 79 20 74 6f 0a 2a 2a 20 69 6d 70 72 6f 76 ity to.** improv
39530 65 6d 65 6e 74 20 70 65 72 66 6f 72 6d 61 6e 63 ement performanc
39540 65 20 74 68 72 6f 75 67 68 20 63 61 72 65 66 75 e through carefu
39550 6c 20 75 73 65 20 6f 66 20 69 6e 64 69 63 65 73 l use of indices
39560 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 .</dd>.**.** </d
39570 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
39580 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f LITE_STMTSTATUS_
39590 46 55 4c 4c 53 43 41 4e 5f 53 54 45 50 20 20 20 FULLSCAN_STEP
395a0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
395b0 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f TE_STMTSTATUS_SO
395c0 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 RT
395d0 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 2../*.** CAPI3RE
395e0 46 3a 20 43 75 73 74 6f 6d 20 50 61 67 65 20 43 F: Custom Page C
395f0 61 63 68 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 45 ache Object.** E
39600 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
39610 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 63 * The sqlite3_pc
39620 61 63 68 65 20 74 79 70 65 20 69 73 20 6f 70 61 ache type is opa
39630 71 75 65 2e 20 20 49 74 20 69 73 20 69 6d 70 6c que. It is impl
39640 65 6d 65 6e 74 65 64 20 62 79 0a 2a 2a 20 74 68 emented by.** th
39650 65 20 70 6c 75 67 67 61 62 6c 65 20 6d 6f 64 75 e pluggable modu
39660 6c 65 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 le. The SQLite
39670 63 6f 72 65 20 68 61 73 20 6e 6f 20 6b 6e 6f 77 core has no know
39680 6c 65 64 67 65 20 6f 66 0a 2a 2a 20 69 74 73 20 ledge of.** its
39690 73 69 7a 65 20 6f 72 20 69 6e 74 65 72 6e 61 6c size or internal
396a0 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 6e structure and n
396b0 65 76 65 72 20 64 65 61 6c 73 20 77 69 74 68 20 ever deals with
396c0 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 the.** sqlite3_p
396d0 63 61 63 68 65 20 6f 62 6a 65 63 74 20 65 78 63 cache object exc
396e0 65 70 74 20 62 79 20 68 6f 6c 64 69 6e 67 20 61 ept by holding a
396f0 6e 64 20 70 61 73 73 69 6e 67 20 70 6f 69 6e 74 nd passing point
39700 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 6f 62 ers.** to the ob
39710 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 ject..**.** See
39720 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
39730 6d 65 74 68 6f 64 73 5d 20 66 6f 72 20 61 64 64 methods] for add
39740 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
39750 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ion..*/.typedef
39760 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 70 struct sqlite3_p
39770 63 61 63 68 65 20 73 71 6c 69 74 65 33 5f 70 63 cache sqlite3_pc
39780 61 63 68 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ache;../*.** CAP
39790 49 33 52 45 46 3a 20 41 70 70 6c 69 63 61 74 69 I3REF: Applicati
397a0 6f 6e 20 44 65 66 69 6e 65 64 20 50 61 67 65 20 on Defined Page
397b0 43 61 63 68 65 2e 0a 2a 2a 20 45 58 50 45 52 49 Cache..** EXPERI
397c0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 MENTAL.**.** The
397d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
397e0 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ]([SQLITE_CONFIG
397f0 5f 50 43 41 43 48 45 5d 2c 20 2e 2e 2e 29 20 69 _PCACHE], ...) i
39800 6e 74 65 72 66 61 63 65 20 63 61 6e 0a 2a 2a 20 nterface can.**
39810 72 65 67 69 73 74 65 72 20 61 6e 20 61 6c 74 65 register an alte
39820 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 63 rnative page cac
39830 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
39840 6e 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 n by passing in
39850 61 6e 20 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an .** instance
39860 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 of the sqlite3_p
39870 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 20 73 74 cache_methods st
39880 72 75 63 74 75 72 65 2e 20 54 68 65 20 6d 61 6a ructure. The maj
39890 6f 72 69 74 79 20 6f 66 20 74 68 65 20 0a 2a 2a ority of the .**
398a0 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 65 heap memory use
398b0 64 20 62 79 20 73 71 6c 69 74 65 20 69 73 20 75 d by sqlite is u
398c0 73 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 sed by the page
398d0 63 61 63 68 65 20 74 6f 20 63 61 63 68 65 20 64 cache to cache d
398e0 61 74 61 20 72 65 61 64 20 0a 2a 2a 20 66 72 6f ata read .** fro
398f0 6d 2c 20 6f 72 20 72 65 61 64 79 20 74 6f 20 62 m, or ready to b
39900 65 20 77 72 69 74 74 65 6e 20 74 6f 2c 20 74 68 e written to, th
39910 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e e database file.
39920 20 42 79 20 69 6d 70 6c 65 6d 65 6e 74 69 6e 67 By implementing
39930 20 61 20 0a 2a 2a 20 63 75 73 74 6f 6d 20 70 61 a .** custom pa
39940 67 65 20 63 61 63 68 65 20 75 73 69 6e 67 20 74 ge cache using t
39950 68 69 73 20 41 50 49 2c 20 61 6e 20 61 70 70 6c his API, an appl
39960 69 63 61 74 69 6f 6e 20 63 61 6e 20 63 6f 6e 74 ication can cont
39970 72 6f 6c 20 6d 6f 72 65 20 0a 2a 2a 20 70 72 65 rol more .** pre
39980 63 69 73 65 6c 79 20 74 68 65 20 61 6d 6f 75 6e cisely the amoun
39990 74 20 6f 66 20 6d 65 6d 6f 72 79 20 63 6f 6e 73 t of memory cons
399a0 75 6d 65 64 20 62 79 20 73 71 6c 69 74 65 2c 20 umed by sqlite,
399b0 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 the way in which
399c0 20 0a 2a 2a 20 73 61 69 64 20 6d 65 6d 6f 72 79 .** said memory
399d0 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e is allocated an
399e0 64 20 72 65 6c 65 61 73 65 64 2c 20 61 6e 64 20 d released, and
399f0 74 68 65 20 70 6f 6c 69 63 69 65 73 20 75 73 65 the policies use
39a00 64 20 74 6f 20 0a 2a 2a 20 64 65 74 65 72 6d 69 d to .** determi
39a10 6e 65 20 65 78 61 63 74 6c 79 20 77 68 69 63 68 ne exactly which
39a20 20 70 61 72 74 73 20 6f 66 20 61 20 64 61 74 61 parts of a data
39a30 62 61 73 65 20 66 69 6c 65 20 61 72 65 20 63 61 base file are ca
39a40 63 68 65 64 20 61 6e 64 20 66 6f 72 20 0a 2a 2a ched and for .**
39a50 20 68 6f 77 20 6c 6f 6e 67 2e 0a 2a 2a 0a 2a 2a how long..**.**
39a60 20 54 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 The contents of
39a70 20 74 68 65 20 73 74 72 75 63 74 75 72 65 20 61 the structure a
39a80 72 65 20 63 6f 70 69 65 64 20 74 6f 20 61 6e 20 re copied to an
39a90 69 6e 74 65 72 6e 61 6c 20 62 75 66 66 65 72 20 internal buffer
39aa0 62 79 20 73 71 6c 69 74 65 0a 2a 2a 20 77 69 74 by sqlite.** wit
39ab0 68 69 6e 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 hin the call to
39ac0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d [sqlite3_config]
39ad0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 ..**.** The xIni
39ae0 74 28 29 20 6d 65 74 68 6f 64 20 69 73 20 63 61 t() method is ca
39af0 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 lled once for ea
39b00 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ch call to [sqli
39b10 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
39b20 5d 0a 2a 2a 20 28 75 73 75 61 6c 6c 79 20 6f 6e ].** (usually on
39b30 6c 79 20 6f 6e 63 65 20 64 75 72 69 6e 67 20 74 ly once during t
39b40 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 he lifetime of t
39b50 68 65 20 70 72 6f 63 65 73 73 29 2e 20 49 74 20 he process). It
39b60 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 20 63 is passed.** a c
39b70 6f 70 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 opy of the sqlit
39b80 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
39b90 73 2e 70 41 72 67 20 76 61 6c 75 65 2e 20 49 74 s.pArg value. It
39ba0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
39bb0 73 65 74 0a 2a 2a 20 75 70 20 67 6c 6f 62 61 6c set.** up global
39bc0 20 73 74 72 75 63 74 75 72 65 73 20 61 6e 64 20 structures and
39bd0 6d 75 74 65 78 65 73 20 72 65 71 75 69 72 65 64 mutexes required
39be0 20 62 79 20 74 68 65 20 63 75 73 74 6f 6d 20 70 by the custom p
39bf0 61 67 65 20 63 61 63 68 65 20 0a 2a 2a 20 69 6d age cache .** im
39c00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 54 68 plementation. Th
39c10 65 20 78 53 68 75 74 64 6f 77 6e 28 29 20 6d 65 e xShutdown() me
39c20 74 68 6f 64 20 69 73 20 63 61 6c 6c 65 64 20 66 thod is called f
39c30 72 6f 6d 20 77 69 74 68 69 6e 20 0a 2a 2a 20 5b rom within .** [
39c40 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
39c50 28 29 5d 2c 20 69 66 20 74 68 65 20 61 70 70 6c ()], if the appl
39c60 69 63 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 ication invokes
39c70 74 68 69 73 20 41 50 49 2e 20 49 74 20 63 61 6e this API. It can
39c80 20 62 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 63 be used.** to c
39c90 6c 65 61 6e 20 75 70 20 61 6e 79 20 6f 75 74 73 lean up any outs
39ca0 74 61 6e 64 69 6e 67 20 72 65 73 6f 75 72 63 65 tanding resource
39cb0 73 20 62 65 66 6f 72 65 20 70 72 6f 63 65 73 73 s before process
39cc0 20 73 68 75 74 64 6f 77 6e 2c 20 69 66 20 72 65 shutdown, if re
39cd0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 quired..**.** Th
39ce0 65 20 78 43 72 65 61 74 65 28 29 20 6d 65 74 68 e xCreate() meth
39cf0 6f 64 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f od is used to co
39d00 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 63 61 nstruct a new ca
39d10 63 68 65 20 69 6e 73 74 61 6e 63 65 2e 20 54 68 che instance. Th
39d20 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d e.** first param
39d30 65 74 65 72 2c 20 73 7a 50 61 67 65 2c 20 69 73 eter, szPage, is
39d40 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 the size in byt
39d50 65 73 20 6f 66 20 74 68 65 20 70 61 67 65 73 20 es of the pages
39d60 74 68 61 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 that must.** be
39d70 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65 allocated by the
39d80 20 63 61 63 68 65 2e 20 73 7a 50 61 67 65 20 77 cache. szPage w
39d90 69 6c 6c 20 6e 6f 74 20 62 65 20 61 20 70 6f 77 ill not be a pow
39da0 65 72 20 6f 66 20 74 77 6f 2e 20 54 68 65 0a 2a er of two. The.*
39db0 2a 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e * second argumen
39dc0 74 2c 20 62 50 75 72 67 65 61 62 6c 65 2c 20 69 t, bPurgeable, i
39dd0 73 20 74 72 75 65 20 69 66 20 74 68 65 20 63 61 s true if the ca
39de0 63 68 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 che being create
39df0 64 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 75 73 65 d will.** be use
39e00 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 d to cache datab
39e10 61 73 65 20 70 61 67 65 73 20 72 65 61 64 20 66 ase pages read f
39e20 72 6f 6d 20 61 20 66 69 6c 65 20 73 74 6f 72 65 rom a file store
39e30 64 20 6f 6e 20 64 69 73 6b 2c 20 6f 72 0a 2a 2a d on disk, or.**
39e40 20 66 61 6c 73 65 20 69 66 20 69 74 20 69 73 20 false if it is
39e50 75 73 65 64 20 66 6f 72 20 61 6e 20 69 6e 2d 6d used for an in-m
39e60 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2e 20 emory database.
39e70 54 68 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d The cache implem
39e80 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 entation.** does
39e90 20 6e 6f 74 20 68 61 76 65 20 74 6f 20 64 6f 20 not have to do
39ea0 61 6e 79 74 68 69 6e 67 20 73 70 65 63 69 61 6c anything special
39eb0 20 62 61 73 65 64 20 6f 6e 20 74 68 65 20 76 61 based on the va
39ec0 6c 75 65 20 6f 66 20 62 50 75 72 67 65 61 62 6c lue of bPurgeabl
39ed0 65 2c 0a 2a 2a 20 69 74 20 69 73 20 70 75 72 65 e,.** it is pure
39ee0 6c 79 20 61 64 76 69 73 6f 72 79 2e 20 0a 2a 2a ly advisory. .**
39ef0 0a 2a 2a 20 54 68 65 20 78 43 61 63 68 65 73 69 .** The xCachesi
39f00 7a 65 28 29 20 6d 65 74 68 6f 64 20 6d 61 79 20 ze() method may
39f10 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 be called at any
39f20 20 74 69 6d 65 20 62 79 20 53 51 4c 69 74 65 20 time by SQLite
39f30 74 6f 20 73 65 74 20 74 68 65 0a 2a 2a 20 73 75 to set the.** su
39f40 67 67 65 73 74 65 64 20 6d 61 78 69 6d 75 6d 20 ggested maximum
39f50 63 61 63 68 65 2d 73 69 7a 65 20 28 6e 75 6d 62 cache-size (numb
39f60 65 72 20 6f 66 20 70 61 67 65 73 20 73 74 6f 72 er of pages stor
39f70 65 64 20 62 79 29 20 74 68 65 20 63 61 63 68 65 ed by) the cache
39f80 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 70 61 73 .** instance pas
39f90 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 sed as the first
39fa0 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 69 73 20 argument. This
39fb0 69 73 20 74 68 65 20 76 61 6c 75 65 20 63 6f 6e is the value con
39fc0 66 69 67 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a figured using.**
39fd0 20 74 68 65 20 53 51 4c 69 74 65 20 22 5b 50 52 the SQLite "[PR
39fe0 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d AGMA cache_size]
39ff0 22 20 63 6f 6d 6d 61 6e 64 2e 20 41 73 20 77 69 " command. As wi
3a000 74 68 20 74 68 65 20 62 50 75 72 67 65 61 62 6c th the bPurgeabl
3a010 65 20 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 e parameter,.**
3a020 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 the implementati
3a030 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 on is not requir
3a040 65 64 20 74 6f 20 64 6f 20 61 6e 79 74 68 69 6e ed to do anythin
3a050 67 20 73 70 65 63 69 61 6c 20 77 69 74 68 20 74 g special with t
3a060 68 69 73 0a 2a 2a 20 76 61 6c 75 65 2c 20 69 74 his.** value, it
3a070 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c is advisory onl
3a080 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 50 61 y..**.** The xPa
3a090 67 65 63 6f 75 6e 74 28 29 20 6d 65 74 68 6f 64 gecount() method
3a0a0 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 should return t
3a0b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 he number of pag
3a0c0 65 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 es currently.**
3a0d0 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 61 stored in the ca
3a0e0 63 68 65 20 73 75 70 70 6c 69 65 64 20 61 73 20 che supplied as
3a0f0 61 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 an argument..**
3a100 0a 2a 2a 20 54 68 65 20 78 46 65 74 63 68 28 29 .** The xFetch()
3a110 20 6d 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 method is used
3a120 74 6f 20 66 65 74 63 68 20 61 20 70 61 67 65 20 to fetch a page
3a130 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 and return a poi
3a140 6e 74 65 72 20 74 6f 20 69 74 2e 20 0a 2a 2a 20 nter to it. .**
3a150 41 20 27 70 61 67 65 27 2c 20 69 6e 20 74 68 69 A 'page', in thi
3a160 73 20 63 6f 6e 74 65 78 74 2c 20 69 73 20 61 20 s context, is a
3a170 62 75 66 66 65 72 20 6f 66 20 73 7a 50 61 67 65 buffer of szPage
3a180 20 62 79 74 65 73 20 61 6c 69 67 6e 65 64 20 61 bytes aligned a
3a190 74 20 61 6e 0a 2a 2a 20 38 2d 62 79 74 65 20 62 t an.** 8-byte b
3a1a0 6f 75 6e 64 61 72 79 2e 20 54 68 65 20 70 61 67 oundary. The pag
3a1b0 65 20 74 6f 20 62 65 20 66 65 74 63 68 65 64 20 e to be fetched
3a1c0 69 73 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 is determined by
3a1d0 20 74 68 65 20 6b 65 79 2e 20 54 68 65 0a 2a 2a the key. The.**
3a1e0 20 6d 69 6d 69 6d 75 6d 20 6b 65 79 20 76 61 6c mimimum key val
3a1f0 75 65 20 69 73 20 31 2e 20 41 66 74 65 72 20 69 ue is 1. After i
3a200 74 20 68 61 73 20 62 65 65 6e 20 72 65 74 72 69 t has been retri
3a210 65 76 65 64 20 75 73 69 6e 67 20 78 46 65 74 63 eved using xFetc
3a220 68 2c 20 74 68 65 20 70 61 67 65 20 0a 2a 2a 20 h, the page .**
3a230 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f is considered to
3a240 20 62 65 20 70 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a be pinned..**.*
3a250 2a 20 49 66 20 74 68 65 20 72 65 71 75 65 73 74 * If the request
3a260 65 64 20 70 61 67 65 20 69 73 20 61 6c 72 65 61 ed page is alrea
3a270 64 79 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 dy in the page c
3a280 61 63 68 65 2c 20 74 68 65 6e 20 61 20 70 6f 69 ache, then a poi
3a290 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 nter to.** the c
3a2a0 61 63 68 65 64 20 62 75 66 66 65 72 20 73 68 6f ached buffer sho
3a2b0 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 20 uld be returned
3a2c0 77 69 74 68 20 69 74 73 20 63 6f 6e 74 65 6e 74 with its content
3a2d0 73 20 69 6e 74 61 63 74 2e 20 49 66 20 74 68 65 s intact. If the
3a2e0 0a 2a 2a 20 70 61 67 65 20 69 73 20 6e 6f 74 20 .** page is not
3a2f0 61 6c 72 65 61 64 79 20 69 6e 20 74 68 65 20 63 already in the c
3a300 61 63 68 65 2c 20 74 68 65 6e 20 74 68 65 20 65 ache, then the e
3a310 78 70 65 63 74 65 64 20 62 65 68 61 76 69 6f 75 xpected behaviou
3a320 72 20 6f 66 20 74 68 65 0a 2a 2a 20 63 61 63 68 r of the.** cach
3a330 65 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 20 e is determined
3a340 62 79 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 by the value of
3a350 74 68 65 20 63 72 65 61 74 65 46 6c 61 67 20 70 the createFlag p
3a360 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 0a arameter passed.
3a370 2a 2a 20 74 6f 20 78 46 65 74 63 68 2c 20 61 63 ** to xFetch, ac
3a380 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 66 cording to the f
3a390 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 3a 0a ollowing table:.
3a3a0 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 **.** <table bor
3a3b0 64 65 72 3d 31 20 77 69 64 74 68 3d 38 35 25 20 der=1 width=85%
3a3c0 61 6c 69 67 6e 3d 63 65 6e 74 65 72 3e 0a 2a 2a align=center>.**
3a3d0 20 20 20 3c 74 72 3e 3c 74 68 3e 63 72 65 61 74 <tr><th>creat
3a3e0 65 46 6c 61 67 3c 74 68 3e 45 78 70 65 63 74 65 eFlag<th>Expecte
3a3f0 64 20 42 65 68 61 76 69 6f 75 72 0a 2a 2a 20 20 d Behaviour.**
3a400 20 3c 74 72 3e 3c 74 64 3e 30 3c 74 64 3e 4e 55 <tr><td>0<td>NU
3a410 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 LL should be ret
3a420 75 72 6e 65 64 2e 20 4e 6f 20 6e 65 77 20 63 61 urned. No new ca
3a430 63 68 65 20 65 6e 74 72 79 20 69 73 20 63 72 65 che entry is cre
3a440 61 74 65 64 2e 0a 2a 2a 20 20 20 3c 74 72 3e 3c ated..** <tr><
3a450 74 64 3e 31 3c 74 64 3e 49 66 20 63 72 65 61 74 td>1<td>If creat
3a460 65 46 6c 61 67 20 69 73 20 73 65 74 20 74 6f 20 eFlag is set to
3a470 31 2c 20 74 68 69 73 20 69 6e 64 69 63 61 74 65 1, this indicate
3a480 73 20 74 68 61 74 20 0a 2a 2a 20 20 20 20 20 20 s that .**
3a490 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 SQLite
3a4a0 20 69 73 20 68 6f 6c 64 69 6e 67 20 70 69 6e 6e is holding pinn
3a4b0 65 64 20 70 61 67 65 73 20 74 68 61 74 20 63 61 ed pages that ca
3a4c0 6e 20 62 65 20 75 6e 70 69 6e 6e 65 64 0a 2a 2a n be unpinned.**
3a4d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3a4e0 62 79 20 77 72 69 74 69 6e 67 20 74 68 65 69 72 by writing their
3a4f0 20 63 6f 6e 74 65 6e 74 73 20 74 6f 20 74 68 65 contents to the
3a500 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 28 database file (
3a510 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 a.**
3a520 20 20 20 20 72 65 6c 61 74 69 76 65 6c 79 20 65 relatively e
3a530 78 70 65 6e 73 69 76 65 20 6f 70 65 72 61 74 69 xpensive operati
3a540 6f 6e 29 2e 20 49 6e 20 74 68 69 73 20 73 69 74 on). In this sit
3a550 75 61 74 69 6f 6e 20 74 68 65 0a 2a 2a 20 20 20 uation the.**
3a560 20 20 20 20 20 20 20 20 20 20 20 20 20 63 61 63 cac
3a570 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
3a580 6e 20 68 61 73 20 74 77 6f 20 63 68 6f 69 63 65 n has two choice
3a590 73 3a 20 69 74 20 63 61 6e 20 72 65 74 75 72 6e s: it can return
3a5a0 20 4e 55 4c 4c 2c 0a 2a 2a 20 20 20 20 20 20 20 NULL,.**
3a5b0 20 20 20 20 20 20 20 20 20 69 6e 20 77 68 69 63 in whic
3a5c0 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 h case SQLite wi
3a5d0 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 20 75 6e ll attempt to un
3a5e0 70 69 6e 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 pin one or more
3a5f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 .**
3a600 20 20 20 70 61 67 65 73 20 62 65 66 6f 72 65 20 pages before
3a610 72 65 2d 72 65 71 75 65 73 74 69 6e 67 20 74 68 re-requesting th
3a620 65 20 73 61 6d 65 20 70 61 67 65 2c 20 6f 72 20 e same page, or
3a630 69 74 20 63 61 6e 0a 2a 2a 20 20 20 20 20 20 20 it can.**
3a640 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 allocat
3a650 65 20 61 20 6e 65 77 20 70 61 67 65 20 61 6e 64 e a new page and
3a660 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 return a pointe
3a670 72 20 74 6f 20 69 74 2e 20 49 66 20 61 20 6e 65 r to it. If a ne
3a680 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 w.**
3a690 20 20 20 20 70 61 67 65 20 69 73 20 61 6c 6c 6f page is allo
3a6a0 63 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20 cated, then the
3a6b0 66 69 72 73 74 20 73 69 7a 65 6f 66 28 76 6f 69 first sizeof(voi
3a6c0 64 2a 29 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 d*) bytes of.**
3a6d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 i
3a6e0 74 20 28 61 74 20 6c 65 61 73 74 29 20 6d 75 73 t (at least) mus
3a6f0 74 20 62 65 20 7a 65 72 6f 65 64 20 62 65 66 6f t be zeroed befo
3a700 72 65 20 69 74 20 69 73 20 72 65 74 75 72 6e 65 re it is returne
3a710 64 2e 0a 2a 2a 20 20 20 3c 74 72 3e 3c 74 64 3e d..** <tr><td>
3a720 32 3c 74 64 3e 49 66 20 63 72 65 61 74 65 46 6c 2<td>If createFl
3a730 61 67 20 69 73 20 73 65 74 20 74 6f 20 32 2c 20 ag is set to 2,
3a740 74 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 6e then SQLite is n
3a750 6f 74 20 68 6f 6c 64 69 6e 67 20 61 6e 79 0a 2a ot holding any.*
3a760 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *
3a770 20 70 69 6e 6e 65 64 20 70 61 67 65 73 20 61 73 pinned pages as
3a780 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
3a790 65 20 73 70 65 63 69 66 69 63 20 63 61 63 68 65 e specific cache
3a7a0 20 70 61 73 73 65 64 0a 2a 2a 20 20 20 20 20 20 passed.**
3a7b0 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65 as the
3a7c0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
3a7d0 74 6f 20 78 46 65 74 63 68 28 29 20 74 68 61 74 to xFetch() that
3a7e0 20 63 61 6e 20 62 65 20 75 6e 70 69 6e 6e 65 64 can be unpinned
3a7f0 2e 20 54 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 . The.**
3a800 20 20 20 20 20 20 20 20 63 61 63 68 65 20 69 6d cache im
3a810 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f plementation sho
3a820 75 6c 64 20 61 74 74 65 6d 70 74 20 74 6f 20 61 uld attempt to a
3a830 6c 6c 6f 63 61 74 65 20 61 20 6e 65 77 0a 2a 2a llocate a new.**
3a840 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3a850 63 61 63 68 65 20 65 6e 74 72 79 20 61 6e 64 20 cache entry and
3a860 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 return a pointer
3a870 20 74 6f 20 69 74 2e 20 41 67 61 69 6e 2c 20 74 to it. Again, t
3a880 68 65 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 he first.**
3a890 20 20 20 20 20 20 20 20 20 20 20 73 69 7a 65 6f sizeo
3a8a0 66 28 76 6f 69 64 2a 29 20 62 79 74 65 73 20 6f f(void*) bytes o
3a8b0 66 20 74 68 65 20 70 61 67 65 20 73 68 6f 75 6c f the page shoul
3a8c0 64 20 62 65 20 7a 65 72 6f 65 64 20 62 65 66 6f d be zeroed befo
3a8d0 72 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 re .**
3a8e0 20 20 20 20 20 20 69 74 20 69 73 20 72 65 74 75 it is retu
3a8f0 72 6e 65 64 2e 20 49 66 20 74 68 65 20 78 46 65 rned. If the xFe
3a900 74 63 68 28 29 20 6d 65 74 68 6f 64 20 72 65 74 tch() method ret
3a910 75 72 6e 73 20 4e 55 4c 4c 20 77 68 65 6e 20 0a urns NULL when .
3a920 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 **
3a930 20 20 63 72 65 61 74 65 46 6c 61 67 3d 3d 32 2c createFlag==2,
3a940 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 SQLite assumes
3a950 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c that a memory al
3a960 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 20 20 20 location .**
3a970 20 20 20 20 20 20 20 20 20 20 20 20 66 61 69 6c fail
3a980 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 53 ed and returns S
3a990 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 74 6f 20 74 QLITE_NOMEM to t
3a9a0 68 65 20 75 73 65 72 2e 0a 2a 2a 20 3c 2f 74 61 he user..** </ta
3a9b0 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 78 55 6e 70 69 ble>.**.** xUnpi
3a9c0 6e 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 n() is called by
3a9d0 20 53 51 4c 69 74 65 20 77 69 74 68 20 61 20 70 SQLite with a p
3a9e0 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 75 72 72 ointer to a curr
3a9f0 65 6e 74 6c 79 20 70 69 6e 6e 65 64 20 70 61 67 ently pinned pag
3aa00 65 0a 2a 2a 20 61 73 20 69 74 73 20 73 65 63 6f e.** as its seco
3aa10 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 nd argument. If
3aa20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
3aa30 74 65 72 2c 20 64 69 73 63 61 72 64 2c 20 69 73 ter, discard, is
3aa40 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 non-zero,.** th
3aa50 65 6e 20 74 68 65 20 70 61 67 65 20 73 68 6f 75 en the page shou
3aa60 6c 64 20 62 65 20 65 76 69 63 74 65 64 20 66 72 ld be evicted fr
3aa70 6f 6d 20 74 68 65 20 63 61 63 68 65 2e 20 49 6e om the cache. In
3aa80 20 74 68 69 73 20 63 61 73 65 20 53 51 4c 69 74 this case SQLit
3aa90 65 20 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 e .** assumes th
3aaa0 61 74 20 74 68 65 20 6e 65 78 74 20 74 69 6d 65 at the next time
3aab0 20 74 68 65 20 70 61 67 65 20 69 73 20 72 65 74 the page is ret
3aac0 72 69 65 76 65 64 20 66 72 6f 6d 20 74 68 65 20 rieved from the
3aad0 63 61 63 68 65 20 75 73 69 6e 67 0a 2a 2a 20 74 cache using.** t
3aae0 68 65 20 78 46 65 74 63 68 28 29 20 6d 65 74 68 he xFetch() meth
3aaf0 6f 64 2c 20 69 74 20 77 69 6c 6c 20 62 65 20 7a od, it will be z
3ab00 65 72 6f 65 64 2e 20 49 66 20 74 68 65 20 64 69 eroed. If the di
3ab10 73 63 61 72 64 20 70 61 72 61 6d 65 74 65 72 20 scard parameter
3ab20 69 73 0a 2a 2a 20 7a 65 72 6f 2c 20 74 68 65 6e is.** zero, then
3ab30 20 74 68 65 20 70 61 67 65 20 69 73 20 63 6f 6e the page is con
3ab40 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 75 6e sidered to be un
3ab50 70 69 6e 6e 65 64 2e 20 54 68 65 20 63 61 63 68 pinned. The cach
3ab60 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
3ab70 0a 2a 2a 20 6d 61 79 20 63 68 6f 6f 73 65 20 74 .** may choose t
3ab80 6f 20 72 65 63 6c 61 69 6d 20 28 66 72 65 65 20 o reclaim (free
3ab90 6f 72 20 72 65 63 79 63 6c 65 29 20 75 6e 70 69 or recycle) unpi
3aba0 6e 6e 65 64 20 70 61 67 65 73 20 61 74 20 61 6e nned pages at an
3abb0 79 20 74 69 6d 65 2e 0a 2a 2a 20 53 51 4c 69 74 y time..** SQLit
3abc0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 6e e assumes that n
3abd0 65 78 74 20 74 69 6d 65 20 74 68 65 20 70 61 67 ext time the pag
3abe0 65 20 69 73 20 72 65 74 72 69 65 76 65 64 20 66 e is retrieved f
3abf0 72 6f 6d 20 74 68 65 20 63 61 63 68 65 0a 2a 2a rom the cache.**
3ac00 20 69 74 20 77 69 6c 6c 20 65 69 74 68 65 72 20 it will either
3ac10 62 65 20 7a 65 72 6f 65 64 2c 20 6f 72 20 63 6f be zeroed, or co
3ac20 6e 74 61 69 6e 20 74 68 65 20 73 61 6d 65 20 64 ntain the same d
3ac30 61 74 61 20 74 68 61 74 20 69 74 20 64 69 64 20 ata that it did
3ac40 77 68 65 6e 20 69 74 0a 2a 2a 20 77 61 73 20 75 when it.** was u
3ac50 6e 70 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 npinned..**.** T
3ac60 68 65 20 63 61 63 68 65 20 69 73 20 6e 6f 74 20 he cache is not
3ac70 72 65 71 75 69 72 65 64 20 74 6f 20 70 65 72 66 required to perf
3ac80 6f 72 6d 20 61 6e 79 20 72 65 66 65 72 65 6e 63 orm any referenc
3ac90 65 20 63 6f 75 6e 74 69 6e 67 2e 20 41 20 73 69 e counting. A si
3aca0 6e 67 6c 65 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f ngle .** call to
3acb0 20 78 55 6e 70 69 6e 28 29 20 75 6e 70 69 6e 73 xUnpin() unpins
3acc0 20 74 68 65 20 70 61 67 65 20 72 65 67 61 72 64 the page regard
3acd0 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 less of the numb
3ace0 65 72 20 6f 66 20 70 72 69 6f 72 20 63 61 6c 6c er of prior call
3acf0 73 20 0a 2a 2a 20 74 6f 20 78 46 65 74 63 68 28 s .** to xFetch(
3ad00 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 65 )..**.** The xRe
3ad10 6b 65 79 28 29 20 6d 65 74 68 6f 64 20 69 73 20 key() method is
3ad20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 used to change t
3ad30 68 65 20 6b 65 79 20 76 61 6c 75 65 20 61 73 73 he key value ass
3ad40 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
3ad50 0a 2a 2a 20 70 61 67 65 20 70 61 73 73 65 64 20 .** page passed
3ad60 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 as the second ar
3ad70 67 75 6d 65 6e 74 20 66 72 6f 6d 20 6f 6c 64 4b gument from oldK
3ad80 65 79 20 74 6f 20 6e 65 77 4b 65 79 2e 20 49 66 ey to newKey. If
3ad90 20 74 68 65 20 63 61 63 68 65 0a 2a 2a 20 70 72 the cache.** pr
3ada0 65 76 69 6f 75 73 6c 79 20 63 6f 6e 74 61 69 6e eviously contain
3adb0 73 20 61 6e 20 65 6e 74 72 79 20 61 73 73 6f 63 s an entry assoc
3adc0 69 61 74 65 64 20 77 69 74 68 20 6e 65 77 4b 65 iated with newKe
3add0 79 2c 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a y, it should be.
3ade0 2a 2a 20 64 69 73 63 61 72 64 65 64 2e 20 41 6e ** discarded. An
3adf0 79 20 70 72 69 6f 72 20 63 61 63 68 65 20 65 6e y prior cache en
3ae00 74 72 79 20 61 73 73 6f 63 69 61 74 65 64 20 77 try associated w
3ae10 69 74 68 20 6e 65 77 4b 65 79 20 69 73 20 67 75 ith newKey is gu
3ae20 61 72 61 6e 74 65 65 64 20 6e 6f 74 0a 2a 2a 20 aranteed not.**
3ae30 74 6f 20 62 65 20 70 69 6e 6e 65 64 2e 0a 2a 2a to be pinned..**
3ae40 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 .** When SQLite
3ae50 63 61 6c 6c 73 20 74 68 65 20 78 54 72 75 6e 63 calls the xTrunc
3ae60 61 74 65 28 29 20 6d 65 74 68 6f 64 2c 20 74 68 ate() method, th
3ae70 65 20 63 61 63 68 65 20 6d 75 73 74 20 64 69 73 e cache must dis
3ae80 63 61 72 64 20 61 6c 6c 0a 2a 2a 20 65 78 69 73 card all.** exis
3ae90 74 69 6e 67 20 63 61 63 68 65 20 65 6e 74 72 69 ting cache entri
3aea0 65 73 20 77 69 74 68 20 70 61 67 65 20 6e 75 6d es with page num
3aeb0 62 65 72 73 20 28 6b 65 79 73 29 20 67 72 65 61 bers (keys) grea
3aec0 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 ter than or equa
3aed0 6c 0a 2a 2a 20 74 6f 20 74 68 65 20 76 61 6c 75 l.** to the valu
3aee0 65 20 6f 66 20 74 68 65 20 69 4c 69 6d 69 74 20 e of the iLimit
3aef0 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 parameter passed
3af00 20 74 6f 20 78 54 72 75 6e 63 61 74 65 28 29 2e to xTruncate().
3af10 20 49 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 If any.** of th
3af20 65 73 65 20 70 61 67 65 73 20 61 72 65 20 70 69 ese pages are pi
3af30 6e 6e 65 64 2c 20 74 68 65 79 20 61 72 65 20 69 nned, they are i
3af40 6d 70 6c 69 63 69 74 6c 79 20 75 6e 70 69 6e 6e mplicitly unpinn
3af50 65 64 2c 20 6d 65 61 6e 69 6e 67 20 74 68 61 74 ed, meaning that
3af60 0a 2a 2a 20 74 68 65 79 20 63 61 6e 20 62 65 20 .** they can be
3af70 73 61 66 65 6c 79 20 64 69 73 63 61 72 64 65 64 safely discarded
3af80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 73 ..**.** The xDes
3af90 74 72 6f 79 28 29 20 6d 65 74 68 6f 64 20 69 73 troy() method is
3afa0 20 75 73 65 64 20 74 6f 20 64 65 6c 65 74 65 20 used to delete
3afb0 61 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 a cache allocate
3afc0 64 20 62 79 20 78 43 72 65 61 74 65 28 29 2e 0a d by xCreate()..
3afd0 2a 2a 20 41 6c 6c 20 72 65 73 6f 75 72 63 65 73 ** All resources
3afe0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
3aff0 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 the specified c
3b000 61 63 68 65 20 73 68 6f 75 6c 64 20 62 65 20 66 ache should be f
3b010 72 65 65 64 2e 20 41 66 74 65 72 0a 2a 2a 20 63 reed. After.** c
3b020 61 6c 6c 69 6e 67 20 74 68 65 20 78 44 65 73 74 alling the xDest
3b030 72 6f 79 28 29 20 6d 65 74 68 6f 64 2c 20 53 51 roy() method, SQ
3b040 4c 69 74 65 20 63 6f 6e 73 69 64 65 72 73 20 74 Lite considers t
3b050 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 he [sqlite3_pcac
3b060 68 65 2a 5d 0a 2a 2a 20 68 61 6e 64 6c 65 20 69 he*].** handle i
3b070 6e 76 61 6c 69 64 2c 20 61 6e 64 20 77 69 6c 6c nvalid, and will
3b080 20 6e 6f 74 20 75 73 65 20 69 74 20 77 69 74 68 not use it with
3b090 20 61 6e 79 20 6f 74 68 65 72 20 73 71 6c 69 74 any other sqlit
3b0a0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
3b0b0 73 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2e 0a s.** functions..
3b0c0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
3b0d0 74 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 t sqlite3_pcache
3b0e0 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 _methods sqlite3
3b0f0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3b _pcache_methods;
3b100 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
3b110 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 20 7b pcache_methods {
3b120 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 3b 0a 20 . void *pArg;.
3b130 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f int (*xInit)(vo
3b140 69 64 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 id*);. void (*x
3b150 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 Shutdown)(void*)
3b160 3b 0a 20 20 73 71 6c 69 74 65 33 5f 70 63 61 63 ;. sqlite3_pcac
3b170 68 65 20 2a 28 2a 78 43 72 65 61 74 65 29 28 69 he *(*xCreate)(i
3b180 6e 74 20 73 7a 50 61 67 65 2c 20 69 6e 74 20 62 nt szPage, int b
3b190 50 75 72 67 65 61 62 6c 65 29 3b 0a 20 20 76 6f Purgeable);. vo
3b1a0 69 64 20 28 2a 78 43 61 63 68 65 73 69 7a 65 29 id (*xCachesize)
3b1b0 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a (sqlite3_pcache*
3b1c0 2c 20 69 6e 74 20 6e 43 61 63 68 65 73 69 7a 65 , int nCachesize
3b1d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 50 61 67 65 );. int (*xPage
3b1e0 63 6f 75 6e 74 29 28 73 71 6c 69 74 65 33 5f 70 count)(sqlite3_p
3b1f0 63 61 63 68 65 2a 29 3b 0a 20 20 76 6f 69 64 20 cache*);. void
3b200 2a 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 *(*xFetch)(sqlit
3b210 65 33 5f 70 63 61 63 68 65 2a 2c 20 75 6e 73 69 e3_pcache*, unsi
3b220 67 6e 65 64 20 6b 65 79 2c 20 69 6e 74 20 63 72 gned key, int cr
3b230 65 61 74 65 46 6c 61 67 29 3b 0a 20 20 76 6f 69 eateFlag);. voi
3b240 64 20 28 2a 78 55 6e 70 69 6e 29 28 73 71 6c 69 d (*xUnpin)(sqli
3b250 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 76 6f 69 te3_pcache*, voi
3b260 64 2a 2c 20 69 6e 74 20 64 69 73 63 61 72 64 29 d*, int discard)
3b270 3b 0a 20 20 76 6f 69 64 20 28 2a 78 52 65 6b 65 ;. void (*xReke
3b280 79 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 y)(sqlite3_pcach
3b290 65 2a 2c 20 76 6f 69 64 2a 2c 20 75 6e 73 69 67 e*, void*, unsig
3b2a0 6e 65 64 20 6f 6c 64 4b 65 79 2c 20 75 6e 73 69 ned oldKey, unsi
3b2b0 67 6e 65 64 20 6e 65 77 4b 65 79 29 3b 0a 20 20 gned newKey);.
3b2c0 76 6f 69 64 20 28 2a 78 54 72 75 6e 63 61 74 65 void (*xTruncate
3b2d0 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 )(sqlite3_pcache
3b2e0 2a 2c 20 75 6e 73 69 67 6e 65 64 20 69 4c 69 6d *, unsigned iLim
3b2f0 69 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 it);. void (*xD
3b300 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f estroy)(sqlite3_
3b310 70 63 61 63 68 65 2a 29 3b 0a 7d 3b 0a 0a 2f 2a pcache*);.};../*
3b320 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e .** CAPI3REF: On
3b330 6c 69 6e 65 20 42 61 63 6b 75 70 20 4f 62 6a 65 line Backup Obje
3b340 63 74 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 ct.** EXPERIMENT
3b350 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c AL.**.** The sql
3b360 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 ite3_backup obje
3b370 63 74 20 72 65 63 6f 72 64 73 20 73 74 61 74 65 ct records state
3b380 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f information abo
3b390 75 74 20 61 6e 20 6f 6e 67 6f 69 6e 67 0a 2a 2a ut an ongoing.**
3b3a0 20 6f 6e 6c 69 6e 65 20 62 61 63 6b 75 70 20 6f online backup o
3b3b0 70 65 72 61 74 69 6f 6e 2e 20 20 54 68 65 20 73 peration. The s
3b3c0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 qlite3_backup ob
3b3d0 6a 65 63 74 20 69 73 20 63 72 65 61 74 65 64 20 ject is created
3b3e0 62 79 0a 2a 2a 20 61 20 63 61 6c 6c 20 74 6f 20 by.** a call to
3b3f0 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f [sqlite3_backup_
3b400 69 6e 69 74 28 29 5d 20 61 6e 64 20 69 73 20 64 init()] and is d
3b410 65 73 74 72 6f 79 65 64 20 62 79 20 61 20 63 61 estroyed by a ca
3b420 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
3b430 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 3_backup_finish(
3b440 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c )]..**.** See Al
3b450 73 6f 3a 20 5b 55 73 69 6e 67 20 74 68 65 20 53 so: [Using the S
3b460 51 4c 69 74 65 20 4f 6e 6c 69 6e 65 20 42 61 63 QLite Online Bac
3b470 6b 75 70 20 41 50 49 5d 0a 2a 2f 0a 74 79 70 65 kup API].*/.type
3b480 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
3b490 65 33 5f 62 61 63 6b 75 70 20 73 71 6c 69 74 65 e3_backup sqlite
3b4a0 33 5f 62 61 63 6b 75 70 3b 0a 0a 2f 2a 0a 2a 2a 3_backup;../*.**
3b4b0 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 6c 69 6e CAPI3REF: Onlin
3b4c0 65 20 42 61 63 6b 75 70 20 41 50 49 2e 0a 2a 2a e Backup API..**
3b4d0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
3b4e0 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 .** This API is
3b4f0 75 73 65 64 20 74 6f 20 6f 76 65 72 77 72 69 74 used to overwrit
3b500 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f e the contents o
3b510 66 20 6f 6e 65 20 64 61 74 61 62 61 73 65 20 77 f one database w
3b520 69 74 68 20 74 68 61 74 0a 2a 2a 20 6f 66 20 61 ith that.** of a
3b530 6e 6f 74 68 65 72 2e 20 49 74 20 69 73 20 75 73 nother. It is us
3b540 65 66 75 6c 20 65 69 74 68 65 72 20 66 6f 72 20 eful either for
3b550 63 72 65 61 74 69 6e 67 20 62 61 63 6b 75 70 73 creating backups
3b560 20 6f 66 20 64 61 74 61 62 61 73 65 73 20 6f 72 of databases or
3b570 0a 2a 2a 20 66 6f 72 20 63 6f 70 79 69 6e 67 20 .** for copying
3b580 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 in-memory databa
3b590 73 65 73 20 74 6f 20 6f 72 20 66 72 6f 6d 20 70 ses to or from p
3b5a0 65 72 73 69 73 74 65 6e 74 20 66 69 6c 65 73 2e ersistent files.
3b5b0 20 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f .**.** See Also
3b5c0 3a 20 5b 55 73 69 6e 67 20 74 68 65 20 53 51 4c : [Using the SQL
3b5d0 69 74 65 20 4f 6e 6c 69 6e 65 20 42 61 63 6b 75 ite Online Backu
3b5e0 70 20 41 50 49 5d 0a 2a 2a 0a 2a 2a 20 45 78 63 p API].**.** Exc
3b5f0 6c 75 73 69 76 65 20 61 63 63 65 73 73 20 69 73 lusive access is
3b600 20 72 65 71 75 69 72 65 64 20 74 6f 20 74 68 65 required to the
3b610 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 destination dat
3b620 61 62 61 73 65 20 66 6f 72 20 74 68 65 20 0a 2a abase for the .*
3b630 2a 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 * duration of th
3b640 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 48 6f 77 e operation. How
3b650 65 76 65 72 20 74 68 65 20 73 6f 75 72 63 65 20 ever the source
3b660 64 61 74 61 62 61 73 65 20 69 73 20 6f 6e 6c 79 database is only
3b670 0a 2a 2a 20 72 65 61 64 2d 6c 6f 63 6b 65 64 20 .** read-locked
3b680 77 68 69 6c 65 20 69 74 20 69 73 20 61 63 74 75 while it is actu
3b690 61 6c 6c 79 20 62 65 69 6e 67 20 72 65 61 64 2c ally being read,
3b6a0 20 69 74 20 69 73 20 6e 6f 74 20 6c 6f 63 6b 65 it is not locke
3b6b0 64 0a 2a 2a 20 63 6f 6e 74 69 6e 75 6f 75 73 6c d.** continuousl
3b6c0 79 20 66 6f 72 20 74 68 65 20 65 6e 74 69 72 65 y for the entire
3b6d0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 54 68 75 73 operation. Thus
3b6e0 2c 20 74 68 65 20 62 61 63 6b 75 70 20 6d 61 79 , the backup may
3b6f0 20 62 65 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 be.** performed
3b700 20 6f 6e 20 61 20 6c 69 76 65 20 64 61 74 61 62 on a live datab
3b710 61 73 65 20 77 69 74 68 6f 75 74 20 70 72 65 76 ase without prev
3b720 65 6e 74 69 6e 67 20 6f 74 68 65 72 20 75 73 65 enting other use
3b730 72 73 20 66 72 6f 6d 0a 2a 2a 20 77 72 69 74 69 rs from.** writi
3b740 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 ng to the databa
3b750 73 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 se for an extend
3b760 65 64 20 70 65 72 69 6f 64 20 6f 66 20 74 69 6d ed period of tim
3b770 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 6f 20 70 65 72 e..** .** To per
3b780 66 6f 72 6d 20 61 20 62 61 63 6b 75 70 20 6f 70 form a backup op
3b790 65 72 61 74 69 6f 6e 3a 20 0a 2a 2a 20 20 20 3c eration: .** <
3b7a0 6f 6c 3e 0a 2a 2a 20 20 20 20 20 3c 6c 69 3e 3c ol>.** <li><
3b7b0 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 b>sqlite3_backup
3b7c0 5f 69 6e 69 74 28 29 3c 2f 62 3e 20 69 73 20 63 _init()</b> is c
3b7d0 61 6c 6c 65 64 20 6f 6e 63 65 20 74 6f 20 69 6e alled once to in
3b7e0 69 74 69 61 6c 69 7a 65 20 74 68 65 0a 2a 2a 20 itialize the.**
3b7f0 20 20 20 20 20 20 20 20 62 61 63 6b 75 70 2c 20 backup,
3b800 0a 2a 2a 20 20 20 20 20 3c 6c 69 3e 3c 62 3e 73 .** <li><b>s
3b810 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3b820 65 70 28 29 3c 2f 62 3e 20 69 73 20 63 61 6c 6c ep()</b> is call
3b830 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 ed one or more t
3b840 69 6d 65 73 20 74 6f 20 74 72 61 6e 73 66 65 72 imes to transfer
3b850 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 74 68 65 .** the
3b860 20 64 61 74 61 20 62 65 74 77 65 65 6e 20 74 68 data between th
3b870 65 20 74 77 6f 20 64 61 74 61 62 61 73 65 73 2c e two databases,
3b880 20 61 6e 64 20 66 69 6e 61 6c 6c 79 0a 2a 2a 20 and finally.**
3b890 20 20 20 20 3c 6c 69 3e 3c 62 3e 73 71 6c 69 74 <li><b>sqlit
3b8a0 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 e3_backup_finish
3b8b0 28 29 3c 2f 62 3e 20 69 73 20 63 61 6c 6c 65 64 ()</b> is called
3b8c0 20 74 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c 20 to release all
3b8d0 72 65 73 6f 75 72 63 65 73 20 0a 2a 2a 20 20 20 resources .**
3b8e0 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 64 associated
3b8f0 20 77 69 74 68 20 74 68 65 20 62 61 63 6b 75 70 with the backup
3b900 20 6f 70 65 72 61 74 69 6f 6e 2e 20 0a 2a 2a 20 operation. .**
3b910 20 20 3c 2f 6f 6c 3e 0a 2a 2a 20 54 68 65 72 65 </ol>.** There
3b920 20 73 68 6f 75 6c 64 20 62 65 20 65 78 61 63 74 should be exact
3b930 6c 79 20 6f 6e 65 20 63 61 6c 6c 20 74 6f 20 73 ly one call to s
3b940 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 qlite3_backup_fi
3b950 6e 69 73 68 28 29 20 66 6f 72 20 65 61 63 68 0a nish() for each.
3b960 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 ** successful ca
3b970 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 ll to sqlite3_ba
3b980 63 6b 75 70 5f 69 6e 69 74 28 29 2e 0a 2a 2a 0a ckup_init()..**.
3b990 2a 2a 20 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 ** <b>sqlite3_ba
3b9a0 63 6b 75 70 5f 69 6e 69 74 28 29 3c 2f 62 3e 0a ckup_init()</b>.
3b9b0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
3b9c0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 70 61 two arguments pa
3b9d0 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 ssed to [sqlite3
3b9e0 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 5d 20 _backup_init()]
3b9f0 61 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65 are the database
3ba00 0a 2a 2a 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 .** handle assoc
3ba10 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 iated with the d
3ba20 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 estination datab
3ba30 61 73 65 20 61 6e 64 20 74 68 65 20 64 61 74 61 ase and the data
3ba40 62 61 73 65 20 6e 61 6d 65 20 0a 2a 2a 20 75 73 base name .** us
3ba50 65 64 20 74 6f 20 61 74 74 61 63 68 20 74 68 65 ed to attach the
3ba60 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 destination dat
3ba70 61 62 61 73 65 20 74 6f 20 74 68 65 20 68 61 6e abase to the han
3ba80 64 6c 65 2e 20 54 68 65 20 64 61 74 61 62 61 73 dle. The databas
3ba90 65 20 6e 61 6d 65 0a 2a 2a 20 69 73 20 22 6d 61 e name.** is "ma
3baa0 69 6e 22 20 66 6f 72 20 74 68 65 20 6d 61 69 6e in" for the main
3bab0 20 64 61 74 61 62 61 73 65 2c 20 22 74 65 6d 70 database, "temp
3bac0 22 20 66 6f 72 20 74 68 65 20 74 65 6d 70 6f 72 " for the tempor
3bad0 61 72 79 20 64 61 74 61 62 61 73 65 2c 20 6f 72 ary database, or
3bae0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 73 70 65 .** the name spe
3baf0 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f cified as part o
3bb00 66 20 74 68 65 20 5b 41 54 54 41 43 48 5d 20 73 f the [ATTACH] s
3bb10 74 61 74 65 6d 65 6e 74 20 69 66 20 74 68 65 20 tatement if the
3bb20 64 65 73 74 69 6e 61 74 69 6f 6e 20 69 73 0a 2a destination is.*
3bb30 2a 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 * an attached da
3bb40 74 61 62 61 73 65 2e 20 54 68 65 20 74 68 69 72 tabase. The thir
3bb50 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 d and fourth arg
3bb60 75 6d 65 6e 74 73 20 70 61 73 73 65 64 20 74 6f uments passed to
3bb70 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 .** sqlite3_bac
3bb80 6b 75 70 5f 69 6e 69 74 28 29 20 69 64 65 6e 74 kup_init() ident
3bb90 69 66 79 20 74 68 65 20 5b 64 61 74 61 62 61 73 ify the [databas
3bba0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a e connection].**
3bbb0 20 61 6e 64 20 64 61 74 61 62 61 73 65 20 6e 61 and database na
3bbc0 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 61 63 me used.** to ac
3bbd0 63 65 73 73 20 74 68 65 20 73 6f 75 72 63 65 20 cess the source
3bbe0 64 61 74 61 62 61 73 65 2e 20 54 68 65 20 76 61 database. The va
3bbf0 6c 75 65 73 20 70 61 73 73 65 64 20 66 6f 72 20 lues passed for
3bc00 74 68 65 20 73 6f 75 72 63 65 20 61 6e 64 20 0a the source and .
3bc10 2a 2a 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 5b ** destination [
3bc20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3bc30 69 6f 6e 5d 20 70 61 72 61 6d 65 74 65 72 73 20 ion] parameters
3bc40 6d 75 73 74 20 6e 6f 74 20 62 65 20 74 68 65 20 must not be the
3bc50 73 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 same..**.** If a
3bc60 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 n error occurs w
3bc70 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 62 61 ithin sqlite3_ba
3bc80 63 6b 75 70 5f 69 6e 69 74 28 29 2c 20 74 68 65 ckup_init(), the
3bc90 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e n NULL is return
3bca0 65 64 0a 2a 2a 20 61 6e 64 20 61 6e 20 65 72 72 ed.** and an err
3bcb0 6f 72 20 63 6f 64 65 20 61 6e 64 20 65 72 72 6f or code and erro
3bcc0 72 20 6d 65 73 73 61 67 65 20 77 72 69 74 74 65 r message writte
3bcd0 6e 20 69 6e 74 6f 20 74 68 65 20 5b 64 61 74 61 n into the [data
3bce0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
3bcf0 20 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 .** passed as t
3bd00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
3bd10 74 2e 20 54 68 65 79 20 6d 61 79 20 62 65 20 72 t. They may be r
3bd20 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 74 etrieved using t
3bd30 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 he.** [sqlite3_e
3bd40 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 rrcode()], [sqli
3bd50 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 te3_errmsg()], a
3bd60 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d nd [sqlite3_errm
3bd70 73 67 31 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e sg16()] function
3bd80 73 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c s..** Otherwise,
3bd90 20 69 66 20 73 75 63 63 65 73 73 66 75 6c 2c 20 if successful,
3bda0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
3bdb0 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d [sqlite3_backup]
3bdc0 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 72 65 object is.** re
3bdd0 74 75 72 6e 65 64 2e 20 54 68 69 73 20 70 6f 69 turned. This poi
3bde0 6e 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 nter may be used
3bdf0 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 74 65 with the sqlite
3be00 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 3_backup_step()
3be10 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 and.** sqlite3_b
3be20 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 20 66 ackup_finish() f
3be30 75 6e 63 74 69 6f 6e 73 20 74 6f 20 70 65 72 66 unctions to perf
3be40 6f 72 6d 20 74 68 65 20 73 70 65 63 69 66 69 65 orm the specifie
3be50 64 20 62 61 63 6b 75 70 20 0a 2a 2a 20 6f 70 65 d backup .** ope
3be60 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 62 ration..**.** <b
3be70 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f >sqlite3_backup_
3be80 73 74 65 70 28 29 3c 2f 62 3e 0a 2a 2a 0a 2a 2a step()</b>.**.**
3be90 20 46 75 6e 63 74 69 6f 6e 20 5b 73 71 6c 69 74 Function [sqlit
3bea0 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3beb0 5d 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 70 ] is used to cop
3bec0 79 20 75 70 20 74 6f 20 6e 50 61 67 65 20 70 61 y up to nPage pa
3bed0 67 65 73 20 62 65 74 77 65 65 6e 20 0a 2a 2a 20 ges between .**
3bee0 74 68 65 20 73 6f 75 72 63 65 20 61 6e 64 20 64 the source and d
3bef0 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 estination datab
3bf00 61 73 65 73 2c 20 77 68 65 72 65 20 6e 50 61 67 ases, where nPag
3bf10 65 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f e is the value o
3bf20 66 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64 f the .** second
3bf30 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 parameter passe
3bf40 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 d to sqlite3_bac
3bf50 6b 75 70 5f 73 74 65 70 28 29 2e 20 49 66 20 6e kup_step(). If n
3bf60 50 61 67 65 20 69 73 20 61 20 6e 65 67 61 74 69 Page is a negati
3bf70 76 65 0a 2a 2a 20 76 61 6c 75 65 2c 20 61 6c 6c ve.** value, all
3bf80 20 72 65 6d 61 69 6e 69 6e 67 20 73 6f 75 72 63 remaining sourc
3bf90 65 20 70 61 67 65 73 20 61 72 65 20 63 6f 70 69 e pages are copi
3bfa0 65 64 2e 20 49 66 20 74 68 65 20 72 65 71 75 69 ed. If the requi
3bfb0 72 65 64 20 70 61 67 65 73 20 61 72 65 20 0a 2a red pages are .*
3bfc0 2a 20 73 75 63 63 65 73 66 75 6c 6c 79 20 63 6f * succesfully co
3bfd0 70 69 65 64 2c 20 62 75 74 20 74 68 65 72 65 20 pied, but there
3bfe0 61 72 65 20 73 74 69 6c 6c 20 6d 6f 72 65 20 70 are still more p
3bff0 61 67 65 73 20 74 6f 20 63 6f 70 79 20 62 65 66 ages to copy bef
3c000 6f 72 65 20 74 68 65 20 0a 2a 2a 20 62 61 63 6b ore the .** back
3c010 75 70 20 69 73 20 63 6f 6d 70 6c 65 74 65 2c 20 up is complete,
3c020 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 it returns [SQLI
3c030 54 45 5f 4f 4b 5d 2e 20 49 66 20 6e 6f 20 65 72 TE_OK]. If no er
3c040 72 6f 72 20 6f 63 63 75 72 65 64 20 61 6e 64 20 ror occured and
3c050 74 68 65 72 65 20 0a 2a 2a 20 61 72 65 20 6e 6f there .** are no
3c060 20 6d 6f 72 65 20 70 61 67 65 73 20 74 6f 20 63 more pages to c
3c070 6f 70 79 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 opy, then [SQLIT
3c080 45 5f 44 4f 4e 45 5d 20 69 73 20 72 65 74 75 72 E_DONE] is retur
3c090 6e 65 64 2e 20 49 66 20 61 6e 20 65 72 72 6f 72 ned. If an error
3c0a0 20 0a 2a 2a 20 6f 63 63 75 72 73 2c 20 74 68 65 .** occurs, the
3c0b0 6e 20 61 6e 20 53 51 4c 69 74 65 20 65 72 72 6f n an SQLite erro
3c0c0 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e r code is return
3c0d0 65 64 2e 20 41 73 20 77 65 6c 6c 20 61 73 20 5b ed. As well as [
3c0e0 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 0a 2a SQLITE_OK] and.*
3c0f0 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c * [SQLITE_DONE],
3c100 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 a call to sqlit
3c110 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3c120 20 6d 61 79 20 72 65 74 75 72 6e 20 5b 53 51 4c may return [SQL
3c130 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2c 0a 2a ITE_READONLY],.*
3c140 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d * [SQLITE_NOMEM]
3c150 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c , [SQLITE_BUSY],
3c160 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5d [SQLITE_LOCKED]
3c170 2c 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 , or an.** [SQLI
3c180 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 TE_IOERR_ACCESS
3c190 7c 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 58 | SQLITE_IOERR_X
3c1a0 58 58 5d 20 65 78 74 65 6e 64 65 64 20 65 72 72 XX] extended err
3c1b0 6f 72 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 41 or code..**.** A
3c1c0 73 20 77 65 6c 6c 20 61 73 20 74 68 65 20 63 61 s well as the ca
3c1d0 73 65 20 77 68 65 72 65 20 74 68 65 20 64 65 73 se where the des
3c1e0 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 tination databas
3c1f0 65 20 66 69 6c 65 20 77 61 73 20 6f 70 65 6e 65 e file was opene
3c200 64 20 66 6f 72 0a 2a 2a 20 72 65 61 64 2d 6f 6e d for.** read-on
3c210 6c 79 20 61 63 63 65 73 73 2c 20 73 71 6c 69 74 ly access, sqlit
3c220 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3c230 20 6d 61 79 20 72 65 74 75 72 6e 20 5b 53 51 4c may return [SQL
3c240 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 20 69 66 ITE_READONLY] if
3c250 0a 2a 2a 20 74 68 65 20 64 65 73 74 69 6e 61 74 .** the destinat
3c260 69 6f 6e 20 69 73 20 61 6e 20 69 6e 2d 6d 65 6d ion is an in-mem
3c270 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 74 ory database wit
3c280 68 20 61 20 64 69 66 66 65 72 65 6e 74 20 70 61 h a different pa
3c290 67 65 20 73 69 7a 65 0a 2a 2a 20 66 72 6f 6d 20 ge size.** from
3c2a0 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 the source datab
3c2b0 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 ase..**.** If sq
3c2c0 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3c2d0 70 28 29 20 63 61 6e 6e 6f 74 20 6f 62 74 61 69 p() cannot obtai
3c2e0 6e 20 61 20 72 65 71 75 69 72 65 64 20 66 69 6c n a required fil
3c2f0 65 2d 73 79 73 74 65 6d 20 6c 6f 63 6b 2c 20 74 e-system lock, t
3c300 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 hen.** the [sqli
3c310 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
3c320 20 7c 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 | busy-handler
3c330 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 function].** is
3c340 69 6e 76 6f 6b 65 64 20 28 69 66 20 6f 6e 65 20 invoked (if one
3c350 69 73 20 73 70 65 63 69 66 69 65 64 29 2e 20 49 is specified). I
3c360 66 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 2d 68 f the .** busy-h
3c370 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 6e andler returns n
3c380 6f 6e 2d 7a 65 72 6f 20 62 65 66 6f 72 65 20 74 on-zero before t
3c390 68 65 20 6c 6f 63 6b 20 69 73 20 61 76 61 69 6c he lock is avail
3c3a0 61 62 6c 65 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b able, then .** [
3c3b0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 SQLITE_BUSY] is
3c3c0 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 returned to the
3c3d0 63 61 6c 6c 65 72 2e 20 49 6e 20 74 68 69 73 20 caller. In this
3c3e0 63 61 73 65 20 74 68 65 20 63 61 6c 6c 20 74 6f case the call to
3c3f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b .** sqlite3_back
3c400 75 70 5f 73 74 65 70 28 29 20 63 61 6e 20 62 65 up_step() can be
3c410 20 72 65 74 72 69 65 64 20 6c 61 74 65 72 2e 20 retried later.
3c420 49 66 20 74 68 65 20 73 6f 75 72 63 65 0a 2a 2a If the source.**
3c430 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
3c440 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 62 65 69 ction].** is bei
3c450 6e 67 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 ng used to write
3c460 20 74 6f 20 74 68 65 20 73 6f 75 72 63 65 20 64 to the source d
3c470 61 74 61 62 61 73 65 20 77 68 65 6e 20 73 71 6c atabase when sql
3c480 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3c490 28 29 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64 2c ().** is called,
3c4a0 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4c 4f then [SQLITE_LO
3c4b0 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 CKED] is returne
3c4c0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 20 41 d immediately. A
3c4d0 67 61 69 6e 2c 20 69 6e 20 74 68 69 73 0a 2a 2a gain, in this.**
3c4e0 20 63 61 73 65 20 74 68 65 20 63 61 6c 6c 20 74 case the call t
3c4f0 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 o sqlite3_backup
3c500 5f 73 74 65 70 28 29 20 63 61 6e 20 62 65 20 72 _step() can be r
3c510 65 74 72 69 65 64 20 6c 61 74 65 72 20 6f 6e 2e etried later on.
3c520 20 49 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 If.** [SQLITE_I
3c530 4f 45 52 52 5f 41 43 43 45 53 53 20 7c 20 53 51 OERR_ACCESS | SQ
3c540 4c 49 54 45 5f 49 4f 45 52 52 5f 58 58 58 5d 2c LITE_IOERR_XXX],
3c550 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c [SQLITE_NOMEM],
3c560 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 or.** [SQLITE_R
3c570 45 41 44 4f 4e 4c 59 5d 20 69 73 20 72 65 74 75 EADONLY] is retu
3c580 72 6e 65 64 2c 20 74 68 65 6e 20 0a 2a 2a 20 74 rned, then .** t
3c590 68 65 72 65 20 69 73 20 6e 6f 20 70 6f 69 6e 74 here is no point
3c5a0 20 69 6e 20 72 65 74 72 79 69 6e 67 20 74 68 65 in retrying the
3c5b0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
3c5c0 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 20 _backup_step().
3c5d0 54 68 65 73 65 20 0a 2a 2a 20 65 72 72 6f 72 73 These .** errors
3c5e0 20 61 72 65 20 63 6f 6e 73 69 64 65 72 65 64 20 are considered
3c5f0 66 61 74 61 6c 2e 20 41 74 20 74 68 69 73 20 70 fatal. At this p
3c600 6f 69 6e 74 20 74 68 65 20 61 70 70 6c 69 63 61 oint the applica
3c610 74 69 6f 6e 20 6d 75 73 74 20 61 63 63 65 70 74 tion must accept
3c620 20 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 62 61 .** that the ba
3c630 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 20 68 ckup operation h
3c640 61 73 20 66 61 69 6c 65 64 20 61 6e 64 20 70 61 as failed and pa
3c650 73 73 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 ss the backup op
3c660 65 72 61 74 69 6f 6e 20 68 61 6e 64 6c 65 20 0a eration handle .
3c670 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 ** to the sqlite
3c680 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 3_backup_finish(
3c690 29 20 74 6f 20 72 65 6c 65 61 73 65 20 61 73 73 ) to release ass
3c6a0 6f 63 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 ociated resource
3c6b0 73 2e 0a 2a 2a 0a 2a 2a 20 46 6f 6c 6c 6f 77 69 s..**.** Followi
3c6c0 6e 67 20 74 68 65 20 66 69 72 73 74 20 63 61 6c ng the first cal
3c6d0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 l to sqlite3_bac
3c6e0 6b 75 70 5f 73 74 65 70 28 29 2c 20 61 6e 20 65 kup_step(), an e
3c6f0 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 20 69 73 xclusive lock is
3c700 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 6f 6e 20 .** obtained on
3c710 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 the destination
3c720 66 69 6c 65 2e 20 49 74 20 69 73 20 6e 6f 74 20 file. It is not
3c730 72 65 6c 65 61 73 65 64 20 75 6e 74 69 6c 20 65 released until e
3c740 69 74 68 65 72 20 0a 2a 2a 20 73 71 6c 69 74 65 ither .** sqlite
3c750 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 3_backup_finish(
3c760 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 72 20 74 ) is called or t
3c770 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 he backup operat
3c780 69 6f 6e 20 69 73 20 63 6f 6d 70 6c 65 74 65 20 ion is complete
3c790 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f .** and sqlite3_
3c7a0 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 72 65 backup_step() re
3c7b0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 4f turns [SQLITE_DO
3c7c0 4e 45 5d 2e 20 41 64 64 69 74 69 6f 6e 61 6c 6c NE]. Additionall
3c7d0 79 2c 20 65 61 63 68 20 74 69 6d 65 20 0a 2a 2a y, each time .**
3c7e0 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 a call to sqlit
3c7f0 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3c800 20 69 73 20 6d 61 64 65 20 61 20 5b 73 68 61 72 is made a [shar
3c810 65 64 20 6c 6f 63 6b 5d 20 69 73 20 6f 62 74 61 ed lock] is obta
3c820 69 6e 65 64 20 6f 6e 0a 2a 2a 20 74 68 65 20 73 ined on.** the s
3c830 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 20 66 ource database f
3c840 69 6c 65 2e 20 54 68 69 73 20 6c 6f 63 6b 20 69 ile. This lock i
3c850 73 20 72 65 6c 65 61 73 65 64 20 62 65 66 6f 72 s released befor
3c860 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 e the.** sqlite3
3c870 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 63 _backup_step() c
3c880 61 6c 6c 20 72 65 74 75 72 6e 73 2e 20 42 65 63 all returns. Bec
3c890 61 75 73 65 20 74 68 65 20 73 6f 75 72 63 65 20 ause the source
3c8a0 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a database is not.
3c8b0 2a 2a 20 6c 6f 63 6b 65 64 20 62 65 74 77 65 65 ** locked betwee
3c8c0 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 n calls to sqlit
3c8d0 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3c8e0 2c 20 69 74 20 6d 61 79 20 62 65 20 6d 6f 64 69 , it may be modi
3c8f0 66 69 65 64 20 6d 69 64 2d 77 61 79 0a 2a 2a 20 fied mid-way.**
3c900 74 68 72 6f 75 67 68 20 74 68 65 20 62 61 63 6b through the back
3c910 75 70 20 70 72 6f 63 65 64 75 72 65 2e 20 49 66 up procedure. If
3c920 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 the source data
3c930 62 61 73 65 20 69 73 20 6d 6f 64 69 66 69 65 64 base is modified
3c940 20 62 79 20 61 6e 0a 2a 2a 20 65 78 74 65 72 6e by an.** extern
3c950 61 6c 20 70 72 6f 63 65 73 73 20 6f 72 20 76 69 al process or vi
3c960 61 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e a a database con
3c970 6e 65 63 74 69 6f 6e 20 6f 74 68 65 72 20 74 68 nection other th
3c980 61 6e 20 74 68 65 20 6f 6e 65 20 62 65 69 6e 67 an the one being
3c990 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65 20 .** used by the
3c9a0 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e backup operation
3c9b0 2c 20 74 68 65 6e 20 74 68 65 20 62 61 63 6b 75 , then the backu
3c9c0 70 20 77 69 6c 6c 20 62 65 20 74 72 61 6e 73 70 p will be transp
3c9d0 61 72 65 6e 74 6c 79 0a 2a 2a 20 72 65 73 74 61 arently.** resta
3c9e0 72 74 65 64 20 62 79 20 74 68 65 20 6e 65 78 74 rted by the next
3c9f0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
3ca00 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 20 _backup_step().
3ca10 49 66 20 74 68 65 20 73 6f 75 72 63 65 20 0a 2a If the source .*
3ca20 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 6d 6f * database is mo
3ca30 64 69 66 69 65 64 20 62 79 20 74 68 65 20 75 73 dified by the us
3ca40 69 6e 67 20 74 68 65 20 73 61 6d 65 20 64 61 74 ing the same dat
3ca50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3ca60 20 61 73 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 as is used.** b
3ca70 79 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 y the backup ope
3ca80 72 61 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 ration, then the
3ca90 20 62 61 63 6b 75 70 20 64 61 74 61 62 61 73 65 backup database
3caa0 20 69 73 20 74 72 61 6e 73 70 61 72 65 6e 74 6c is transparentl
3cab0 79 20 0a 2a 2a 20 75 70 64 61 74 65 64 20 61 74 y .** updated at
3cac0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a the same time..
3cad0 2a 2a 0a 2a 2a 20 3c 62 3e 73 71 6c 69 74 65 33 **.** <b>sqlite3
3cae0 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 _backup_finish()
3caf0 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 63 65 20 </b>.**.** Once
3cb00 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 sqlite3_backup_s
3cb10 74 65 70 28 29 20 68 61 73 20 72 65 74 75 72 6e tep() has return
3cb20 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d ed [SQLITE_DONE]
3cb30 2c 20 6f 72 20 77 68 65 6e 20 74 68 65 20 0a 2a , or when the .*
3cb40 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 69 * application wi
3cb50 73 68 65 73 20 74 6f 20 61 62 61 6e 64 6f 6e 20 shes to abandon
3cb60 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 the backup opera
3cb70 74 69 6f 6e 2c 20 74 68 65 20 5b 73 71 6c 69 74 tion, the [sqlit
3cb80 65 33 5f 62 61 63 6b 75 70 5d 0a 2a 2a 20 6f 62 e3_backup].** ob
3cb90 6a 65 63 74 20 73 68 6f 75 6c 64 20 62 65 20 70 ject should be p
3cba0 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 assed to sqlite3
3cbb0 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 _backup_finish()
3cbc0 2e 20 54 68 69 73 20 72 65 6c 65 61 73 65 73 20 . This releases
3cbd0 61 6c 6c 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 all.** resources
3cbe0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
3cbf0 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 the backup oper
3cc00 61 74 69 6f 6e 2e 20 49 66 20 73 71 6c 69 74 65 ation. If sqlite
3cc10 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 0a 3_backup_step().
3cc20 2a 2a 20 68 61 73 20 6e 6f 74 20 79 65 74 20 72 ** has not yet r
3cc30 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
3cc40 44 4f 4e 45 5d 2c 20 74 68 65 6e 20 61 6e 79 20 DONE], then any
3cc50 61 63 74 69 76 65 20 77 72 69 74 65 2d 74 72 61 active write-tra
3cc60 6e 73 61 63 74 69 6f 6e 20 6f 6e 20 74 68 65 0a nsaction on the.
3cc70 2a 2a 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 ** destination d
3cc80 61 74 61 62 61 73 65 20 69 73 20 72 6f 6c 6c 65 atabase is rolle
3cc90 64 20 62 61 63 6b 2e 20 54 68 65 20 5b 73 71 6c d back. The [sql
3cca0 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a ite3_backup] obj
3ccb0 65 63 74 20 69 73 20 69 6e 76 61 6c 69 64 0a 2a ect is invalid.*
3ccc0 2a 20 61 6e 64 20 6d 61 79 20 6e 6f 74 20 62 65 * and may not be
3ccd0 20 75 73 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 used following
3cce0 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 a call to sqlite
3ccf0 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 3_backup_finish(
3cd00 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c )..**.** The val
3cd10 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ue returned by s
3cd20 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 qlite3_backup_fi
3cd30 6e 69 73 68 20 69 73 20 5b 53 51 4c 49 54 45 5f nish is [SQLITE_
3cd40 4f 4b 5d 20 69 66 20 6e 6f 20 65 72 72 6f 72 0a OK] if no error.
3cd50 2a 2a 20 6f 63 63 75 72 72 65 64 2c 20 72 65 67 ** occurred, reg
3cd60 61 72 64 6c 65 73 73 20 6f 72 20 77 68 65 74 68 ardless or wheth
3cd70 65 72 20 6f 72 20 6e 6f 74 20 73 71 6c 69 74 65 er or not sqlite
3cd80 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 3_backup_step()
3cd90 77 61 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 61 20 was called.** a
3cda0 73 75 66 66 69 63 69 65 6e 74 20 6e 75 6d 62 65 sufficient numbe
3cdb0 72 20 6f 66 20 74 69 6d 65 73 20 74 6f 20 63 6f r of times to co
3cdc0 6d 70 6c 65 74 65 20 74 68 65 20 62 61 63 6b 75 mplete the backu
3cdd0 70 20 6f 70 65 72 61 74 69 6f 6e 2e 20 4f 72 2c p operation. Or,
3cde0 20 69 66 0a 2a 2a 20 61 6e 20 6f 75 74 2d 6f 66 if.** an out-of
3cdf0 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f -memory conditio
3ce00 6e 20 6f 72 20 49 4f 20 65 72 72 6f 72 20 6f 63 n or IO error oc
3ce10 63 75 72 65 64 20 64 75 72 69 6e 67 20 61 20 63 cured during a c
3ce20 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 all to.** sqlite
3ce30 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 3_backup_step()
3ce40 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d then [SQLITE_NOM
3ce50 45 4d 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 EM] or an.** [SQ
3ce60 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 LITE_IOERR_ACCES
3ce70 53 20 7c 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 S | SQLITE_IOERR
3ce80 5f 58 58 58 5d 20 65 72 72 6f 72 20 63 6f 64 65 _XXX] error code
3ce90 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e .** is returned.
3cea0 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 74 68 In this case th
3ceb0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 e error code and
3cec0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
3ced0 65 20 61 72 65 0a 2a 2a 20 77 72 69 74 74 65 6e e are.** written
3cee0 20 74 6f 20 74 68 65 20 64 65 73 74 69 6e 61 74 to the destinat
3cef0 69 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f ion [database co
3cf00 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a nnection]..**.**
3cf10 20 41 20 72 65 74 75 72 6e 20 6f 66 20 5b 53 51 A return of [SQ
3cf20 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 LITE_BUSY] or [S
3cf30 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5d 20 66 72 QLITE_LOCKED] fr
3cf40 6f 6d 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 om sqlite3_backu
3cf50 70 5f 73 74 65 70 28 29 20 69 73 0a 2a 2a 20 6e p_step() is.** n
3cf60 6f 74 20 61 20 70 65 72 6d 61 6e 65 6e 74 20 65 ot a permanent e
3cf70 72 72 6f 72 20 61 6e 64 20 64 6f 65 73 20 6e 6f rror and does no
3cf80 74 20 61 66 66 65 63 74 20 74 68 65 20 72 65 74 t affect the ret
3cf90 75 72 6e 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 urn value of.**
3cfa0 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 sqlite3_backup_f
3cfb0 69 6e 69 73 68 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c inish()..**.** <
3cfc0 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 b>sqlite3_backup
3cfd0 5f 72 65 6d 61 69 6e 69 6e 67 28 29 2c 20 73 71 _remaining(), sq
3cfe0 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 70 61 67 lite3_backup_pag
3cff0 65 63 6f 75 6e 74 28 29 3c 2f 62 3e 0a 2a 2a 0a ecount()</b>.**.
3d000 2a 2a 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 ** Each call to
3d010 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 sqlite3_backup_s
3d020 74 65 70 28 29 20 73 65 74 73 20 74 77 6f 20 76 tep() sets two v
3d030 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 74 alues stored int
3d040 65 72 6e 61 6c 6c 79 0a 2a 2a 20 62 79 20 61 6e ernally.** by an
3d050 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 [sqlite3_backup
3d060 5d 20 6f 62 6a 65 63 74 2e 20 54 68 65 20 6e 75 ] object. The nu
3d070 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 73 74 mber of pages st
3d080 69 6c 6c 20 74 6f 20 62 65 20 62 61 63 6b 65 64 ill to be backed
3d090 0a 2a 2a 20 75 70 2c 20 77 68 69 63 68 20 6d 61 .** up, which ma
3d0a0 79 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 y be queried by
3d0b0 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 72 sqlite3_backup_r
3d0c0 65 6d 61 69 6e 69 6e 67 28 29 2c 20 61 6e 64 20 emaining(), and
3d0d0 74 68 65 20 74 6f 74 61 6c 0a 2a 2a 20 6e 75 6d the total.** num
3d0e0 62 65 72 20 6f 66 20 70 61 67 65 73 20 69 6e 20 ber of pages in
3d0f0 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 the source datab
3d100 61 73 65 20 66 69 6c 65 2c 20 77 68 69 63 68 20 ase file, which
3d110 6d 61 79 20 62 65 20 71 75 65 72 69 65 64 20 62 may be queried b
3d120 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 y.** sqlite3_bac
3d130 6b 75 70 5f 70 61 67 65 63 6f 75 6e 74 28 29 2e kup_pagecount().
3d140 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 .**.** The value
3d150 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
3d160 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 ese functions ar
3d170 65 20 6f 6e 6c 79 20 75 70 64 61 74 65 64 20 62 e only updated b
3d180 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 y.** sqlite3_bac
3d190 6b 75 70 5f 73 74 65 70 28 29 2e 20 49 66 20 74 kup_step(). If t
3d1a0 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 he source databa
3d1b0 73 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 se is modified d
3d1c0 75 72 69 6e 67 20 61 20 62 61 63 6b 75 70 0a 2a uring a backup.*
3d1d0 2a 20 6f 70 65 72 61 74 69 6f 6e 2c 20 74 68 65 * operation, the
3d1e0 6e 20 74 68 65 20 76 61 6c 75 65 73 20 61 72 65 n the values are
3d1f0 20 6e 6f 74 20 75 70 64 61 74 65 64 20 74 6f 20 not updated to
3d200 61 63 63 6f 75 6e 74 20 66 6f 72 20 61 6e 79 20 account for any
3d210 65 78 74 72 61 0a 2a 2a 20 70 61 67 65 73 20 74 extra.** pages t
3d220 68 61 74 20 6e 65 65 64 20 74 6f 20 62 65 20 75 hat need to be u
3d230 70 64 61 74 65 64 20 6f 72 20 74 68 65 20 73 69 pdated or the si
3d240 7a 65 20 6f 66 20 74 68 65 20 73 6f 75 72 63 65 ze of the source
3d250 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a database file.*
3d260 2a 20 63 68 61 6e 67 69 6e 67 2e 0a 2a 2a 0a 2a * changing..**.*
3d270 2a 20 3c 62 3e 43 6f 6e 63 75 72 72 65 6e 74 20 * <b>Concurrent
3d280 55 73 61 67 65 20 6f 66 20 44 61 74 61 62 61 73 Usage of Databas
3d290 65 20 48 61 6e 64 6c 65 73 3c 2f 62 3e 0a 2a 2a e Handles</b>.**
3d2a0 0a 2a 2a 20 54 68 65 20 73 6f 75 72 63 65 20 5b .** The source [
3d2b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3d2c0 69 6f 6e 5d 20 6d 61 79 20 62 65 20 75 73 65 64 ion] may be used
3d2d0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 by the applicat
3d2e0 69 6f 6e 20 66 6f 72 20 6f 74 68 65 72 0a 2a 2a ion for other.**
3d2f0 20 70 75 72 70 6f 73 65 73 20 77 68 69 6c 65 20 purposes while
3d300 61 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 a backup operati
3d310 6f 6e 20 69 73 20 75 6e 64 65 72 77 61 79 20 6f on is underway o
3d320 72 20 62 65 69 6e 67 20 69 6e 69 74 69 61 6c 69 r being initiali
3d330 7a 65 64 2e 0a 2a 2a 20 49 66 20 53 51 4c 69 74 zed..** If SQLit
3d340 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 61 6e e is compiled an
3d350 64 20 63 6f 6e 66 69 67 75 72 65 64 20 74 6f 20 d configured to
3d360 73 75 70 70 6f 72 74 20 74 68 72 65 61 64 73 61 support threadsa
3d370 66 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 fe database.** c
3d380 6f 6e 6e 65 63 74 69 6f 6e 73 2c 20 74 68 65 6e onnections, then
3d390 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 the source data
3d3a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
3d3b0 6d 61 79 20 62 65 20 75 73 65 64 20 63 6f 6e 63 may be used conc
3d3c0 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 66 72 6f 6d urrently.** from
3d3d0 20 77 69 74 68 69 6e 20 6f 74 68 65 72 20 74 68 within other th
3d3e0 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 48 6f 77 reads..**.** How
3d3f0 65 76 65 72 2c 20 74 68 65 20 61 70 70 6c 69 63 ever, the applic
3d400 61 74 69 6f 6e 20 6d 75 73 74 20 67 75 61 72 61 ation must guara
3d410 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 64 65 ntee that the de
3d420 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 stination databa
3d430 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
3d440 20 68 61 6e 64 6c 65 20 69 73 20 6e 6f 74 20 70 handle is not p
3d450 61 73 73 65 64 20 74 6f 20 61 6e 79 20 6f 74 68 assed to any oth
3d460 65 72 20 41 50 49 20 28 62 79 20 61 6e 79 20 74 er API (by any t
3d470 68 72 65 61 64 29 20 61 66 74 65 72 20 0a 2a 2a hread) after .**
3d480 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3d490 69 6e 69 74 28 29 20 69 73 20 63 61 6c 6c 65 64 init() is called
3d4a0 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 and before the
3d4b0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 63 61 corresponding ca
3d4c0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ll to.** sqlite3
3d4d0 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 _backup_finish()
3d4e0 2e 20 55 6e 66 6f 72 74 75 6e 61 74 65 6c 79 20 . Unfortunately
3d4f0 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 SQLite does not
3d500 63 75 72 72 65 6e 74 6c 79 20 63 68 65 63 6b 0a currently check.
3d510 2a 2a 20 66 6f 72 20 74 68 69 73 2c 20 69 66 20 ** for this, if
3d520 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
3d530 64 6f 65 73 20 75 73 65 20 74 68 65 20 64 65 73 does use the des
3d540 74 69 6e 61 74 69 6f 6e 20 5b 64 61 74 61 62 61 tination [databa
3d550 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a se connection].*
3d560 2a 20 66 6f 72 20 73 6f 6d 65 20 6f 74 68 65 72 * for some other
3d570 20 70 75 72 70 6f 73 65 20 64 75 72 69 6e 67 20 purpose during
3d580 61 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 a backup operati
3d590 6f 6e 2c 20 74 68 69 6e 67 73 20 6d 61 79 20 61 on, things may a
3d5a0 70 70 65 61 72 20 74 6f 0a 2a 2a 20 77 6f 72 6b ppear to.** work
3d5b0 20 63 6f 72 72 65 63 74 6c 79 20 62 75 74 20 69 correctly but i
3d5c0 6e 20 66 61 63 74 20 62 65 20 73 75 62 74 6c 79 n fact be subtly
3d5d0 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 69 6e 67 2e malfunctioning.
3d5e0 20 20 55 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 Use of the.**
3d5f0 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 destination data
3d600 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
3d610 77 68 69 6c 65 20 61 20 62 61 63 6b 75 70 20 69 while a backup i
3d620 73 20 69 6e 20 70 72 6f 67 72 65 73 73 20 6d 69 s in progress mi
3d630 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 63 61 75 73 ght.** also caus
3d640 65 20 61 20 6d 75 74 65 78 20 64 65 61 64 6c 6f e a mutex deadlo
3d650 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 75 72 74 68 65 ck..**.** Furthe
3d660 72 6d 6f 72 65 2c 20 69 66 20 72 75 6e 6e 69 6e rmore, if runnin
3d670 67 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 g in [shared cac
3d680 68 65 20 6d 6f 64 65 5d 2c 20 74 68 65 20 61 70 he mode], the ap
3d690 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 0a 2a plication must.*
3d6a0 2a 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 * guarantee that
3d6b0 20 74 68 65 20 73 68 61 72 65 64 20 63 61 63 68 the shared cach
3d6c0 65 20 75 73 65 64 20 62 79 20 74 68 65 20 64 65 e used by the de
3d6d0 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 stination databa
3d6e0 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 63 63 se.** is not acc
3d6f0 65 73 73 65 64 20 77 68 69 6c 65 20 74 68 65 20 essed while the
3d700 62 61 63 6b 75 70 20 69 73 20 72 75 6e 6e 69 6e backup is runnin
3d710 67 2e 20 49 6e 20 70 72 61 63 74 69 63 65 20 74 g. In practice t
3d720 68 69 73 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 his means.** tha
3d730 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f t the applicatio
3d740 6e 20 6d 75 73 74 20 67 75 61 72 61 6e 74 65 65 n must guarantee
3d750 20 74 68 61 74 20 74 68 65 20 66 69 6c 65 2d 73 that the file-s
3d760 79 73 74 65 6d 20 66 69 6c 65 20 62 65 69 6e 67 ystem file being
3d770 20 0a 2a 2a 20 62 61 63 6b 65 64 20 75 70 20 74 .** backed up t
3d780 6f 20 69 73 20 6e 6f 74 20 61 63 63 65 73 73 65 o is not accesse
3d790 64 20 62 79 20 61 6e 79 20 63 6f 6e 6e 65 63 74 d by any connect
3d7a0 69 6f 6e 20 77 69 74 68 69 6e 20 74 68 65 20 70 ion within the p
3d7b0 72 6f 63 65 73 73 2c 0a 2a 2a 20 6e 6f 74 20 6a rocess,.** not j
3d7c0 75 73 74 20 74 68 65 20 73 70 65 63 69 66 69 63 ust the specific
3d7d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
3d7e0 20 77 61 73 20 70 61 73 73 65 64 20 74 6f 20 73 was passed to s
3d7f0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e qlite3_backup_in
3d800 69 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 it()..**.** The
3d810 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d [sqlite3_backup]
3d820 20 6f 62 6a 65 63 74 20 69 74 73 65 6c 66 20 69 object itself i
3d830 73 20 70 61 72 74 69 61 6c 6c 79 20 74 68 72 65 s partially thre
3d840 61 64 73 61 66 65 2e 20 4d 75 6c 74 69 70 6c 65 adsafe. Multiple
3d850 20 0a 2a 2a 20 74 68 72 65 61 64 73 20 6d 61 79 .** threads may
3d860 20 73 61 66 65 6c 79 20 6d 61 6b 65 20 6d 75 6c safely make mul
3d870 74 69 70 6c 65 20 63 6f 6e 63 75 72 72 65 6e 74 tiple concurrent
3d880 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
3d890 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 3_backup_step().
3d8a0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 .** However, the
3d8b0 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3d8c0 72 65 6d 61 69 6e 69 6e 67 28 29 20 61 6e 64 20 remaining() and
3d8d0 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 70 sqlite3_backup_p
3d8e0 61 67 65 63 6f 75 6e 74 28 29 0a 2a 2a 20 41 50 agecount().** AP
3d8f0 49 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 Is are not stric
3d900 74 6c 79 20 73 70 65 61 6b 69 6e 67 20 74 68 72 tly speaking thr
3d910 65 61 64 73 61 66 65 2e 20 49 66 20 74 68 65 79 eadsafe. If they
3d920 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 are invoked at
3d930 74 68 65 0a 2a 2a 20 73 61 6d 65 20 74 69 6d 65 the.** same time
3d940 20 61 73 20 61 6e 6f 74 68 65 72 20 74 68 72 65 as another thre
3d950 61 64 20 69 73 20 69 6e 76 6f 6b 69 6e 67 20 73 ad is invoking s
3d960 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3d970 65 70 28 29 20 69 74 20 69 73 0a 2a 2a 20 70 6f ep() it is.** po
3d980 73 73 69 62 6c 65 20 74 68 61 74 20 74 68 65 79 ssible that they
3d990 20 72 65 74 75 72 6e 20 69 6e 76 61 6c 69 64 20 return invalid
3d9a0 76 61 6c 75 65 73 2e 0a 2a 2f 0a 73 71 6c 69 74 values..*/.sqlit
3d9b0 65 33 5f 62 61 63 6b 75 70 20 2a 73 71 6c 69 74 e3_backup *sqlit
3d9c0 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 0a e3_backup_init(.
3d9d0 20 20 73 71 6c 69 74 65 33 20 2a 70 44 65 73 74 sqlite3 *pDest
3d9e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
3d9f0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 65 73 74 /* Dest
3da00 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 ination database
3da10 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
3da20 73 74 20 63 68 61 72 20 2a 7a 44 65 73 74 4e 61 st char *zDestNa
3da30 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 me,
3da40 20 20 20 20 2f 2a 20 44 65 73 74 69 6e 61 74 69 /* Destinati
3da50 6f 6e 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 on database name
3da60 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 70 */. sqlite3 *p
3da70 53 6f 75 72 63 65 2c 20 20 20 20 20 20 20 20 20 Source,
3da80 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
3da90 53 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 20 Source database
3daa0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
3dab0 74 20 63 68 61 72 20 2a 7a 53 6f 75 72 63 65 4e t char *zSourceN
3dac0 61 6d 65 20 20 20 20 20 20 20 20 20 20 20 20 20 ame
3dad0 20 20 20 2f 2a 20 53 6f 75 72 63 65 20 64 61 74 /* Source dat
3dae0 61 62 61 73 65 20 6e 61 6d 65 20 2a 2f 0a 29 3b abase name */.);
3daf0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 61 63 .int sqlite3_bac
3db00 6b 75 70 5f 73 74 65 70 28 73 71 6c 69 74 65 33 kup_step(sqlite3
3db10 5f 62 61 63 6b 75 70 20 2a 70 2c 20 69 6e 74 20 _backup *p, int
3db20 6e 50 61 67 65 29 3b 0a 69 6e 74 20 73 71 6c 69 nPage);.int sqli
3db30 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 te3_backup_finis
3db40 68 28 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 h(sqlite3_backup
3db50 20 2a 70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *p);.int sqlite
3db60 33 5f 62 61 63 6b 75 70 5f 72 65 6d 61 69 6e 69 3_backup_remaini
3db70 6e 67 28 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ng(sqlite3_backu
3db80 70 20 2a 70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 p *p);.int sqlit
3db90 65 33 5f 62 61 63 6b 75 70 5f 70 61 67 65 63 6f e3_backup_pageco
3dba0 75 6e 74 28 73 71 6c 69 74 65 33 5f 62 61 63 6b unt(sqlite3_back
3dbb0 75 70 20 2a 70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 up *p);../*.** C
3dbc0 41 50 49 33 52 45 46 3a 20 55 6e 6c 6f 63 6b 20 API3REF: Unlock
3dbd0 4e 6f 74 69 66 69 63 61 74 69 6f 6e 0a 2a 2a 20 Notification.**
3dbe0 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
3dbf0 2a 2a 20 57 68 65 6e 20 72 75 6e 6e 69 6e 67 20 ** When running
3dc00 69 6e 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 in shared-cache
3dc10 6d 6f 64 65 2c 20 61 20 64 61 74 61 62 61 73 65 mode, a database
3dc20 20 6f 70 65 72 61 74 69 6f 6e 20 6d 61 79 20 66 operation may f
3dc30 61 69 6c 20 77 69 74 68 0a 2a 2a 20 61 6e 20 5b ail with.** an [
3dc40 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5d 20 65 SQLITE_LOCKED] e
3dc50 72 72 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 rror if the requ
3dc60 69 72 65 64 20 6c 6f 63 6b 73 20 6f 6e 20 74 68 ired locks on th
3dc70 65 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6f e shared-cache o
3dc80 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 r.** individual
3dc90 74 61 62 6c 65 73 20 77 69 74 68 69 6e 20 74 68 tables within th
3dca0 65 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 63 e shared-cache c
3dcb0 61 6e 6e 6f 74 20 62 65 20 6f 62 74 61 69 6e 65 annot be obtaine
3dcc0 64 2e 20 53 65 65 0a 2a 2a 20 5b 53 51 4c 69 74 d. See.** [SQLit
3dcd0 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d e Shared-Cache M
3dce0 6f 64 65 5d 20 66 6f 72 20 61 20 64 65 73 63 72 ode] for a descr
3dcf0 69 70 74 69 6f 6e 20 6f 66 20 73 68 61 72 65 64 iption of shared
3dd00 2d 63 61 63 68 65 20 6c 6f 63 6b 69 6e 67 2e 20 -cache locking.
3dd10 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 79 .** This API may
3dd20 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 67 69 be used to regi
3dd30 73 74 65 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 ster a callback
3dd40 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c that SQLite will
3dd50 20 69 6e 76 6f 6b 65 20 0a 2a 2a 20 77 68 65 6e invoke .** when
3dd60 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 the connection
3dd70 63 75 72 72 65 6e 74 6c 79 20 68 6f 6c 64 69 6e currently holdin
3dd80 67 20 74 68 65 20 72 65 71 75 69 72 65 64 20 6c g the required l
3dd90 6f 63 6b 20 72 65 6c 69 6e 71 75 69 73 68 65 73 ock relinquishes
3dda0 20 69 74 2e 0a 2a 2a 20 54 68 69 73 20 41 50 49 it..** This API
3ddb0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 is only availab
3ddc0 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 le if the librar
3ddd0 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 y was compiled w
3dde0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ith the.** [SQLI
3ddf0 54 45 5f 45 4e 41 42 4c 45 5f 55 4e 4c 4f 43 4b TE_ENABLE_UNLOCK
3de00 5f 4e 4f 54 49 46 59 5d 20 43 2d 70 72 65 70 72 _NOTIFY] C-prepr
3de10 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 ocessor symbol d
3de20 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 efined..**.** Se
3de30 65 20 41 6c 73 6f 3a 20 5b 55 73 69 6e 67 20 74 e Also: [Using t
3de40 68 65 20 53 51 4c 69 74 65 20 55 6e 6c 6f 63 6b he SQLite Unlock
3de50 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 46 65 Notification Fe
3de60 61 74 75 72 65 5d 2e 0a 2a 2a 0a 2a 2a 20 53 68 ature]..**.** Sh
3de70 61 72 65 64 2d 63 61 63 68 65 20 6c 6f 63 6b 73 ared-cache locks
3de80 20 61 72 65 20 72 65 6c 65 61 73 65 64 20 77 68 are released wh
3de90 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f en a database co
3dea0 6e 6e 65 63 74 69 6f 6e 20 63 6f 6e 63 6c 75 64 nnection conclud
3deb0 65 73 0a 2a 2a 20 69 74 73 20 63 75 72 72 65 6e es.** its curren
3dec0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 65 t transaction, e
3ded0 69 74 68 65 72 20 62 79 20 63 6f 6d 6d 69 74 74 ither by committ
3dee0 69 6e 67 20 69 74 20 6f 72 20 72 6f 6c 6c 69 6e ing it or rollin
3def0 67 20 69 74 20 62 61 63 6b 2e 20 0a 2a 2a 0a 2a g it back. .**.*
3df00 2a 20 57 68 65 6e 20 61 20 63 6f 6e 6e 65 63 74 * When a connect
3df10 69 6f 6e 20 28 6b 6e 6f 77 6e 20 61 73 20 74 68 ion (known as th
3df20 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 e blocked connec
3df30 74 69 6f 6e 29 20 66 61 69 6c 73 20 74 6f 20 6f tion) fails to o
3df40 62 74 61 69 6e 20 61 0a 2a 2a 20 73 68 61 72 65 btain a.** share
3df50 64 2d 63 61 63 68 65 20 6c 6f 63 6b 20 61 6e 64 d-cache lock and
3df60 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 69 SQLITE_LOCKED i
3df70 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 s returned to th
3df80 65 20 63 61 6c 6c 65 72 2c 20 74 68 65 0a 2a 2a e caller, the.**
3df90 20 69 64 65 6e 74 69 74 79 20 6f 66 20 74 68 65 identity of the
3dfa0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
3dfb0 74 69 6f 6e 20 28 74 68 65 20 62 6c 6f 63 6b 69 tion (the blocki
3dfc0 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 29 20 74 ng connection) t
3dfd0 68 61 74 0a 2a 2a 20 68 61 73 20 6c 6f 63 6b 65 hat.** has locke
3dfe0 64 20 74 68 65 20 72 65 71 75 69 72 65 64 20 72 d the required r
3dff0 65 73 6f 75 72 63 65 20 69 73 20 73 74 6f 72 65 esource is store
3e000 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 20 41 66 d internally. Af
3e010 74 65 72 20 61 6e 20 0a 2a 2a 20 61 70 70 6c 69 ter an .** appli
3e020 63 61 74 69 6f 6e 20 72 65 63 65 69 76 65 73 20 cation receives
3e030 61 6e 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 an SQLITE_LOCKED
3e040 20 65 72 72 6f 72 2c 20 69 74 20 6d 61 79 20 63 error, it may c
3e050 61 6c 6c 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 all the.** sqlit
3e060 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 e3_unlock_notify
3e070 28 29 20 6d 65 74 68 6f 64 20 77 69 74 68 20 74 () method with t
3e080 68 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 he blocked conne
3e090 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 61 73 20 ction handle as
3e0a0 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 61 72 .** the first ar
3e0b0 67 75 6d 65 6e 74 20 74 6f 20 72 65 67 69 73 74 gument to regist
3e0c0 65 72 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 er for a callbac
3e0d0 6b 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 69 k that will be i
3e0e0 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 nvoked.** when t
3e0f0 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e he blocking conn
3e100 65 63 74 69 6f 6e 73 20 63 75 72 72 65 6e 74 20 ections current
3e110 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 transaction is c
3e120 6f 6e 63 6c 75 64 65 64 2e 20 54 68 65 0a 2a 2a oncluded. The.**
3e130 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
3e140 6f 6b 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e oked from within
3e150 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 the [sqlite3_st
3e160 65 70 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ep] or [sqlite3_
3e170 63 6c 6f 73 65 5d 0a 2a 2a 20 63 61 6c 6c 20 74 close].** call t
3e180 68 61 74 20 63 6f 6e 63 6c 75 64 65 73 20 74 68 hat concludes th
3e190 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 e blocking conne
3e1a0 63 74 69 6f 6e 73 20 74 72 61 6e 73 61 63 74 69 ctions transacti
3e1b0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c on..**.** If sql
3e1c0 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 ite3_unlock_noti
3e1d0 66 79 28 29 20 69 73 20 63 61 6c 6c 65 64 20 69 fy() is called i
3e1e0 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 n a multi-thread
3e1f0 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 0a ed application,.
3e200 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 63 68 ** there is a ch
3e210 61 6e 63 65 20 74 68 61 74 20 74 68 65 20 62 6c ance that the bl
3e220 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f ocking connectio
3e230 6e 20 77 69 6c 6c 20 68 61 76 65 20 61 6c 72 65 n will have alre
3e240 61 64 79 0a 2a 2a 20 63 6f 6e 63 6c 75 64 65 64 ady.** concluded
3e250 20 69 74 73 20 74 72 61 6e 73 61 63 74 69 6f 6e its transaction
3e260 20 62 79 20 74 68 65 20 74 69 6d 65 20 73 71 6c by the time sql
3e270 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 ite3_unlock_noti
3e280 66 79 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 2e fy() is invoked.
3e290 0a 2a 2a 20 49 66 20 74 68 69 73 20 68 61 70 70 .** If this happ
3e2a0 65 6e 73 2c 20 74 68 65 6e 20 74 68 65 20 73 70 ens, then the sp
3e2b0 65 63 69 66 69 65 64 20 63 61 6c 6c 62 61 63 6b ecified callback
3e2c0 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6d 6d 65 is invoked imme
3e2d0 64 69 61 74 65 6c 79 2c 0a 2a 2a 20 66 72 6f 6d diately,.** from
3e2e0 20 77 69 74 68 69 6e 20 74 68 65 20 63 61 6c 6c within the call
3e2f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f to sqlite3_unlo
3e300 63 6b 5f 6e 6f 74 69 66 79 28 29 2e 0a 2a 2a 0a ck_notify()..**.
3e310 2a 2a 20 49 66 20 74 68 65 20 62 6c 6f 63 6b 65 ** If the blocke
3e320 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 d connection is
3e330 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 6f 62 attempting to ob
3e340 74 61 69 6e 20 61 20 77 72 69 74 65 2d 6c 6f 63 tain a write-loc
3e350 6b 20 6f 6e 20 61 0a 2a 2a 20 73 68 61 72 65 64 k on a.** shared
3e360 2d 63 61 63 68 65 20 74 61 62 6c 65 2c 20 61 6e -cache table, an
3e370 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 d more than one
3e380 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e other connection
3e390 20 63 75 72 72 65 6e 74 6c 79 20 68 6f 6c 64 73 currently holds
3e3a0 0a 2a 2a 20 61 20 72 65 61 64 2d 6c 6f 63 6b 20 .** a read-lock
3e3b0 6f 6e 20 74 68 65 20 73 61 6d 65 20 74 61 62 6c on the same tabl
3e3c0 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 e, then SQLite a
3e3d0 72 62 69 74 72 61 72 69 6c 79 20 73 65 6c 65 63 rbitrarily selec
3e3e0 74 73 20 6f 6e 65 20 6f 66 20 0a 2a 2a 20 74 68 ts one of .** th
3e3f0 65 20 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 e other connecti
3e400 6f 6e 73 20 74 6f 20 75 73 65 20 61 73 20 74 68 ons to use as th
3e410 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 e blocking conne
3e420 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ction..**.** The
3e430 72 65 20 6d 61 79 20 62 65 20 61 74 20 6d 6f 73 re may be at mos
3e440 74 20 6f 6e 65 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 t one unlock-not
3e450 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 67 ify callback reg
3e460 69 73 74 65 72 65 64 20 62 79 20 61 20 0a 2a 2a istered by a .**
3e470 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 74 blocked connect
3e480 69 6f 6e 2e 20 49 66 20 73 71 6c 69 74 65 33 5f ion. If sqlite3_
3e490 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 unlock_notify()
3e4a0 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 is called when t
3e4b0 68 65 0a 2a 2a 20 62 6c 6f 63 6b 65 64 20 63 6f he.** blocked co
3e4c0 6e 6e 65 63 74 69 6f 6e 20 61 6c 72 65 61 64 79 nnection already
3e4d0 20 68 61 73 20 61 20 72 65 67 69 73 74 65 72 65 has a registere
3e4e0 64 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 d unlock-notify
3e4f0 63 61 6c 6c 62 61 63 6b 2c 0a 2a 2a 20 74 68 65 callback,.** the
3e500 6e 20 74 68 65 20 6e 65 77 20 63 61 6c 6c 62 61 n the new callba
3e510 63 6b 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 ck replaces the
3e520 6f 6c 64 2e 20 49 66 20 73 71 6c 69 74 65 33 5f old. If sqlite3_
3e530 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 unlock_notify()
3e540 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 77 69 74 is.** called wit
3e550 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 h a NULL pointer
3e560 20 61 73 20 69 74 73 20 73 65 63 6f 6e 64 20 61 as its second a
3e570 72 67 75 6d 65 6e 74 2c 20 74 68 65 6e 20 61 6e rgument, then an
3e580 79 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 75 6e y existing.** un
3e590 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c lock-notify call
3e5a0 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 6c 65 back is cancelle
3e5b0 64 2e 20 54 68 65 20 62 6c 6f 63 6b 65 64 20 63 d. The blocked c
3e5c0 6f 6e 6e 65 63 74 69 6f 6e 73 20 0a 2a 2a 20 75 onnections .** u
3e5d0 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c nlock-notify cal
3e5e0 6c 62 61 63 6b 20 6d 61 79 20 61 6c 73 6f 20 62 lback may also b
3e5f0 65 20 63 61 6e 63 65 6c 65 64 20 62 79 20 63 6c e canceled by cl
3e600 6f 73 69 6e 67 20 74 68 65 20 62 6c 6f 63 6b 65 osing the blocke
3e610 64 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 d.** connection
3e620 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 using [sqlite3_c
3e630 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 lose()]..**.** T
3e640 68 65 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 he unlock-notify
3e650 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 callback is not
3e660 20 72 65 65 6e 74 72 61 6e 74 2e 20 49 66 20 61 reentrant. If a
3e670 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e n application in
3e680 76 6f 6b 65 73 0a 2a 2a 20 61 6e 79 20 73 71 6c vokes.** any sql
3e690 69 74 65 33 5f 78 78 78 20 41 50 49 20 66 75 6e ite3_xxx API fun
3e6a0 63 74 69 6f 6e 73 20 66 72 6f 6d 20 77 69 74 68 ctions from with
3e6b0 69 6e 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 in an unlock-not
3e6c0 69 66 79 20 63 61 6c 6c 62 61 63 6b 2c 20 61 0a ify callback, a.
3e6d0 2a 2a 20 63 72 61 73 68 20 6f 72 20 64 65 61 64 ** crash or dead
3e6e0 6c 6f 63 6b 20 6d 61 79 20 62 65 20 74 68 65 20 lock may be the
3e6f0 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 55 6e result..**.** Un
3e700 6c 65 73 73 20 64 65 61 64 6c 6f 63 6b 20 69 73 less deadlock is
3e710 20 64 65 74 65 63 74 65 64 20 28 73 65 65 20 62 detected (see b
3e720 65 6c 6f 77 29 2c 20 73 71 6c 69 74 65 33 5f 75 elow), sqlite3_u
3e730 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 61 nlock_notify() a
3e740 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e 73 lways.** returns
3e750 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a SQLITE_OK..**.*
3e760 2a 20 3c 62 3e 43 61 6c 6c 62 61 63 6b 20 49 6e * <b>Callback In
3e770 76 6f 63 61 74 69 6f 6e 20 44 65 74 61 69 6c 73 vocation Details
3e780 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 </b>.**.** When
3e790 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 an unlock-notify
3e7a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 72 65 67 callback is reg
3e7b0 69 73 74 65 72 65 64 2c 20 74 68 65 20 61 70 70 istered, the app
3e7c0 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 lication provide
3e7d0 73 20 61 20 0a 2a 2a 20 73 69 6e 67 6c 65 20 76 s a .** single v
3e7e0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 74 68 61 oid* pointer tha
3e7f0 74 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 74 t is passed to t
3e800 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 68 65 6e he callback when
3e810 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a it is invoked..
3e820 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 ** However, the
3e830 73 69 67 6e 61 74 75 72 65 20 6f 66 20 74 68 65 signature of the
3e840 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
3e850 6f 6e 20 61 6c 6c 6f 77 73 20 53 51 4c 69 74 65 on allows SQLite
3e860 20 74 6f 20 70 61 73 73 0a 2a 2a 20 69 74 20 61 to pass.** it a
3e870 6e 20 61 72 72 61 79 20 6f 66 20 76 6f 69 64 2a n array of void*
3e880 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 context pointer
3e890 73 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 s. The first arg
3e8a0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a ument passed to.
3e8b0 2a 2a 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 ** an unlock-not
3e8c0 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ify callback is
3e8d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
3e8e0 61 72 72 61 79 20 6f 66 20 76 6f 69 64 2a 20 70 array of void* p
3e8f0 6f 69 6e 74 65 72 73 2c 0a 2a 2a 20 61 6e 64 20 ointers,.** and
3e900 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 the second is th
3e910 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 e number of entr
3e920 69 65 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 ies in the array
3e930 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 62 ..**.** When a b
3e940 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 locking connecti
3e950 6f 6e 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 ons transaction
3e960 69 73 20 63 6f 6e 63 6c 75 64 65 64 2c 20 74 68 is concluded, th
3e970 65 72 65 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f ere may be.** mo
3e980 72 65 20 74 68 61 6e 20 6f 6e 65 20 62 6c 6f 63 re than one bloc
3e990 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ked connection t
3e9a0 68 61 74 20 68 61 73 20 72 65 67 69 73 74 65 72 hat has register
3e9b0 65 64 20 66 6f 72 20 61 6e 20 75 6e 6c 6f 63 6b ed for an unlock
3e9c0 2d 6e 6f 74 69 66 79 0a 2a 2a 20 63 61 6c 6c 62 -notify.** callb
3e9d0 61 63 6b 2e 20 49 66 20 74 77 6f 20 6f 72 20 6d ack. If two or m
3e9e0 6f 72 65 20 73 75 63 68 20 62 6c 6f 63 6b 65 64 ore such blocked
3e9f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 68 61 76 connections hav
3ea00 65 20 73 70 65 63 69 66 69 65 64 20 74 68 65 0a e specified the.
3ea10 2a 2a 20 73 61 6d 65 20 63 61 6c 6c 62 61 63 6b ** same callback
3ea20 20 66 75 6e 63 74 69 6f 6e 2c 20 74 68 65 6e 20 function, then
3ea30 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b instead of invok
3ea40 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ing the callback
3ea50 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 6c function.** mul
3ea60 74 69 70 6c 65 20 74 69 6d 65 73 2c 20 69 74 20 tiple times, it
3ea70 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 is invoked once
3ea80 77 69 74 68 20 74 68 65 20 73 65 74 20 6f 66 20 with the set of
3ea90 76 6f 69 64 2a 20 63 6f 6e 74 65 78 74 20 70 6f void* context po
3eaa0 69 6e 74 65 72 73 0a 2a 2a 20 73 70 65 63 69 66 inters.** specif
3eab0 69 65 64 20 62 79 20 74 68 65 20 62 6c 6f 63 6b ied by the block
3eac0 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 ed connections b
3ead0 75 6e 64 6c 65 64 20 74 6f 67 65 74 68 65 72 20 undled together
3eae0 69 6e 74 6f 20 61 6e 20 61 72 72 61 79 2e 0a 2a into an array..*
3eaf0 2a 20 54 68 69 73 20 67 69 76 65 73 20 74 68 65 * This gives the
3eb00 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 61 6e 20 application an
3eb10 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 6f 20 70 opportunity to p
3eb20 72 69 6f 72 69 74 69 7a 65 20 61 6e 79 20 61 63 rioritize any ac
3eb30 74 69 6f 6e 73 20 0a 2a 2a 20 72 65 6c 61 74 65 tions .** relate
3eb40 64 20 74 6f 20 74 68 65 20 73 65 74 20 6f 66 20 d to the set of
3eb50 75 6e 62 6c 6f 63 6b 65 64 20 64 61 74 61 62 61 unblocked databa
3eb60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a se connections..
3eb70 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 61 64 6c 6f 63 **.** <b>Deadloc
3eb80 6b 20 44 65 74 65 63 74 69 6f 6e 3c 2f 62 3e 0a k Detection</b>.
3eb90 2a 2a 0a 2a 2a 20 41 73 73 75 6d 69 6e 67 20 74 **.** Assuming t
3eba0 68 61 74 20 61 66 74 65 72 20 72 65 67 69 73 74 hat after regist
3ebb0 65 72 69 6e 67 20 66 6f 72 20 61 6e 20 75 6e 6c ering for an unl
3ebc0 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 ock-notify callb
3ebd0 61 63 6b 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 ack a .** databa
3ebe0 73 65 20 77 61 69 74 73 20 66 6f 72 20 74 68 65 se waits for the
3ebf0 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 callback to be
3ec00 69 73 73 75 65 64 20 62 65 66 6f 72 65 20 74 61 issued before ta
3ec10 6b 69 6e 67 20 61 6e 79 20 66 75 72 74 68 65 72 king any further
3ec20 0a 2a 2a 20 61 63 74 69 6f 6e 20 28 61 20 72 65 .** action (a re
3ec30 61 73 6f 6e 61 62 6c 65 20 61 73 73 75 6d 70 74 asonable assumpt
3ec40 69 6f 6e 29 2c 20 74 68 65 6e 20 75 73 69 6e 67 ion), then using
3ec50 20 74 68 69 73 20 41 50 49 20 6d 61 79 20 63 61 this API may ca
3ec60 75 73 65 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 use the.** appli
3ec70 63 61 74 69 6f 6e 20 74 6f 20 64 65 61 64 6c 6f cation to deadlo
3ec80 63 6b 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c ck. For example,
3ec90 20 69 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 58 if connection X
3eca0 20 69 73 20 77 61 69 74 69 6e 67 20 66 6f 72 0a is waiting for.
3ecb0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 59 27 ** connection Y'
3ecc0 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f s transaction to
3ecd0 20 62 65 20 63 6f 6e 63 6c 75 64 65 64 2c 20 61 be concluded, a
3ece0 6e 64 20 73 69 6d 69 6c 61 72 6c 79 20 63 6f 6e nd similarly con
3ecf0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 59 20 69 73 20 nection.** Y is
3ed00 77 61 69 74 69 6e 67 20 6f 6e 20 63 6f 6e 6e 65 waiting on conne
3ed10 63 74 69 6f 6e 20 58 27 73 20 74 72 61 6e 73 61 ction X's transa
3ed20 63 74 69 6f 6e 2c 20 74 68 65 6e 20 6e 65 69 74 ction, then neit
3ed30 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a her connection.*
3ed40 2a 20 77 69 6c 6c 20 70 72 6f 63 65 65 64 20 61 * will proceed a
3ed50 6e 64 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 nd the system ma
3ed60 79 20 72 65 6d 61 69 6e 20 64 65 61 64 6c 6f 63 y remain deadloc
3ed70 6b 65 64 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 ked indefinitely
3ed80 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 ..**.** To avoid
3ed90 20 74 68 69 73 20 73 63 65 6e 61 72 69 6f 2c 20 this scenario,
3eda0 74 68 65 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f the sqlite3_unlo
3edb0 63 6b 5f 6e 6f 74 69 66 79 28 29 20 70 65 72 66 ck_notify() perf
3edc0 6f 72 6d 73 20 64 65 61 64 6c 6f 63 6b 0a 2a 2a orms deadlock.**
3edd0 20 64 65 74 65 63 74 69 6f 6e 2e 20 49 66 20 61 detection. If a
3ede0 20 67 69 76 65 6e 20 63 61 6c 6c 20 74 6f 20 73 given call to s
3edf0 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f qlite3_unlock_no
3ee00 74 69 66 79 28 29 20 77 6f 75 6c 64 20 70 75 74 tify() would put
3ee10 20 74 68 65 0a 2a 2a 20 73 79 73 74 65 6d 20 69 the.** system i
3ee20 6e 20 61 20 64 65 61 64 6c 6f 63 6b 65 64 20 73 n a deadlocked s
3ee30 74 61 74 65 2c 20 74 68 65 6e 20 53 51 4c 49 54 tate, then SQLIT
3ee40 45 5f 4c 4f 43 4b 45 44 20 69 73 20 72 65 74 75 E_LOCKED is retu
3ee50 72 6e 65 64 20 61 6e 64 20 6e 6f 0a 2a 2a 20 75 rned and no.** u
3ee60 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c nlock-notify cal
3ee70 6c 62 61 63 6b 20 69 73 20 72 65 67 69 73 74 65 lback is registe
3ee80 72 65 64 2e 20 54 68 65 20 73 79 73 74 65 6d 20 red. The system
3ee90 69 73 20 73 61 69 64 20 74 6f 20 62 65 20 69 6e is said to be in
3eea0 0a 2a 2a 20 61 20 64 65 61 64 6c 6f 63 6b 65 64 .** a deadlocked
3eeb0 20 73 74 61 74 65 20 69 66 20 63 6f 6e 6e 65 63 state if connec
3eec0 74 69 6f 6e 20 41 20 68 61 73 20 72 65 67 69 73 tion A has regis
3eed0 74 65 72 65 64 20 66 6f 72 20 61 6e 20 75 6e 6c tered for an unl
3eee0 6f 63 6b 2d 6e 6f 74 69 66 79 0a 2a 2a 20 63 61 ock-notify.** ca
3eef0 6c 6c 62 61 63 6b 20 6f 6e 20 74 68 65 20 63 6f llback on the co
3ef00 6e 63 6c 75 73 69 6f 6e 20 6f 66 20 63 6f 6e 6e nclusion of conn
3ef10 65 63 74 69 6f 6e 20 42 27 73 20 74 72 61 6e 73 ection B's trans
3ef20 61 63 74 69 6f 6e 2c 20 61 6e 64 20 63 6f 6e 6e action, and conn
3ef30 65 63 74 69 6f 6e 0a 2a 2a 20 42 20 68 61 73 20 ection.** B has
3ef40 69 74 73 65 6c 66 20 72 65 67 69 73 74 65 72 65 itself registere
3ef50 64 20 66 6f 72 20 61 6e 20 75 6e 6c 6f 63 6b 2d d for an unlock-
3ef60 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 notify callback
3ef70 77 68 65 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a when connection.
3ef80 2a 2a 20 41 27 73 20 74 72 61 6e 73 61 63 74 69 ** A's transacti
3ef90 6f 6e 20 69 73 20 63 6f 6e 63 6c 75 64 65 64 2e on is concluded.
3efa0 20 49 6e 64 69 72 65 63 74 20 64 65 61 64 6c 6f Indirect deadlo
3efb0 63 6b 20 69 73 20 61 6c 73 6f 20 64 65 74 65 63 ck is also detec
3efc0 74 65 64 2c 20 73 6f 0a 2a 2a 20 74 68 65 20 73 ted, so.** the s
3efd0 79 73 74 65 6d 20 69 73 20 61 6c 73 6f 20 63 6f ystem is also co
3efe0 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 64 nsidered to be d
3eff0 65 61 64 6c 6f 63 6b 65 64 20 69 66 20 63 6f 6e eadlocked if con
3f000 6e 65 63 74 69 6f 6e 20 42 20 68 61 73 0a 2a 2a nection B has.**
3f010 20 72 65 67 69 73 74 65 72 65 64 20 66 6f 72 20 registered for
3f020 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 an unlock-notify
3f030 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 74 68 65 callback on the
3f040 20 63 6f 6e 63 6c 75 73 69 6f 6e 20 6f 66 20 63 conclusion of c
3f050 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 27 73 onnection.** C's
3f060 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 77 68 transaction, wh
3f070 65 72 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 43 ere connection C
3f080 20 69 73 20 77 61 69 74 69 6e 67 20 6f 6e 20 63 is waiting on c
3f090 6f 6e 6e 65 63 74 69 6f 6e 20 41 2e 20 41 6e 79 onnection A. Any
3f0a0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 6c 65 .** number of le
3f0b0 76 65 6c 73 20 6f 66 20 69 6e 64 69 72 65 63 74 vels of indirect
3f0c0 69 6f 6e 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e ion are allowed.
3f0d0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 22 44 .**.** <b>The "D
3f0e0 52 4f 50 20 54 41 42 4c 45 22 20 45 78 63 65 70 ROP TABLE" Excep
3f0f0 74 69 6f 6e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 57 tion</b>.**.** W
3f100 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 hen a call to [s
3f110 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 qlite3_step()] r
3f120 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4c 4f eturns SQLITE_LO
3f130 43 4b 45 44 2c 20 69 74 20 69 73 20 61 6c 6d 6f CKED, it is almo
3f140 73 74 20 0a 2a 2a 20 61 6c 77 61 79 73 20 61 70 st .** always ap
3f150 70 72 6f 70 72 69 61 74 65 20 74 6f 20 63 61 6c propriate to cal
3f160 6c 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b l sqlite3_unlock
3f170 5f 6e 6f 74 69 66 79 28 29 2e 20 54 68 65 72 65 _notify(). There
3f180 20 69 73 20 68 6f 77 65 76 65 72 2c 0a 2a 2a 20 is however,.**
3f190 6f 6e 65 20 65 78 63 65 70 74 69 6f 6e 2e 20 57 one exception. W
3f1a0 68 65 6e 20 65 78 65 63 75 74 69 6e 67 20 61 20 hen executing a
3f1b0 22 44 52 4f 50 20 54 41 42 4c 45 22 20 6f 72 20 "DROP TABLE" or
3f1c0 22 44 52 4f 50 20 49 4e 44 45 58 22 20 73 74 61 "DROP INDEX" sta
3f1d0 74 65 6d 65 6e 74 2c 0a 2a 2a 20 53 51 4c 69 74 tement,.** SQLit
3f1e0 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 65 72 e checks if ther
3f1f0 65 20 61 72 65 20 61 6e 79 20 63 75 72 72 65 6e e are any curren
3f200 74 6c 79 20 65 78 65 63 75 74 69 6e 67 20 53 45 tly executing SE
3f210 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 0a LECT statements.
3f220 2a 2a 20 74 68 61 74 20 62 65 6c 6f 6e 67 20 74 ** that belong t
3f230 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 6e 65 o the same conne
3f240 63 74 69 6f 6e 2e 20 49 66 20 74 68 65 72 65 20 ction. If there
3f250 61 72 65 2c 20 53 51 4c 49 54 45 5f 4c 4f 43 4b are, SQLITE_LOCK
3f260 45 44 20 69 73 0a 2a 2a 20 72 65 74 75 72 6e 65 ED is.** returne
3f270 64 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 d. In this case
3f280 74 68 65 72 65 20 69 73 20 6e 6f 20 22 62 6c 6f there is no "blo
3f290 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e cking connection
3f2a0 22 2c 20 73 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a ", so invoking.*
3f2b0 2a 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b * sqlite3_unlock
3f2c0 5f 6e 6f 74 69 66 79 28 29 20 72 65 73 75 6c 74 _notify() result
3f2d0 73 20 69 6e 20 74 68 65 20 75 6e 6c 6f 63 6b 2d s in the unlock-
3f2e0 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 notify callback
3f2f0 62 65 69 6e 67 0a 2a 2a 20 69 6e 76 6f 6b 65 64 being.** invoked
3f300 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 20 49 66 immediately. If
3f310 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
3f320 20 74 68 65 6e 20 72 65 2d 61 74 74 65 6d 70 74 then re-attempt
3f330 73 20 74 68 65 20 22 44 52 4f 50 20 54 41 42 4c s the "DROP TABL
3f340 45 22 0a 2a 2a 20 6f 72 20 22 44 52 4f 50 20 49 E".** or "DROP I
3f350 4e 44 45 58 22 20 71 75 65 72 79 2c 20 61 6e 20 NDEX" query, an
3f360 69 6e 66 69 6e 69 74 65 20 6c 6f 6f 70 20 6d 69 infinite loop mi
3f370 67 68 74 20 62 65 20 74 68 65 20 72 65 73 75 6c ght be the resul
3f380 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 77 61 79 t..**.** One way
3f390 20 61 72 6f 75 6e 64 20 74 68 69 73 20 70 72 6f around this pro
3f3a0 62 6c 65 6d 20 69 73 20 74 6f 20 63 68 65 63 6b blem is to check
3f3b0 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 65 72 the extended er
3f3c0 72 6f 72 20 63 6f 64 65 20 72 65 74 75 72 6e 65 ror code returne
3f3d0 64 0a 2a 2a 20 62 79 20 61 6e 20 73 71 6c 69 74 d.** by an sqlit
3f3e0 65 33 5f 73 74 65 70 28 29 20 63 61 6c 6c 2e 20 e3_step() call.
3f3f0 49 66 20 74 68 65 72 65 20 69 73 20 61 20 62 6c If there is a bl
3f400 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f ocking connectio
3f410 6e 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 65 n, then the.** e
3f420 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
3f430 64 65 20 69 73 20 73 65 74 20 74 6f 20 53 51 4c de is set to SQL
3f440 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 ITE_LOCKED_SHARE
3f450 44 43 41 43 48 45 2e 20 4f 74 68 65 72 77 69 73 DCACHE. Otherwis
3f460 65 2c 20 69 6e 0a 2a 2a 20 74 68 65 20 73 70 65 e, in.** the spe
3f470 63 69 61 6c 20 22 44 52 4f 50 20 54 41 42 4c 45 cial "DROP TABLE
3f480 2f 49 4e 44 45 58 22 20 63 61 73 65 2c 20 74 68 /INDEX" case, th
3f490 65 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 e extended error
3f4a0 20 63 6f 64 65 20 69 73 20 6a 75 73 74 20 0a 2a code is just .*
3f4b0 2a 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 2e * SQLITE_LOCKED.
3f4c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
3f4d0 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 0a 20 unlock_notify(.
3f4e0 20 73 71 6c 69 74 65 33 20 2a 70 42 6c 6f 63 6b sqlite3 *pBlock
3f4f0 65 64 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 ed,
3f500 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
3f510 57 61 69 74 69 6e 67 20 63 6f 6e 6e 65 63 74 69 Waiting connecti
3f520 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 on */. void (*x
3f530 4e 6f 74 69 66 79 29 28 76 6f 69 64 20 2a 2a 61 Notify)(void **a
3f540 70 41 72 67 2c 20 69 6e 74 20 6e 41 72 67 29 2c pArg, int nArg),
3f550 20 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 /* Callback
3f560 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f function to invo
3f570 6b 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 4e ke */. void *pN
3f580 6f 74 69 66 79 41 72 67 20 20 20 20 20 20 20 20 otifyArg
3f590 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3f5a0 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 /* Argument
3f5b0 74 6f 20 70 61 73 73 20 74 6f 20 78 4e 6f 74 69 to pass to xNoti
3f5c0 66 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 fy */.);../*.**
3f5d0 55 6e 64 6f 20 74 68 65 20 68 61 63 6b 20 74 68 Undo the hack th
3f5e0 61 74 20 63 6f 6e 76 65 72 74 73 20 66 6c 6f 61 at converts floa
3f5f0 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 70 65 73 ting point types
3f600 20 74 6f 20 69 6e 74 65 67 65 72 20 66 6f 72 0a to integer for.
3f610 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 70 72 6f ** builds on pro
3f620 63 65 73 73 6f 72 73 20 77 69 74 68 6f 75 74 20 cessors without
3f630 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 floating point s
3f640 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64 65 upport..*/.#ifde
3f650 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c f SQLITE_OMIT_FL
3f660 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 75 OATING_POINT.# u
3f670 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 65 6e 64 ndef double.#end
3f680 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c if..#ifdef __cpl
3f690 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e 64 usplus.} /* End
3f6a0 20 6f 66 20 74 68 65 20 27 65 78 74 65 72 6e 20 of the 'extern
3f6b0 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65 "C"' block */.#e
3f6c0 6e 64 69 66 0a 23 65 6e 64 69 66 0a ndif.#endif.