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 33 36 20 32 30 30 39 2f 30 n,v 1.436 2009/0
05f0: 33 2f 32 30 20 31 33 3a 31 35 3a 33 30 20 64 72 3/20 13:15:30 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 32 "3.6.12
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 32 0a 0a 2f 2a 0a 2a 2a 20 3006012../*.**
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: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4010: 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 LOCKED_SHAREDCAC
4020: 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f HE (SQLITE_
4030: 4c 4f 43 4b 45 44 20 7c 20 28 31 3c 3c 38 29 20 LOCKED | (1<<8)
4040: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 )../*.** CAPI3RE
4050: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c F: Flags For Fil
4060: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e e Open Operation
4070: 73 20 7b 48 31 30 32 33 30 7d 20 3c 48 31 31 31 s {H10230} <H111
4080: 32 30 3e 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 20> <H12700>.**.
4090: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c ** These bit val
40a0: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 ues are intended
40b0: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a for use in the.
40c0: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 ** 3rd parameter
40d0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
40e0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 _open_v2()] inte
40f0: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 rface and.** in
4100: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
4110: 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d r to the xOpen m
4120: 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 ethod of the.**
4130: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
4140: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 ject..*/.#define
4150: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 SQLITE_OPEN_REA
4160: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 DONLY 0x
4170: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 00000001.#define
4180: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 SQLITE_OPEN_REA
4190: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 DWRITE 0x
41a0: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 00000002.#define
41b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 SQLITE_OPEN_CRE
41c0: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 ATE 0x
41d0: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 00000004.#define
41e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c SQLITE_OPEN_DEL
41f0: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 ETEONCLOSE 0x
4200: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 00000008.#define
4210: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 SQLITE_OPEN_EXC
4220: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 LUSIVE 0x
4230: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 00000010.#define
4240: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 SQLITE_OPEN_MAI
4250: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 N_DB 0x
4260: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 00000100.#define
4270: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d SQLITE_OPEN_TEM
4280: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 P_DB 0x
4290: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 00000200.#define
42a0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 SQLITE_OPEN_TRA
42b0: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 NSIENT_DB 0x
42c0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 00000400.#define
42d0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 SQLITE_OPEN_MAI
42e0: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 N_JOURNAL 0x
42f0: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 00000800.#define
4300: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d SQLITE_OPEN_TEM
4310: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 P_JOURNAL 0x
4320: 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 00001000.#define
4330: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 SQLITE_OPEN_SUB
4340: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 JOURNAL 0x
4350: 30 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 00002000.#define
4360: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 SQLITE_OPEN_MAS
4370: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 TER_JOURNAL 0x
4380: 30 30 30 30 34 30 30 30 0a 23 64 65 66 69 6e 65 00004000.#define
4390: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d SQLITE_OPEN_NOM
43a0: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 UTEX 0x
43b0: 30 30 30 30 38 30 30 30 0a 23 64 65 66 69 6e 65 00008000.#define
43c0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c SQLITE_OPEN_FUL
43d0: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78 LMUTEX 0x
43e0: 30 30 30 31 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 00010000../*.**
43f0: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 CAPI3REF: Device
4400: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 Characteristics
4410: 20 7b 48 31 30 32 34 30 7d 20 3c 48 31 31 31 32 {H10240} <H1112
4420: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 0>.**.** The xDe
4430: 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73 viceCapabilities
4440: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b method of the [
4450: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
4460: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 ds].** object re
4470: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 turns an integer
4480: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 which is a vect
4490: 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a or of the these.
44a0: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 ** bit values ex
44b0: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 pressing I/O cha
44c0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 racteristics of
44d0: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 the mass storage
44e0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 .** device that
44f0: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 holds the file t
4500: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 hat the [sqlite3
4510: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 _io_methods].**
4520: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a refers to..**.**
4530: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
4540: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 P_ATOMIC propert
4550: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c y means that all
4560: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e writes of.** an
4570: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 y size are atomi
4580: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 c. The SQLITE_I
4590: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 OCAP_ATOMICnnn v
45a0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 alues.** mean th
45b0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f at writes of blo
45c0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e cks that are nnn
45d0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 bytes in size a
45e0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 nd.** are aligne
45f0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 d to an address
4600: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 which is an inte
4610: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a ger multiple of.
4620: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 ** nnn are atomi
4630: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 c. The SQLITE_I
4640: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 OCAP_SAFE_APPEND
4650: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 value means.**
4660: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 that when data i
4670: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 s appended to a
4680: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 file, the data i
4690: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 s appended.** fi
46a0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a rst then the siz
46b0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 e of the file is
46c0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 extended, never
46d0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 the other.** wa
46e0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 y around. The S
46f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
4700: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 ENTIAL property
4710: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e means that.** in
4720: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 formation is wri
4730: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 tten to disk in
4740: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 the same order a
4750: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 s calls.** to xW
4760: 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 rite()..*/.#defi
4770: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
4780: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 ATOMIC
4790: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 0x00000001.#defi
47a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
47b0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 ATOMIC512
47c0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 0x00000002.#defi
47d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
47e0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 ATOMIC1K
47f0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 0x00000004.#defi
4800: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
4810: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 ATOMIC2K
4820: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 0x00000008.#defi
4830: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
4840: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 ATOMIC4K
4850: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 0x00000010.#defi
4860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
4870: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 ATOMIC8K
4880: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 0x00000020.#defi
4890: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
48a0: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 ATOMIC16K
48b0: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 0x00000040.#defi
48c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
48d0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 ATOMIC32K
48e0: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 0x00000080.#defi
48f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
4900: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 ATOMIC64K
4910: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 0x00000100.#defi
4920: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
4930: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 SAFE_APPEND
4940: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 0x00000200.#defi
4950: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
4960: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 SEQUENTIAL
4970: 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 0x00000400../*.*
4980: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 * CAPI3REF: File
4990: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 Locking Levels
49a0: 7b 48 31 30 32 35 30 7d 20 3c 48 31 31 31 32 30 {H10250} <H11120
49b0: 3e 20 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a > <H11310>.**.**
49c0: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 SQLite uses one
49d0: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 of these intege
49e0: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 r values as the
49f0: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 second.** argume
4a00: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d nt to calls it m
4a10: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 akes to the xLoc
4a20: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 k() and xUnlock(
4a30: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 ) methods.** of
4a40: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d an [sqlite3_io_m
4a50: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a ethods] object..
4a60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4a70: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 E_LOCK_NONE
4a80: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 0.#define S
4a90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
4aa0: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 D 1.#defi
4ab0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 ne SQLITE_LOCK_R
4ac0: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 ESERVED 2.#
4ad0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
4ae0: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 CK_PENDING
4af0: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 3.#define SQLIT
4b00: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 E_LOCK_EXCLUSIVE
4b10: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 4../*.** CA
4b20: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e PI3REF: Synchron
4b30: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 ization Type Fla
4b40: 67 73 20 7b 48 31 30 32 36 30 7d 20 3c 48 31 31 gs {H10260} <H11
4b50: 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 120>.**.** When
4b60: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 SQLite invokes t
4b70: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f he xSync() metho
4b80: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 d of an.** [sqli
4b90: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
4ba0: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 object it uses a
4bb0: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a combination of.
4bc0: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 ** these integer
4bd0: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 values as the s
4be0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a econd argument..
4bf0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 **.** When the S
4c00: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f QLITE_SYNC_DATAO
4c10: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 NLY flag is used
4c20: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 , it means that
4c30: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 the.** sync oper
4c40: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 ation only needs
4c50: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 to flush data t
4c60: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 o mass storage.
4c70: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d Inode.** inform
4c80: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 ation need not b
4c90: 65 20 66 6c 75 73 68 65 64 2e 20 54 68 65 20 53 e flushed. The S
4ca0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 QLITE_SYNC_NORMA
4cb0: 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 L flag means.**
4cc0: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 to use normal fs
4cd0: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e ync() semantics.
4ce0: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 The SQLITE_SYNC
4cf0: 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e 73 _FULL flag means
4d00: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f .** to use Mac O
4d10: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 S X style fullsy
4d20: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 nc instead of fs
4d30: 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e ync()..*/.#defin
4d40: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f e SQLITE_SYNC_NO
4d50: 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 RMAL 0x00
4d60: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 002.#define SQLI
4d70: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 TE_SYNC_FULL
4d80: 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 0x00003.#d
4d90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e efine SQLITE_SYN
4da0: 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 C_DATAONLY
4db0: 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 0x00010../*.** C
4dc0: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 API3REF: OS Inte
4dd0: 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 rface Open File
4de0: 48 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 Handle {H11110}
4df0: 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 <S20110>.**.** A
4e00: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d n [sqlite3_file]
4e10: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e object represen
4e20: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 ts an open file
4e30: 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 in the OS.** int
4e40: 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49 erface layer. I
4e50: 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 ndividual OS int
4e60: 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 erface implement
4e70: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 ations will.** w
4e80: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 ant to subclass
4e90: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 this object by a
4ea0: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f ppending additio
4eb0: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f nal fields.** fo
4ec0: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e r their own use.
4ed0: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 The pMethods e
4ee0: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 ntry is a pointe
4ef0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 r to an.** [sqli
4f00: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
4f10: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 object that defi
4f20: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 nes methods for
4f30: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f performing.** I/
4f40: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 O operations on
4f50: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a the open file..*
4f60: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
4f70: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 sqlite3_file sq
4f80: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 lite3_file;.stru
4f90: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 ct sqlite3_file
4fa0: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 {. const struct
4fb0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 sqlite3_io_meth
4fc0: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 ods *pMethods;
4fd0: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 /* Methods for a
4fe0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d n open file */.}
4ff0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
5000: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 F: OS Interface
5010: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 File Virtual Met
5020: 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 hods Object {H11
5030: 31 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 120} <S20110>.**
5040: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f .** Every file o
5050: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 pened by the [sq
5060: 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e lite3_vfs] xOpen
5070: 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 method populate
5080: 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s an.** [sqlite3
5090: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f _file] object (o
50a0: 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 r, more commonly
50b0: 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 , a subclass of
50c0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
50d0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 file] object) wi
50e0: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 th a pointer to
50f0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
5100: 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 his object..** T
5110: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e his object defin
5120: 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 es the methods u
5130: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 sed to perform v
5140: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e arious operation
5150: 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 s.** against the
5160: 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 open file repre
5170: 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 sented by the [s
5180: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
5190: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ect..**.** The f
51a0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f lags argument to
51b0: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e xSync may be on
51c0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e e of [SQLITE_SYN
51d0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 C_NORMAL] or.**
51e0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c [SQLITE_SYNC_FUL
51f0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 L]. The first c
5200: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 hoice is the nor
5210: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 mal fsync()..**
5220: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 The second choic
5230: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 e is a Mac OS X
5240: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 style fullsync.
5250: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e The [SQLITE_SYN
5260: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 C_DATAONLY].** f
5270: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 lag may be ORed
5280: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 in to indicate t
5290: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 hat only the dat
52a0: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a a of the file.**
52b0: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f and not its ino
52c0: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 de needs to be s
52d0: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ynced..**.** The
52e0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 integer values
52f0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 to xLock() and x
5300: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 Unlock() are one
5310: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c of.** <ul>.** <
5320: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
5330: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 _NONE],.** <li>
5340: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 [SQLITE_LOCK_SHA
5350: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 RED],.** <li> [S
5360: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 QLITE_LOCK_RESER
5370: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 VED],.** <li> [S
5380: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 QLITE_LOCK_PENDI
5390: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 NG], or.** <li>
53a0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 [SQLITE_LOCK_EXC
53b0: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c LUSIVE]..** </ul
53c0: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 >.** xLock() inc
53d0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e reases the lock.
53e0: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 xUnlock() decre
53f0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a ases the lock..*
5400: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 * The xCheckRese
5410: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f rvedLock() metho
5420: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 d checks whether
5430: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f any database co
5440: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 nnection,.** eit
5450: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 her in this proc
5460: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f ess or in some o
5470: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 ther process, is
5480: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 holding a RESER
5490: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c VED,.** PENDING,
54a0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f or EXCLUSIVE lo
54b0: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 ck on the file.
54c0: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 It returns true
54d0: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f .** if such a lo
54e0: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 ck exists and fa
54f0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a lse otherwise..*
5500: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f *.** The xFileCo
5510: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 ntrol() method i
5520: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 s a generic inte
5530: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 rface that allow
5540: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 s custom.** VFS
5550: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
5560: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 to directly cont
5570: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 rol an open file
5580: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
5590: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
55a0: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 rol()] interface
55b0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f . The second "o
55c0: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 p" argument is a
55d0: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 n.** integer opc
55e0: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 ode. The third
55f0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 argument is a ge
5600: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e neric pointer in
5610: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 tended to.** poi
5620: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 nt to a structur
5630: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 e that may conta
5640: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 in arguments or
5650: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 space in which t
5660: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 o.** write retur
5670: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e n values. Poten
5680: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 tial uses for xF
5690: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 ileControl() mig
56a0: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f ht be.** functio
56b0: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f ns to enable blo
56c0: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 cking locks with
56d0: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 timeouts, to ch
56e0: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b ange the.** lock
56f0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f ing strategy (fo
5700: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 r example to use
5710: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 dot-file locks)
5720: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 , to inquire.**
5730: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 about the status
5740: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 of a lock, or t
5750: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f o break stale lo
5760: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 cks. The SQLite
5770: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 .** core reserve
5780: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 s all opcodes le
5790: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 ss than 100 for
57a0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 its own use..**
57b0: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f A [SQLITE_FCNTL_
57c0: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 LOCKSTATE | list
57d0: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 of opcodes] les
57e0: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 s than 100 is av
57f0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c ailable..** Appl
5800: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 ications that de
5810: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 fine a custom xF
5820: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
5830: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 d should use opc
5840: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 odes.** greater
5850: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 than 100 to avoi
5860: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a d conflicts..**.
5870: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 ** The xSectorSi
5880: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 ze() method retu
5890: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 rns the sector s
58a0: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 ize of the.** de
58b0: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c vice that underl
58c0: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 ies the file. T
58d0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 he sector size i
58e0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d s the.** minimum
58f0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 write that can
5900: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 be performed wit
5910: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a hout disturbing.
5920: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 ** other bytes i
5930: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 n the file. The
5940: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 xDeviceCharacte
5950: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 ristics().** met
5960: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 hod returns a bi
5970: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 t vector describ
5980: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 ing behaviors of
5990: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 the.** underlyi
59a0: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a ng device:.**.**
59b0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 <ul>.** <li> [S
59c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
59d0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c IC].** <li> [SQL
59e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
59f0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 512].** <li> [SQ
5a00: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
5a10: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C1K].** <li> [SQ
5a20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
5a30: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C2K].** <li> [SQ
5a40: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
5a50: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C4K].** <li> [SQ
5a60: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
5a70: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C8K].** <li> [SQ
5a80: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
5a90: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C16K].** <li> [S
5aa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5ab0: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC32K].** <li> [
5ac0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5ad0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC64K].** <li>
5ae0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 [SQLITE_IOCAP_SA
5af0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c FE_APPEND].** <l
5b00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
5b10: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 _SEQUENTIAL].**
5b20: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 </ul>.**.** The
5b30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5b40: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 MIC property mea
5b50: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 ns that all writ
5b60: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a es of.** any siz
5b70: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 e are atomic. T
5b80: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
5b90: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 ATOMICnnn values
5ba0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 .** mean that wr
5bb0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 ites of blocks t
5bc0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 hat are nnn byte
5bd0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a s in size and.**
5be0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 are aligned to
5bf0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 an address which
5c00: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d is an integer m
5c10: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e ultiple of.** nn
5c20: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 n are atomic. T
5c30: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
5c40: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 SAFE_APPEND valu
5c50: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 e means.** that
5c60: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 when data is app
5c70: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c ended to a file,
5c80: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 the data is app
5c90: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 ended.** first t
5ca0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 hen the size of
5cb0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 the file is exte
5cc0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 nded, never the
5cd0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f other.** way aro
5ce0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 und. The SQLITE
5cf0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
5d00: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 L property means
5d10: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 that.** informa
5d20: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 tion is written
5d30: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 to disk in the s
5d40: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c ame order as cal
5d50: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 ls.** to xWrite(
5d60: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 )..**.** If xRea
5d70: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 d() returns SQLI
5d80: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 TE_IOERR_SHORT_R
5d90: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f EAD it must also
5da0: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 fill.** in the
5db0: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 unread portions
5dc0: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 of the buffer wi
5dd0: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 th zeros. A VFS
5de0: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 that.** fails t
5df0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 o zero-fill shor
5e00: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 t reads might se
5e10: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 em to work. How
5e20: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 ever,.** failure
5e30: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 to zero-fill sh
5e40: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 ort reads will e
5e50: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 ventually lead t
5e60: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f o.** database co
5e70: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 rruption..*/.typ
5e80: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
5e90: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 te3_io_methods s
5ea0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
5eb0: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 s;.struct sqlite
5ec0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 3_io_methods {.
5ed0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 int iVersion;.
5ee0: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 int (*xClose)(s
5ef0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
5f00: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 int (*xRead)(sq
5f10: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 lite3_file*, voi
5f20: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 d*, int iAmt, sq
5f30: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 lite3_int64 iOfs
5f40: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 t);. int (*xWri
5f50: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 te)(sqlite3_file
5f60: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
5f70: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 int iAmt, sqlite
5f80: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 3_int64 iOfst);.
5f90: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 int (*xTruncat
5fa0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
5fb0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
5fc0: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 size);. int (*x
5fd0: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 Sync)(sqlite3_fi
5fe0: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b le*, int flags);
5ff0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 . int (*xFileSi
6000: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ze)(sqlite3_file
6010: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
6020: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 *pSize);. int
6030: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 (*xLock)(sqlite3
6040: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 _file*, int);.
6050: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 int (*xUnlock)(s
6060: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
6070: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 t);. int (*xChe
6080: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 ckReservedLock)(
6090: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
60a0: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 nt *pResOut);.
60b0: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 int (*xFileContr
60c0: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ol)(sqlite3_file
60d0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 *, int op, void
60e0: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a *pArg);. int (*
60f0: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c xSectorSize)(sql
6100: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 ite3_file*);. i
6110: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 nt (*xDeviceChar
6120: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c acteristics)(sql
6130: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f ite3_file*);. /
6140: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 * Additional met
6150: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 hods may be adde
6160: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
6170: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a ases */.};../*.*
6180: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e * CAPI3REF: Stan
6190: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f dard File Contro
61a0: 6c 20 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 l Opcodes {H1131
61b0: 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 0} <S30800>.**.*
61c0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 * These integer
61d0: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 constants are op
61e0: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 codes for the xF
61f0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
6200: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c d.** of the [sql
6210: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
6220: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 object and for
6230: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
6240: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 e_control()].**
6250: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
6260: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
6270: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 TL_LOCKSTATE] op
6280: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 code is used for
6290: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 debugging. Thi
62a0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 s.** opcode caus
62b0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 es the xFileCont
62c0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 rol method to wr
62d0: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 ite the current
62e0: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 state of.** the
62f0: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 lock (one of [SQ
6300: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c LITE_LOCK_NONE],
6310: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 [SQLITE_LOCK_SH
6320: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 ARED],.** [SQLIT
6330: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d E_LOCK_RESERVED]
6340: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 , [SQLITE_LOCK_P
6350: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c ENDING], or [SQL
6360: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 ITE_LOCK_EXCLUSI
6370: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 VE]).** into an
6380: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 integer that the
6390: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 pArg argument p
63a0: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 oints to. This c
63b0: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 apability.** is
63c0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 used during test
63d0: 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 ing and only nee
63e0: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 ds to be support
63f0: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 ed when SQLITE_T
6400: 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 EST.** is define
6410: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 d..*/.#define SQ
6420: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 LITE_FCNTL_LOCKS
6430: 54 41 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 TATE 1.#d
6440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 efine SQLITE_GET
6450: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 _LOCKPROXYFILE
6460: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
6470: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f LITE_SET_LOCKPRO
6480: 58 59 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 XYFILE 3.#d
6490: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 efine SQLITE_LAS
64a0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 T_ERRNO
64b0: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 4../*.** CAP
64c0: 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e I3REF: Mutex Han
64d0: 64 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 dle {H17110} <S2
64e0: 30 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0130>.**.** The
64f0: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 mutex module wit
6500: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e hin SQLite defin
6510: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 es [sqlite3_mute
6520: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 x] to be an.** a
6530: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 bstract type for
6540: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e a mutex object.
6550: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 The SQLite cor
6560: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a e never looks.**
6570: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c at the internal
6580: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
6590: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d of an [sqlite3_m
65a0: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a utex]. It only.
65b0: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f ** deals with po
65c0: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 inters to the [s
65d0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 qlite3_mutex] ob
65e0: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 ject..**.** Mute
65f0: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 xes are created
6600: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d using [sqlite3_m
6610: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a utex_alloc()]..*
6620: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
6630: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 sqlite3_mutex s
6640: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f qlite3_mutex;../
6650: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
6660: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 S Interface Obje
6670: 63 74 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 ct {H11140} <S20
6680: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 100>.**.** An in
6690: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 stance of the sq
66a0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 lite3_vfs object
66b0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 defines the int
66c0: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a erface between.*
66d0: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 * the SQLite cor
66e0: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c e and the underl
66f0: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 ying operating s
6700: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 ystem. The "vfs
6710: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 ".** in the name
6720: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 of the object s
6730: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 tands for "virtu
6740: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e al file system".
6750: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 .**.** The value
6760: 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e of the iVersion
6770: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 field is initia
6780: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 lly 1 but may be
6790: 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 larger in.** fu
67a0: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
67b0: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 SQLite. Additi
67c0: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 onal fields may
67d0: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 be appended to t
67e0: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 his.** object wh
67f0: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 en the iVersion
6800: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 value is increas
6810: 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 ed. Note that t
6820: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 he structure.**
6830: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 of the sqlite3_v
6840: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 fs object change
6850: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 s in the transac
6860: 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 tion between.**
6870: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
6880: 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 .5.9 and 3.6.0 a
6890: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 nd yet the iVers
68a0: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f ion field was no
68b0: 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a t.** modified..*
68c0: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c *.** The szOsFil
68d0: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 e field is the s
68e0: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c ize of the subcl
68f0: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 assed [sqlite3_f
6900: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 ile].** structur
6910: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 e used by this V
6920: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 FS. mxPathname
6930: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c is the maximum l
6940: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 ength of.** a pa
6950: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 thname in this V
6960: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 FS..**.** Regist
6970: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 ered sqlite3_vfs
6980: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 objects are kep
6990: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 t on a linked li
69a0: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 st formed by.**
69b0: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 the pNext pointe
69c0: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 r. The [sqlite3
69d0: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d _vfs_register()]
69e0: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
69f0: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 _vfs_unregister(
6a00: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 )] interfaces ma
6a10: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a nage this list.*
6a20: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 * in a thread-sa
6a30: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 fe way. The [sq
6a40: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 lite3_vfs_find()
6a50: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 ] interface.** s
6a60: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 earches the list
6a70: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 . Neither the a
6a80: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 pplication code
6a90: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 nor the VFS.** i
6aa0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 mplementation sh
6ab0: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 ould use the pNe
6ac0: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a xt pointer..**.*
6ad0: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c * The pNext fiel
6ae0: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 d is the only fi
6af0: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 eld in the sqlit
6b00: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 e3_vfs.** struct
6b10: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 ure that SQLite
6b20: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 will ever modify
6b30: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f . SQLite will o
6b40: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 nly access.** or
6b50: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 modify this fie
6b60: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 ld while holding
6b70: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 a particular st
6b80: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 atic mutex..** T
6b90: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
6ba0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 hould never modi
6bb0: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 fy anything with
6bc0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 in the sqlite3_v
6bd0: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 fs.** object onc
6be0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 e the object has
6bf0: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 been registered
6c00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d ..**.** The zNam
6c10: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 e field holds th
6c20: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 e name of the VF
6c30: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e S module. The n
6c40: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 ame must.** be u
6c50: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c nique across all
6c60: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a VFS modules..**
6c70: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 .** SQLite will
6c80: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 guarantee that t
6c90: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 he zFilename par
6ca0: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a ameter to xOpen.
6cb0: 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e ** is either a N
6cc0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 ULL pointer or s
6cd0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a tring obtained.*
6ce0: 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 * from xFullPath
6cf0: 6e 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 name(). SQLite
6d00: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 further guarante
6d10: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 es that.** the s
6d20: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 tring will be va
6d30: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 lid and unchange
6d40: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 d until xClose()
6d50: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 is.** called. B
6d60: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 ecause of the pr
6d70: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c evious sentense,
6d80: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 .** the [sqlite3
6d90: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c _file] can safel
6da0: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 y store a pointe
6db0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 r to the.** file
6dc0: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 name if it needs
6dd0: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 to remember the
6de0: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f filename for so
6df0: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 me reason..** If
6e00: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 the zFilename p
6e10: 61 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 arameter is xOpe
6e20: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e n is a NULL poin
6e30: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a ter then xOpen.*
6e40: 2a 20 6d 75 73 74 20 69 6e 76 69 74 65 20 69 74 * must invite it
6e50: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 s own temporary
6e60: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c name for the fil
6e70: 65 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 e. Whenever the
6e80: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 .** xFilename p
6e90: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c arameter is NULL
6ea0: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 it will also be
6eb0: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 the case that t
6ec0: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 he.** flags para
6ed0: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 meter will inclu
6ee0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f de [SQLITE_OPEN_
6ef0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a DELETEONCLOSE]..
6f00: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 **.** The flags
6f10: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 argument to xOpe
6f20: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c n() includes all
6f30: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 bits set in.**
6f40: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 the flags argume
6f50: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f nt to [sqlite3_o
6f60: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 pen_v2()]. Or i
6f70: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 f [sqlite3_open(
6f80: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 )].** or [sqlite
6f90: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 3_open16()] is u
6fa0: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 sed, then flags
6fb0: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 includes at leas
6fc0: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 t.** [SQLITE_OPE
6fd0: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b N_READWRITE] | [
6fe0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
6ff0: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 TE]. .** If xOpe
7000: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 n() opens a file
7010: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 read-only then
7020: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 it sets *pOutFla
7030: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 gs to.** include
7040: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 [SQLITE_OPEN_RE
7050: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 ADONLY]. Other
7060: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 bits in *pOutFla
7070: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a gs may be set..*
7080: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c *.** SQLite will
7090: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 also add one of
70a0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 the following f
70b0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 lags to the xOpe
70c0: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 n().** call, dep
70d0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 ending on the ob
70e0: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 ject being opene
70f0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a d:.**.** <ul>.**
7100: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
7110: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 PEN_MAIN_DB].**
7120: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
7130: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d EN_MAIN_JOURNAL]
7140: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
7150: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a E_OPEN_TEMP_DB].
7160: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
7170: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e _OPEN_TEMP_JOURN
7180: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
7190: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 LITE_OPEN_TRANSI
71a0: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 ENT_DB].** <li>
71b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 [SQLITE_OPEN_SU
71c0: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 BJOURNAL].** <li
71d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
71e0: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a MASTER_JOURNAL].
71f0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 ** </ul>.**.** T
7200: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c he file I/O impl
7210: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 ementation can u
7220: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 se the object ty
7230: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 pe flags to.** c
7240: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 hange the way it
7250: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 deals with file
7260: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c s. For example,
7270: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a an application.
7280: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 ** that does not
7290: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 care about cras
72a0: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f h recovery or ro
72b0: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b llback might mak
72c0: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 e.** the open of
72d0: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 a journal file
72e0: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 a no-op. Writes
72f0: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c to this journal
7300: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 would.** also b
7310: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e e no-ops, and an
7320: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 y attempt to rea
7330: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f d the journal wo
7340: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 uld return.** SQ
7350: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 LITE_IOERR. Or
7360: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 the implementati
7370: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 on might recogni
7380: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 ze that a databa
7390: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 se.** file will
73a0: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c be doing page-al
73b0: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 igned sector rea
73c0: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e ds and writes in
73d0: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 a random.** ord
73e0: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 er and set up it
73f0: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 s I/O subsystem
7400: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a accordingly..**.
7410: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 ** SQLite might
7420: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 also add one of
7430: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c the following fl
7440: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e ags to the xOpen
7450: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c method:.**.** <
7460: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ul>.** <li> [SQL
7470: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
7480: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 NCLOSE].** <li>
7490: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 [SQLITE_OPEN_EXC
74a0: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e LUSIVE].** </ul>
74b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
74c0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
74d0: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e CLOSE] flag mean
74e0: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c s the file shoul
74f0: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 d be.** deleted
7500: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 when it is close
7510: 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f d. The [SQLITE_
7520: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
7530: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 SE].** will be s
7540: 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 et for TEMP dat
7550: 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 abases, journals
7560: 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 and for subjour
7570: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nals..**.** The
7580: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 [SQLITE_OPEN_EXC
7590: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 LUSIVE] flag mea
75a0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 ns the file shou
75b0: 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 ld be opened.**
75c0: 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 for exclusive ac
75d0: 63 65 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67 cess. This flag
75e0: 20 69 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 is set for all
75f0: 66 69 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 files except.**
7600: 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 for the main dat
7610: 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a abase file..**.*
7620: 2a 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 * At least szOsF
7630: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d ile bytes of mem
7640: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 ory are allocate
7650: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 d by SQLite.** t
7660: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c o hold the [sql
7670: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 ite3_file] struc
7680: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 ture passed as t
7690: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 he third.** argu
76a0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 ment to xOpen.
76b0: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 The xOpen method
76c0: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 does not have t
76d0: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 o.** allocate th
76e0: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 e structure; it
76f0: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c should just fill
7700: 20 69 74 20 69 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 it in..**.** Th
7710: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
7720: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 to xAccess() ma
7730: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 y be [SQLITE_ACC
7740: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 ESS_EXISTS].** t
7750: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 o test for the e
7760: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 xistence of a fi
7770: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 le, or [SQLITE_A
7780: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d CCESS_READWRITE]
7790: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 to.** test whet
77a0: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 her a file is re
77b0: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 adable and writa
77c0: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f ble, or [SQLITE_
77d0: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 ACCESS_READ].**
77e0: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 to test whether
77f0: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 a file is at lea
7800: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 st readable. T
7810: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 he file can be a
7820: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a .** directory..*
7830: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c *.** SQLite will
7840: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 always allocate
7850: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 at least mxPath
7860: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 name+1 bytes for
7870: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 the.** output b
7880: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e uffer xFullPathn
7890: 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 ame. The exact
78a0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 size of the outp
78b0: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 ut buffer.** is
78c0: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 also passed as a
78d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f parameter to bo
78e0: 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 th methods. If
78f0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 the output buffe
7900: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 r.** is not larg
7910: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 e enough, [SQLIT
7920: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 E_CANTOPEN] shou
7930: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 ld be returned.
7940: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a Since this is.**
7950: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 handled as a fa
7960: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c tal error by SQL
7970: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 ite, vfs impleme
7980: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ntations should
7990: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 endeavor.** to p
79a0: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 revent this by s
79b0: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d etting mxPathnam
79c0: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e e to a sufficien
79d0: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e tly large value.
79e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 .**.** The xRand
79f0: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 omness(), xSleep
7a00: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 (), and xCurrent
7a10: 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65 Time() interface
7a20: 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 s.** are not str
7a30: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 ictly a part of
7a40: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 the filesystem,
7a50: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 but they are.**
7a60: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 included in the
7a70: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f VFS structure fo
7a80: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a r completeness..
7a90: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 ** The xRandomne
7aa0: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 ss() function at
7ab0: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e tempts to return
7ac0: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a nBytes bytes.**
7ad0: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 of good-quality
7ae0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f randomness into
7af0: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 zOut. The retu
7b00: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 rn value is.** t
7b10: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 he actual number
7b20: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e of bytes of ran
7b30: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 domness obtained
7b40: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 ..** The xSleep(
7b50: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 ) method causes
7b60: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 the calling thre
7b70: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 ad to sleep for
7b80: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 at.** least the
7b90: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 number of micros
7ba0: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 econds given. T
7bb0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 he xCurrentTime(
7bc0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 ).** method retu
7bd0: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 rns a Julian Day
7be0: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 Number for the
7bf0: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 current date and
7c00: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 time..**.*/.typ
7c10: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
7c20: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f te3_vfs sqlite3_
7c30: 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 vfs;.struct sqli
7c40: 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 te3_vfs {. int
7c50: 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 iVersion;
7c60: 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 /* Structur
7c70: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 e version number
7c80: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 */. int szOsFi
7c90: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f le; /
7ca0: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 * Size of subcla
7cb0: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c ssed sqlite3_fil
7cc0: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 e */. int mxPat
7cd0: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 hname;
7ce0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 /* Maximum file
7cf0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 pathname length
7d00: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 */. sqlite3_vfs
7d10: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a *pNext; /*
7d20: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 Next registered
7d30: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 VFS */. const
7d40: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 char *zName;
7d50: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 /* Name of th
7d60: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 is virtual file
7d70: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 system */. void
7d80: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 *pAppData;
7d90: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 /* Pointer
7da0: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 to application-s
7db0: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a pecific data */.
7dc0: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 int (*xOpen)(s
7dd0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
7de0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
7df0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 sqlite3_file*,.
7e00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e in
7e10: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f t flags, int *pO
7e20: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 utFlags);. int
7e30: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 (*xDelete)(sqlit
7e40: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
7e50: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 har *zName, int
7e60: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 syncDir);. int
7e70: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 (*xAccess)(sqlit
7e80: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
7e90: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 har *zName, int
7ea0: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 flags, int *pRes
7eb0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 Out);. int (*xF
7ec0: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c ullPathname)(sql
7ed0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
7ee0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
7ef0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f t nOut, char *zO
7f00: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 ut);. void *(*x
7f10: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f DlOpen)(sqlite3_
7f20: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
7f30: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 *zFilename);.
7f40: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 void (*xDlError)
7f50: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
7f60: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a nt nByte, char *
7f70: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 zErrMsg);. void
7f80: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c (*(*xDlSym)(sql
7f90: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c ite3_vfs*,void*,
7fa0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 const char *zSy
7fb0: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 mbol))(void);.
7fc0: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 void (*xDlClose)
7fd0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 (sqlite3_vfs*, v
7fe0: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 oid*);. int (*x
7ff0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 Randomness)(sqli
8000: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 te3_vfs*, int nB
8010: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 yte, char *zOut)
8020: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 ;. int (*xSleep
8030: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
8040: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 int microseconds
8050: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 );. int (*xCurr
8060: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 entTime)(sqlite3
8070: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b _vfs*, double*);
8080: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 . int (*xGetLas
8090: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f tError)(sqlite3_
80a0: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 vfs*, int, char
80b0: 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 *);. /* New fie
80c0: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e lds may be appen
80d0: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 ded in figure ve
80e0: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 rsions. The iVe
80f0: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 rsion. ** value
8100: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 will increment
8110: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 whenever this ha
8120: 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a ppens. */.};../*
8130: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c .** CAPI3REF: Fl
8140: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 ags for the xAcc
8150: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b ess VFS method {
8160: 48 31 31 31 39 30 7d 20 3c 48 31 31 31 34 30 3e H11190} <H11140>
8170: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 .**.** These int
8180: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 eger constants c
8190: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 an be used as th
81a0: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
81b0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 r to.** the xAcc
81c0: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e ess method of an
81d0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
81e0: 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 bject. {END} Th
81f0: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 ey determine.**
8200: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 what kind of per
8210: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 missions the xAc
8220: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c cess method is l
8230: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 ooking for..** W
8240: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ith SQLITE_ACCES
8250: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 S_EXISTS, the xA
8260: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 ccess method.**
8270: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 simply checks wh
8280: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 ether the file e
8290: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 xists..** With S
82a0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
82b0: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 DWRITE, the xAcc
82c0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 ess method.** ch
82d0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 ecks whether the
82e0: 20 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 file is both re
82f0: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 adable and writa
8300: 62 6c 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c ble..** With SQL
8310: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c ITE_ACCESS_READ,
8320: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
8330: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 hod.** checks wh
8340: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 ether the file i
8350: 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 s readable..*/.#
8360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
8370: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 CESS_EXISTS 0
8380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8390: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
83a0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
83b0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 E_ACCESS_READ
83c0: 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 2../*.** CAPI
83d0: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 3REF: Initialize
83e0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 The SQLite Libr
83f0: 61 72 79 20 7b 48 31 30 31 33 30 7d 20 3c 53 32 ary {H10130} <S2
8400: 30 30 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0000><S30100>.**
8410: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
8420: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
8430: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 tine initializes
8440: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c the.** SQLite l
8450: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c ibrary. The sql
8460: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
8470: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c routine.** deall
8480: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 ocates any resou
8490: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 rces that were a
84a0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 llocated by sqli
84b0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
84c0: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 ..**.** A call t
84d0: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 o sqlite3_initia
84e0: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 lize() is an "ef
84f0: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 fective" call if
8500: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 it is.** the fi
8510: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 rst time sqlite3
8520: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
8530: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 invoked during
8540: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a the lifetime of.
8550: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 ** the process,
8560: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 or if it is the
8570: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 first time sqlit
8580: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
8590: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f is invoked.** fo
85a0: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 llowing a call t
85b0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
85c0: 77 6e 28 29 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 wn(). Only an e
85d0: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a ffective call.**
85e0: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 of sqlite3_init
85f0: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e ialize() does an
8600: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e y initialization
8610: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c . All other cal
8620: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 ls.** are harmle
8630: 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a ss no-ops..**.**
8640: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 Among other thi
8650: 6e 67 73 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 ngs, sqlite3_ini
8660: 74 69 61 6c 69 7a 65 28 29 20 73 68 61 6c 6c 20 tialize() shall
8670: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 invoke.** sqlite
8680: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 3_os_init(). Si
8690: 6d 69 6c 61 72 6c 79 2c 20 73 71 6c 69 74 65 33 milarly, sqlite3
86a0: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 _shutdown().** s
86b0: 68 61 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 hall invoke sqli
86c0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a te3_os_end()..**
86d0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
86e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
86f0: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 tine returns [SQ
8700: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
8710: 65 73 73 2e 0a 2a 2a 20 49 66 20 66 6f 72 20 73 ess..** If for s
8720: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 ome reason, sqli
8730: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
8740: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e is unable to in
8750: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 itialize.** the
8760: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 library (perhaps
8770: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f it is unable to
8780: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 allocate a need
8790: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 ed resource such
87a0: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 .** as a mutex)
87b0: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 it returns an [e
87c0: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 rror code] other
87d0: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b than [SQLITE_OK
87e0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ]..**.** The sql
87f0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
8800: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c ) routine is cal
8810: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 led internally b
8820: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 y many other.**
8830: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
8840: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 s so that an app
8850: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 lication usually
8860: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
8870: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 o.** invoke sqli
8880: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
8890: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 directly. For
88a0: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 example, [sqlite
88b0: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 3_open()].** cal
88c0: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ls sqlite3_initi
88d0: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 alize() so the S
88e0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 QLite library wi
88f0: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 ll be automatica
8900: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a lly.** initializ
8910: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 ed when [sqlite3
8920: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c _open()] is call
8930: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 ed if it has not
8940: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a be initialized.
8950: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77 ** already. How
8960: 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 ever, if SQLite
8970: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
8980: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 the [SQLITE_OMI
8990: 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 T_AUTOINIT].** c
89a0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
89b0: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 on, then the aut
89c0: 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 omatic calls to
89d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
89e0: 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 ze().** are omit
89f0: 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c ted and the appl
8a00: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c ication must cal
8a10: 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 l sqlite3_initia
8a20: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a lize() directly.
8a30: 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e ** prior to usin
8a40: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 g any other SQLi
8a50: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 te interface. F
8a60: 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 or maximum porta
8a70: 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 bility,.** it is
8a80: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 recommended tha
8a90: 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 t applications a
8aa0: 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c lways invoke sql
8ab0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
8ac0: 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 ).** directly pr
8ad0: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 ior to using any
8ae0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
8af0: 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 terface. Future
8b00: 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 releases.** of
8b10: 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 SQLite may requi
8b20: 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 re this. In oth
8b30: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 er words, the be
8b40: 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 havior exhibited
8b50: 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 .** when SQLite
8b60: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
8b70: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 [SQLITE_OMIT_AU
8b80: 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 TOINIT] might be
8b90: 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 come the.** defa
8ba0: 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 ult behavior in
8bb0: 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 some future rele
8bc0: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ase of SQLite..*
8bd0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
8be0: 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 _os_init() routi
8bf0: 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e ne does operatin
8c00: 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 g-system specifi
8c10: 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 c.** initializat
8c20: 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 ion of the SQLit
8c30: 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 e library. The
8c40: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
8c50: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f .** routine undo
8c60: 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 es the effect of
8c70: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
8c80: 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 (). Typical tas
8c90: 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 ks.** performed
8ca0: 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 by these routine
8cb0: 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 s include alloca
8cc0: 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 tion or dealloca
8cd0: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 tion.** of stati
8ce0: 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 c resources, ini
8cf0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 tialization of g
8d00: 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c lobal variables,
8d10: 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 .** setting up a
8d20: 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 default [sqlite
8d30: 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 3_vfs] module, o
8d40: 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 r setting up.**
8d50: 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 a default config
8d60: 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 uration using [s
8d70: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
8d80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c ..**.** The appl
8d90: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e ication should n
8da0: 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 ever invoke eith
8db0: 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e er sqlite3_os_in
8dc0: 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 it().** or sqlit
8dd0: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 e3_os_end() dire
8de0: 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 ctly. The appli
8df0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e cation should on
8e00: 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c ly invoke.** sql
8e10: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
8e20: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 ) and sqlite3_sh
8e30: 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 utdown(). The s
8e40: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
8e50: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
8e60: 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 called automati
8e70: 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 cally by sqlite3
8e80: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e _initialize() an
8e90: 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f d.** sqlite3_os_
8ea0: 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 end() is called
8eb0: 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 by sqlite3_shutd
8ec0: 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 own(). Appropri
8ed0: 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 ate.** implement
8ee0: 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 ations for sqlit
8ef0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 e3_os_init() and
8f00: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
8f10: 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 ).** are built i
8f20: 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 nto SQLite when
8f30: 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 it is compiled f
8f40: 6f 72 20 75 6e 69 78 2c 20 77 69 6e 64 6f 77 73 or unix, windows
8f50: 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 , or os/2..** Wh
8f60: 65 6e 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 en built for oth
8f70: 65 72 20 70 6c 61 74 66 6f 72 6d 73 20 28 75 73 er platforms (us
8f80: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ing the [SQLITE_
8f90: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 OS_OTHER=1] comp
8fa0: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 ile-time.** opti
8fb0: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 on) the applicat
8fc0: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 ion must supply
8fd0: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 a suitable imple
8fe0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a mentation for.**
8ff0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
9000: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
9010: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 s_end(). An app
9020: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 lication-supplie
9030: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 d.** implementat
9040: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f ion of sqlite3_o
9050: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 s_init() or sqli
9060: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
9070: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c must return [SQL
9080: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
9090: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 ss and some othe
90a0: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 r [error code] u
90b0: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a pon.** failure..
90c0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 */.int sqlite3_i
90d0: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b nitialize(void);
90e0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 .int sqlite3_shu
90f0: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 tdown(void);.int
9100: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
9110: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 (void);.int sqli
9120: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 te3_os_end(void)
9130: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
9140: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 F: Configuring T
9150: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 he SQLite Librar
9160: 79 20 7b 48 31 34 31 30 30 7d 20 3c 53 32 30 30 y {H14100} <S200
9170: 30 30 3e 3c 53 33 30 32 30 30 3e 0a 2a 2a 20 45 00><S30200>.** E
9180: 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
9190: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
91a0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 nfig() interface
91b0: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 is used to make
91c0: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 global configur
91d0: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 ation.** changes
91e0: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 to SQLite in or
91f0: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 der to tune SQLi
9200: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 te to the specif
9210: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 ic needs of.** t
9220: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 he application.
9230: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e The default con
9240: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 figuration is re
9250: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f commended for mo
9260: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f st.** applicatio
9270: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 ns and so this r
9280: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c outine is usuall
9290: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e y not necessary.
92a0: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 It is.** provi
92b0: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 ded to support r
92c0: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 are applications
92d0: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 with unusual ne
92e0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 eds..**.** The s
92f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
9300: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 interface is not
9310: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 threadsafe. Th
9320: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a e application.**
9330: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 must insure tha
9340: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 t no other SQLit
9350: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 e interfaces are
9360: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 invoked by othe
9370: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 r.** threads whi
9380: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 le sqlite3_confi
9390: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 g() is running.
93a0: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 Furthermore, sq
93b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a lite3_config().*
93c0: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e * may only be in
93d0: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c voked prior to l
93e0: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a ibrary initializ
93f0: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b ation using.** [
9400: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9410: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 ze()] or after s
9420: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 hutdown by [sqli
9430: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e te3_shutdown()].
9440: 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 .** Note, howeve
9450: 72 2c 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f r, that sqlite3_
9460: 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 config() can be
9470: 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f called as part o
9480: 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 f the.** impleme
9490: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 ntation of an ap
94a0: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
94b0: 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e d [sqlite3_os_in
94c0: 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 it()]..**.** The
94d0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
94e0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 to sqlite3_confi
94f0: 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 g() is an intege
9500: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e r.** [SQLITE_CON
9510: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
9520: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e | configuration
9530: 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 option] that de
9540: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 termines.** what
9550: 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c property of SQL
9560: 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e ite is to be con
9570: 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 figured. Subseq
9580: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a uent arguments.*
9590: 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 * vary depending
95a0: 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f on the [SQLITE_
95b0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
95c0: 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 EAD | configurat
95d0: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 ion option].** i
95e0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
95f0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e ment..**.** When
9600: 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e a configuration
9610: 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 option is set,
9620: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
9630: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
9640: 5f 4f 4b 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 _OK]..** If the
9650: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 option is unknow
9660: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 n or SQLite is u
9670: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 nable to set the
9680: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 option.** then
9690: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 this routine ret
96a0: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 urns a non-zero
96b0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a [error code]..**
96c0: 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
96d0: 3a 0a 2a 2a 20 5b 48 31 34 31 30 33 5d 20 5b 48 :.** [H14103] [H
96e0: 31 34 31 30 36 5d 20 5b 48 31 34 31 32 30 5d 20 14106] [H14120]
96f0: 5b 48 31 34 31 32 33 5d 20 5b 48 31 34 31 32 36 [H14123] [H14126
9700: 5d 20 5b 48 31 34 31 32 39 5d 20 5b 48 31 34 31 ] [H14129] [H141
9710: 33 32 5d 20 5b 48 31 34 31 33 35 5d 0a 2a 2a 20 32] [H14135].**
9720: 5b 48 31 34 31 33 38 5d 20 5b 48 31 34 31 34 31 [H14138] [H14141
9730: 5d 20 5b 48 31 34 31 34 34 5d 20 5b 48 31 34 31 ] [H14144] [H141
9740: 34 37 5d 20 5b 48 31 34 31 35 30 5d 20 5b 48 31 47] [H14150] [H1
9750: 34 31 35 33 5d 20 5b 48 31 34 31 35 36 5d 20 5b 4153] [H14156] [
9760: 48 31 34 31 35 39 5d 0a 2a 2a 20 5b 48 31 34 31 H14159].** [H141
9770: 36 32 5d 20 5b 48 31 34 31 36 35 5d 20 5b 48 31 62] [H14165] [H1
9780: 34 31 36 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 4168].*/.SQLITE_
9790: 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 EXPERIMENTAL int
97a0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
97b0: 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a int, ...);../*.*
97c0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
97d0: 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 igure database c
97e0: 6f 6e 6e 65 63 74 69 6f 6e 73 20 20 7b 48 31 34 onnections {H14
97f0: 32 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 200} <S20000>.**
9800: 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
9810: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
9820: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 db_config() inte
9830: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
9840: 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 make configurat
9850: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 ion.** changes t
9860: 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f o a [database co
9870: 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 nnection]. The
9880: 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d interface is sim
9890: 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 ilar to.** [sqli
98a0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 te3_config()] ex
98b0: 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 cept that the ch
98c0: 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 anges apply to a
98d0: 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 single.** [data
98e0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
98f0: 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 (specified in t
9900: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
9910: 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 t). The.** sqli
9920: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 te3_db_config()
9930: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 6f 6e interface can on
9940: 6c 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 ly be used immed
9950: 69 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 iately after.**
9960: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
9970: 6e 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 nection is creat
9980: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
9990: 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 3_open()],.** [s
99a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
99b0: 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 , or [sqlite3_op
99c0: 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a en_v2()]. .**.*
99d0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 * The second arg
99e0: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
99f0: 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e _db_config(D,V,.
9a00: 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 ..) is the.** c
9a10: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 onfiguration ver
9a20: 62 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 b - an integer c
9a30: 6f 64 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 ode that indicat
9a40: 65 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 es what.** aspec
9a50: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 t of the [databa
9a60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
9a70: 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 s being configur
9a80: 65 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 ed..** The only
9a90: 63 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 choice for this
9aa0: 76 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 value is [SQLITE
9ab0: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
9ac0: 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 IDE]..** New ver
9ad0: 62 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f bs are likely to
9ae0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
9af0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
9b00: 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 SQLite..** Addit
9b10: 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 ional arguments
9b20: 64 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 depend on the ve
9b30: 72 62 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 rb..**.** Requir
9b40: 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 32 ements:.** [H142
9b50: 30 33 5d 20 5b 48 31 34 32 30 36 5d 20 5b 48 31 03] [H14206] [H1
9b60: 34 32 30 39 5d 20 5b 48 31 34 32 31 32 5d 20 5b 4209] [H14212] [
9b70: 48 31 34 32 31 35 5d 0a 2a 2f 0a 53 51 4c 49 54 H14215].*/.SQLIT
9b80: 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 E_EXPERIMENTAL i
9b90: 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f nt sqlite3_db_co
9ba0: 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 nfig(sqlite3*, i
9bb0: 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a nt op, ...);../*
9bc0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
9bd0: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 mory Allocation
9be0: 52 6f 75 74 69 6e 65 73 20 7b 48 31 30 31 35 35 Routines {H10155
9bf0: 7d 20 3c 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58 } <S20120>.** EX
9c00: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
9c10: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
9c20: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 this object defi
9c30: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 nes the interfac
9c40: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 e between SQLite
9c50: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 .** and low-leve
9c60: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
9c70: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a ion routines..**
9c80: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 .** This object
9c90: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 is used in only
9ca0: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 one place in the
9cb0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
9cc0: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 e..** A pointer
9cd0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
9ce0: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 f this object is
9cf0: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f the argument to
9d00: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
9d10: 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 fig()] when the
9d20: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
9d30: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 tion is.** [SQLI
9d40: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
9d50: 5d 2e 20 20 42 79 20 63 72 65 61 74 69 6e 67 20 ]. By creating
9d60: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
9d70: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e his object.** an
9d80: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 d passing it to
9d90: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
9da0: 29 5d 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 )] during config
9db0: 75 72 61 74 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 uration, an.** a
9dc0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 pplication can s
9dd0: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e pecify an altern
9de0: 61 74 69 76 65 20 6d 65 6d 6f 72 79 20 61 6c 6c ative memory all
9df0: 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 ocation subsyste
9e00: 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c 69 74 65 20 m.** for SQLite
9e10: 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f to use for all o
9e20: 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 f its dynamic me
9e30: 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a mory needs..**.*
9e40: 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 * Note that SQLi
9e50: 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 61 20 te comes with a
9e60: 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 built-in memory
9e70: 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 69 allocator that i
9e80: 73 0a 2a 2a 20 70 65 72 66 65 63 74 6c 79 20 61 s.** perfectly a
9e90: 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 dequate for the
9ea0: 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a overwhelming maj
9eb0: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 ority of applica
9ec0: 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 tions.** and tha
9ed0: 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 t this object is
9ee0: 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 only useful to
9ef0: 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 a tiny minority
9f00: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a of applications.
9f10: 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 ** with speciali
9f20: 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 zed memory alloc
9f30: 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e ation requiremen
9f40: 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 ts. This object
9f50: 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 is.** also used
9f60: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 during testing
9f70: 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 of SQLite in ord
9f80: 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e er to specify an
9f90: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 alternative.**
9fa0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
9fb0: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 that simulates
9fc0: 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 memory out-of-me
9fd0: 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 mory conditions
9fe0: 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 in.** order to v
9ff0: 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 erify that SQLit
a000: 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 e recovers grace
a010: 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a fully from such.
a020: 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a ** conditions..*
a030: 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 *.** The xMalloc
a040: 2c 20 78 46 72 65 65 2c 20 61 6e 64 20 78 52 65 , xFree, and xRe
a050: 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 73 20 6d 75 alloc methods mu
a060: 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 st work like the
a070: 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 66 72 .** malloc(), fr
a080: 65 65 28 29 2c 20 61 6e 64 20 72 65 61 6c 6c 6f ee(), and reallo
a090: 63 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 c() functions fr
a0a0: 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 om the standard
a0b0: 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 library..**.** x
a0c0: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 Size should retu
a0d0: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 rn the allocated
a0e0: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 size of a memor
a0f0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 y allocation.**
a100: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 previously obtai
a110: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 ned from xMalloc
a120: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 or xRealloc. T
a130: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a he allocated siz
a140: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 e.** is always a
a150: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 t least as big a
a160: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 s the requested
a170: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 size but may be
a180: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 larger..**.** Th
a190: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f e xRoundup metho
a1a0: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 d returns what w
a1b0: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f ould be the allo
a1c0: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a cated size of.**
a1d0: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
a1e0: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 tion given a par
a1f0: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 ticular requeste
a200: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 d size. Most me
a210: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f mory.** allocato
a220: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f rs round up memo
a230: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 ry allocations a
a240: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e t least to the n
a250: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 ext multiple.**
a260: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f of 8. Some allo
a270: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 cators round up
a280: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 to a larger mult
a290: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 iple or to a pow
a2a0: 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 er of 2..**.** T
a2b0: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 he xInit method
a2c0: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 initializes the
a2d0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
a2e0: 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c . (For example,
a2f0: 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c .** it might all
a300: 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 ocate any requir
a310: 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 e mutexes or ini
a320: 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c tialize internal
a330: 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 data.** structu
a340: 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 res. The xShutd
a350: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e own method is in
a360: 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c voked (indirectl
a370: 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 y) by.** [sqlite
a380: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 3_shutdown()] an
a390: 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 d should dealloc
a3a0: 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 ate any resource
a3b0: 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 s acquired.** by
a3c0: 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 xInit. The pAp
a3d0: 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 pData pointer is
a3e0: 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c used as the onl
a3f0: 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a y parameter to.*
a400: 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 * xInit and xShu
a410: 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 tdown..*/.typede
a420: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
a430: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c _mem_methods sql
a440: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
a450: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
a460: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 _mem_methods {.
a470: 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 void *(*xMalloc
a480: 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 )(int);
a490: 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 /* Memory alloca
a4a0: 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f tion function */
a4b0: 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 . void (*xFree)
a4c0: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
a4d0: 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f /* Free a prio
a4e0: 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a r allocation */.
a4f0: 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c void *(*xReall
a500: 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 oc)(void*,int);
a510: 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c /* Resize an al
a520: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e location */. in
a530: 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a t (*xSize)(void*
a540: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ); /*
a550: 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 Return the size
a560: 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e of an allocation
a570: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 */. int (*xRou
a580: 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 ndup)(int);
a590: 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 /* Round up
a5a0: 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f request size to
a5b0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 allocation size
a5c0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 */. int (*xIni
a5d0: 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 t)(void*);
a5e0: 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 /* Initiali
a5f0: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c ze the memory al
a600: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 locator */. voi
a610: 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 d (*xShutdown)(v
a620: 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 oid*); /* D
a630: 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 einitialize the
a640: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
a650: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 */. void *pApp
a660: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 Data;
a670: 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 /* Argument
a680: 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 to xInit() and
a690: 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d xShutdown() */.}
a6a0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
a6b0: 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e F: Configuration
a6c0: 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 36 30 Options {H10160
a6d0: 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 } <S20000>.** EX
a6e0: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
a6f0: 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
a700: 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 are the availab
a710: 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 le integer confi
a720: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
a730: 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 that.** can be
a740: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 passed as the fi
a750: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
a760: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e the [sqlite3_con
a770: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
a780: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 ..**.** New conf
a790: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
a7a0: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
a7b0: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
a7c0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 s of SQLite..**
a7d0: 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 Existing configu
a7e0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
a7f0: 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 ight be disconti
a800: 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 nued. Applicati
a810: 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 ons.** should ch
a820: 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 eck the return c
a830: 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ode from [sqlite
a840: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 3_config()] to m
a850: 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a ake sure that.**
a860: 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 the call worked
a870: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
a880: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
a890: 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ace will return
a8a0: 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 a.** non-zero [e
a8b0: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 rror code] if a
a8c0: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 discontinued or
a8d0: 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 unsupported conf
a8e0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
a8f0: 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a .** is invoked..
a900: 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 **.** <dl>.** <d
a910: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
a920: 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 SINGLETHREAD</dt
a930: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
a940: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
a950: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
a960: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 This option dis
a970: 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 ables.** all mut
a980: 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 exing and puts S
a990: 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 QLite into a mod
a9a0: 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f e where it can o
a9b0: 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 nly be used.** b
a9c0: 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 y a single threa
a9d0: 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 d.</dd>.**.** <d
a9e0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
a9f0: 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e MULTITHREAD</dt>
aa00: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
aa10: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
aa20: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
aa30: 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 This option disa
aa40: 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 bles.** mutexing
aa50: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
aa60: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 nnection] and [p
aa70: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
aa80: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 t] objects..** T
aa90: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 he application i
aaa0: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
aab0: 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 r serializing ac
aac0: 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 cess to.** [data
aad0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
aae0: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 ] and [prepared
aaf0: 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 statements]. Bu
ab00: 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a t other mutexes.
ab10: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 ** are enabled s
ab20: 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 o that SQLite wi
ab30: 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 ll be safe to us
ab40: 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 e in a multi-thr
ab50: 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e eaded.** environ
ab60: 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 ment as long as
ab70: 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 no two threads a
ab80: 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 ttempt to use th
ab90: 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 e same.** [datab
aba0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
abb0: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
abc0: 2e 20 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 . See the [thre
abd0: 61 64 69 6e 67 20 6d 6f 64 65 5d 0a 2a 2a 20 64 ading mode].** d
abe0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 ocumentation for
abf0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f additional info
ac00: 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a rmation.</dd>.**
ac10: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
ac20: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 ONFIG_SERIALIZED
ac30: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
ac40: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 re are no argume
ac50: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
ac60: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e on. This option
ac70: 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 enables.** all
ac80: 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e mutexes includin
ac90: 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a g the recursive.
aca0: 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 ** mutexes on [d
acb0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
acc0: 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 on] and [prepare
acd0: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a d statement] obj
ace0: 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 ects..** In this
acf0: 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 mode (which is
ad00: 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e the default when
ad10: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
ad20: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c led with.** [SQL
ad30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 ITE_THREADSAFE=1
ad40: 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 ]) the SQLite li
ad50: 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c brary will itsel
ad60: 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 f serialize acce
ad70: 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 ss.** to [databa
ad80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 se connections]
ad90: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
ada0: 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 atements] so tha
adb0: 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 t the.** applica
adc0: 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 tion is free to
add0: 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 use the same [da
ade0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
adf0: 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d n] or the.** sam
ae00: 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
ae10: 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 ement] in differ
ae20: 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 ent threads at t
ae30: 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a he same time..**
ae40: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 See the [thread
ae50: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 ing mode] docume
ae60: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 ntation for addi
ae70: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 tional informati
ae80: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c on.</dd>.**.** <
ae90: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
aea0: 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 _MALLOC</dt>.**
aeb0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
aec0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
aed0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
aee0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
aef0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 .** instance of
af00: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d the [sqlite3_mem
af10: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
af20: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 ure. The argume
af30: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 nt specifies.**
af40: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d alternative low-
af50: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c level memory all
af60: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
af70: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 to be used in p
af80: 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d lace of.** the m
af90: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
afa0: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 routines built
afb0: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 into SQLite.</dd
afc0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
afd0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c TE_CONFIG_GETMAL
afe0: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e LOC</dt>.** <dd>
aff0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
b000: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
b010: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
b020: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
b030: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
b040: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 [sqlite3_mem_met
b050: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
b060: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d The [sqlite3_m
b070: 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 em_methods].** s
b080: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c tructure is fill
b090: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 ed with the curr
b0a0: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 ently defined me
b0b0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
b0c0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 routines..** Thi
b0d0: 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 s option can be
b0e0: 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 used to overload
b0f0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d the default mem
b100: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ory allocation.*
b110: 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 * routines with
b120: 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 a wrapper that s
b130: 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 imulations memor
b140: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 y allocation fai
b150: 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b lure or.** track
b160: 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 s memory usage,
b170: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 for example.</dd
b180: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
b190: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
b1a0: 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TUS</dt>.** <dd>
b1b0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
b1c0: 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e s single argumen
b1d0: 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 t of type int, i
b1e0: 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
b1f0: 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 .** boolean, whi
b200: 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 ch enables or di
b210: 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 sables the colle
b220: 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 ction of memory
b230: 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 allocation .** s
b240: 74 61 74 69 73 74 69 63 73 2e 20 57 68 65 6e 20 tatistics. When
b250: 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f disabled, the fo
b260: 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 llowing SQLite i
b270: 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 nterfaces become
b280: 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 .** non-operati
b290: 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a onal:.** <ul>.
b2a0: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
b2b0: 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
b2c0: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c ].** <li> [sql
b2d0: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
b2e0: 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c water()].** <l
b2f0: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 i> [sqlite3_soft
b300: 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a _heap_limit()].*
b310: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 * <li> [sqlite
b320: 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 3_status()].**
b330: 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a </ul>.** </dd>.
b340: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
b350: 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c _CONFIG_SCRATCH<
b360: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
b370: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 option specifie
b380: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 s a static memor
b390: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 y buffer that SQ
b3a0: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 Lite can use for
b3b0: 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f .** scratch memo
b3c0: 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 ry. There are t
b3d0: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 hree arguments:
b3e0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 A pointer to th
b3f0: 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a e memory, the.**
b400: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 size of each sc
b410: 72 61 74 63 68 20 62 75 66 66 65 72 20 28 73 7a ratch buffer (sz
b420: 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 ), and the numbe
b430: 72 20 6f 66 20 62 75 66 66 65 72 73 20 28 4e 29 r of buffers (N)
b440: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 . The sz.** arg
b450: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 ument must be a
b460: 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 multiple of 16.
b470: 54 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 The sz parameter
b480: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 should be a few
b490: 20 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 bytes.** larger
b4a0: 20 74 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c than the actual
b4b0: 20 73 63 72 61 74 63 68 20 73 70 61 63 65 20 72 scratch space r
b4c0: 65 71 75 69 72 65 64 20 64 75 65 20 69 6e 74 65 equired due inte
b4d0: 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a rnal overhead..*
b4e0: 2a 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 * The first.** a
b4f0: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 rgument should p
b500: 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 oint to an alloc
b510: 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 ation of at leas
b520: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 t sz*N bytes of
b530: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 memory..** SQLit
b540: 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f e will use no mo
b550: 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 re than one scra
b560: 74 63 68 20 62 75 66 66 65 72 20 61 74 20 6f 6e tch buffer at on
b570: 63 65 20 70 65 72 20 74 68 72 65 61 64 2c 20 73 ce per thread, s
b580: 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 o.** N should be
b590: 20 73 65 74 20 74 6f 20 74 68 65 20 65 78 70 65 set to the expe
b5a0: 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d cted maximum num
b5b0: 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 20 ber of threads.
b5c0: 20 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d The sz.** param
b5d0: 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 36 eter should be 6
b5e0: 20 74 69 6d 65 73 20 74 68 65 20 73 69 7a 65 20 times the size
b5f0: 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 of the largest d
b600: 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a atabase page siz
b610: 65 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20 62 75 e..** Scratch bu
b620: 66 66 65 72 73 20 61 72 65 20 75 73 65 64 20 61 ffers are used a
b630: 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 74 s part of the bt
b640: 72 65 65 20 62 61 6c 61 6e 63 65 20 6f 70 65 72 ree balance oper
b650: 61 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 ation. If.** Th
b660: 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 72 e btree balancer
b670: 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 needs additiona
b680: 6c 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 l memory beyond
b690: 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 what is provided
b6a0: 20 62 79 0a 2a 2a 20 73 63 72 61 74 63 68 20 62 by.** scratch b
b6b0: 75 66 66 65 72 73 20 6f 72 20 69 66 20 6e 6f 20 uffers or if no
b6c0: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 73 scratch buffer s
b6d0: 70 61 63 65 20 69 73 20 73 70 65 63 69 66 69 65 pace is specifie
b6e0: 64 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a d, then SQLite.*
b6f0: 2a 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 * goes to [sqlit
b700: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 e3_malloc()] to
b710: 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 obtain the memor
b720: 79 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e y it needs.</dd>
b730: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
b740: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
b750: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 HE</dt>.** <dd>T
b760: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 his option speci
b770: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 fies a static me
b780: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 mory buffer that
b790: 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 SQLite can use
b7a0: 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 for.** the datab
b7b0: 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 ase page cache w
b7c0: 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 ith the default
b7d0: 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 page cache imple
b7e0: 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 menation. .** T
b7f0: 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f his configuratio
b800: 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 n should not be
b810: 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 used if an appli
b820: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 cation-define pa
b830: 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c ge.** cache impl
b840: 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f ementation is lo
b850: 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 aded using the S
b860: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
b870: 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 CHE option..** T
b880: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 here are three a
b890: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 rguments to this
b8a0: 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 option: A point
b8b0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 6d 65 6d er to the.** mem
b8c0: 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 ory, the size of
b8d0: 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 each page buffe
b8e0: 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 r (sz), and the
b8f0: 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 number of pages
b900: 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 (N)..** The sz a
b910: 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 rgument must be
b920: 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 a power of two b
b930: 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 etween 512 and 3
b940: 32 37 36 38 2e 20 20 54 68 65 20 66 69 72 73 74 2768. The first
b950: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f .** argument sho
b960: 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 uld point to an
b970: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 allocation of at
b980: 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 least sz*N byte
b990: 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 s of memory..**
b9a0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 SQLite will use
b9b0: 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 the memory provi
b9c0: 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 ded by the first
b9d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 argument to sat
b9e0: 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f isfy its.** memo
b9f0: 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 ry needs for the
ba00: 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 first N pages t
ba10: 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 hat it adds to c
ba20: 61 63 68 65 2e 20 20 49 66 20 61 64 64 69 74 69 ache. If additi
ba30: 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 onal.** page cac
ba40: 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 he memory is nee
ba50: 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 ded beyond what
ba60: 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 is provided by t
ba70: 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e his option, then
ba80: 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 .** SQLite goes
ba90: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c to [sqlite3_mall
baa0: 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 oc()] for the ad
bab0: 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 ditional storage
bac0: 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 69 space..** The i
bad0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 mplementation mi
bae0: 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d ght use one or m
baf0: 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66 ore of the N buf
bb00: 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a fers to hold .**
bb10: 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 memory accounti
bb20: 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 ng information.
bb30: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
bb40: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 SQLITE_CONFIG_HE
bb50: 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 AP</dt>.** <dd>T
bb60: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 his option speci
bb70: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 fies a static me
bb80: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 mory buffer that
bb90: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 SQLite will use
bba0: 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 .** for all of i
bbb0: 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 ts dynamic memor
bbc0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 y allocation nee
bbd0: 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 ds beyond those
bbe0: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 provided.** for
bbf0: 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 by [SQLITE_CONFI
bc00: 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b G_SCRATCH] and [
bc10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
bc20: 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 GECACHE]..** The
bc30: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 re are three arg
bc40: 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65 uments: A pointe
bc50: 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c r to the memory,
bc60: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
bc70: 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d * bytes in the m
bc80: 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e emory buffer, an
bc90: 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c d the minimum al
bca0: 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20 20 location size.
bcb0: 49 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 If.** the first
bcc0: 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d pointer (the mem
bcd0: 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 ory pointer) is
bce0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 NULL, then SQLit
bcf0: 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 e reverts.** to
bd00: 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c using its defaul
bd10: 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
bd20: 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d or (the system m
bd30: 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e alloc() implemen
bd40: 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f tation),.** undo
bd50: 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e ing any prior in
bd60: 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c vocation of [SQL
bd70: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
bd80: 43 5d 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 6d C]. If the.** m
bd90: 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 emory pointer is
bda0: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 not NULL and ei
bdb0: 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 ther [SQLITE_ENA
bdc0: 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a BLE_MEMSYS3] or.
bdd0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c ** [SQLITE_ENABL
bde0: 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 E_MEMSYS5] are d
bdf0: 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 efined, then the
be00: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d alternative mem
be10: 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 ory.** allocator
be20: 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 is engaged to h
be30: 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c andle all of SQL
be40: 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ites memory allo
be50: 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 3c 2f 64 cation needs.</d
be60: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
be70: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
be80: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
be90: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 s option takes a
bea0: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
beb0: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e which is a poin
bec0: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 ter to an.** ins
bed0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 tance of the [sq
bee0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
bef0: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 ods] structure.
bf00: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 The argument sp
bf10: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 ecifies.** alter
bf20: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c native low-level
bf30: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 mutex routines
bf40: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c to be used in pl
bf50: 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 ace.** the mutex
bf60: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 routines built
bf70: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 into SQLite.</dd
bf80: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
bf90: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
bfa0: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 EX</dt>.** <dd>T
bfb0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
bfc0: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
bfd0: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f nt which is a po
bfe0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 inter to an.** i
bff0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
c000: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
c010: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
c020: 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 . The.** [sqlit
c030: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
c040: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 ].** structure i
c050: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 s filled with th
c060: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 e currently defi
c070: 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e ned mutex routin
c080: 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 es..** This opti
c090: 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 on can be used t
c0a0: 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 o overload the d
c0b0: 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c efault mutex all
c0c0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 ocation.** routi
c0d0: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 nes with a wrapp
c0e0: 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b er used to track
c0f0: 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 mutex usage for
c100: 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 performance.**
c110: 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 profiling or tes
c120: 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c ting, for exampl
c130: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 e.</dd>.**.** <d
c140: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
c150: 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a LOOKASIDE</dt>.*
c160: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f * <dd>This optio
c170: 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 n takes two argu
c180: 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 ments that deter
c190: 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 mine the default
c1a0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 63 61 .** memory allca
c1b0: 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 20 6f tion lookaside o
c1c0: 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 54 68 ptimization. Th
c1d0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
c1e0: 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 is the.** size
c1f0: 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 of each lookasid
c200: 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e e buffer slot an
c210: 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 d the second is
c220: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
c230: 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 slots allocated
c240: 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 to each databas
c250: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c 2f 64 e connection.</d
c260: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
c270: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
c280: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 E</dt>.** <dd>Th
c290: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
c2a0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
c2b0: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
c2c0: 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 nter to.** an [s
c2d0: 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
c2e0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 thods] object.
c2f0: 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 This object spec
c300: 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 ifies the interf
c310: 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 ace.** to a cust
c320: 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d om page cache im
c330: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 53 plementation. S
c340: 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f QLite makes a co
c350: 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a py of the.** obj
c360: 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 ect and uses it
c370: 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d for page cache m
c380: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
c390: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 s.</dd>.**.** <d
c3a0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
c3b0: 47 45 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a GETPCACHE</dt>.*
c3c0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f * <dd>This optio
c3d0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
c3e0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
c3f0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
c400: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 an.** [sqlite3_p
c410: 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f cache_methods] o
c420: 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 bject. SQLite c
c430: 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 opies of the cur
c440: 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 rent.** page cac
c450: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
c460: 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 n into that obje
c470: 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ct.</dd>.**.** <
c480: 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
c490: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
c4a0: 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f NGLETHREAD 1 /
c4b0: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 * nil */.#define
c4c0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
c4d0: 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 ULTITHREAD 2
c4e0: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
c4f0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
c500: 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 SERIALIZED 3
c510: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
c520: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
c530: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 _MALLOC 4
c540: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d /* sqlite3_mem
c550: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
c560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
c570: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 IG_GETMALLOC
c580: 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 5 /* sqlite3_m
c590: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 em_methods* */.#
c5a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
c5b0: 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 NFIG_SCRATCH
c5c0: 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 6 /* void*,
c5d0: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f int sz, int N */
c5e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c5f0: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
c600: 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 7 /* void*
c610: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 , int sz, int N
c620: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
c630: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 E_CONFIG_HEAP
c640: 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 8 /* voi
c650: 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 d*, int nByte, i
c660: 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e nt min */.#defin
c670: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
c680: 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 MEMSTATUS 9
c690: 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 /* boolean */.#
c6a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
c6b0: 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 NFIG_MUTEX
c6c0: 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 10 /* sqlite3
c6d0: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 _mutex_methods*
c6e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
c6f0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
c700: 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c X 11 /* sql
c710: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
c720: 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f ds* */./* previo
c730: 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 usly SQLITE_CONF
c740: 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 IG_CHUNKALLOC 12
c750: 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e which is now un
c760: 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e used. */ .#defin
c770: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
c780: 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 LOOKASIDE 13
c790: 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 /* int int */.#
c7a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
c7b0: 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 NFIG_PCACHE
c7c0: 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 14 /* sqlite3
c7d0: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a _pcache_methods*
c7e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
c7f0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
c800: 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 CHE 15 /* sq
c810: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
c820: 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 hods* */../*.**
c830: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
c840: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 uration Options
c850: 7b 48 31 30 31 37 30 7d 20 3c 53 32 30 30 30 30 {H10170} <S20000
c860: 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
c870: 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f L.**.** These co
c880: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 nstants are the
c890: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 available intege
c8a0: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 r configuration
c8b0: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 options that.**
c8c0: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 can be passed as
c8d0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
c8e0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c ment to the [sql
c8f0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
c900: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a ] interface..**.
c910: 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 ** New configura
c920: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 tion options may
c930: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
c940: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
c950: 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 SQLite..** Exist
c960: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ing configuratio
c970: 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 n options might
c980: 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e be discontinued.
c990: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a Applications.*
c9a0: 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 * should check t
c9b0: 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 he return code f
c9c0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f rom [sqlite3_db_
c9d0: 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b config()] to mak
c9e0: 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 e sure that.** t
c9f0: 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 he call worked.
ca00: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 The [sqlite3_db
ca10: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
ca20: 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e face will return
ca30: 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b a.** non-zero [
ca40: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 error code] if a
ca50: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 discontinued or
ca60: 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e unsupported con
ca70: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
ca80: 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e n.** is invoked.
ca90: 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c .**.** <dl>.** <
caa0: 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 dt>SQLITE_DBCONF
cab0: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 IG_LOOKASIDE</dt
cac0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 >.** <dd>This op
cad0: 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 tion takes three
cae0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 additional argu
caf0: 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 ments that deter
cb00: 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f mine the .** [lo
cb10: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 okaside memory a
cb20: 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 llocator] config
cb30: 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 uration for the
cb40: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
cb50: 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 tion]..** The fi
cb60: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 rst argument (th
cb70: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
cb80: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 r to [sqlite3_db
cb90: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a _config()] is a.
cba0: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 ** pointer to a
cbb0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f memory buffer to
cbc0: 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 use for lookasi
cbd0: 64 65 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 20 de memory. The
cbe0: 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e first.** argumen
cbf0: 74 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e t may be NULL in
cc00: 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 which case SQLi
cc10: 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 te will allocate
cc20: 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a the lookaside.*
cc30: 2a 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 * buffer itself
cc40: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d using [sqlite3_m
cc50: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 73 alloc()]. The s
cc60: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
cc70: 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 s the.** size of
cc80: 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 each lookaside
cc90: 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 buffer slot and
cca0: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 the third argume
ccb0: 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 nt is the number
ccc0: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 of.** slots. T
ccd0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 he size of the b
cce0: 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 uffer in the fir
ccf0: 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 st argument must
cd00: 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e be greater than
cd10: 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 .** or equal to
cd20: 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 the product of t
cd30: 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 he second and th
cd40: 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 3c 2f ird arguments.</
cd50: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a dd>.**.** </dl>.
cd60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
cd70: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
cd80: 53 49 44 45 20 20 20 20 31 30 30 31 20 20 2f 2a SIDE 1001 /*
cd90: 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a void* int int *
cda0: 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 /.../*.** CAPI3R
cdb0: 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 EF: Enable Or Di
cdc0: 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 sable Extended R
cdd0: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 32 esult Codes {H12
cde0: 32 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 200} <S10700>.**
cdf0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
ce00: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f extended_result_
ce10: 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 codes() routine
ce20: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 enables or disab
ce30: 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 les the.** [exte
ce40: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
ce50: 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 s] feature of SQ
ce60: 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64 Lite. The extend
ce70: 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 ed result.** cod
ce80: 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 es are disabled
ce90: 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 by default for h
cea0: 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 istorical compat
ceb0: 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72 ibility consider
cec0: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 ations..**.** Re
ced0: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
cee0: 48 31 32 32 30 31 5d 20 5b 48 31 32 32 30 32 5d H12201] [H12202]
cef0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
cf00: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f extended_result_
cf10: 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 codes(sqlite3*,
cf20: 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a int onoff);../*.
cf30: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 ** CAPI3REF: Las
cf40: 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 7b t Insert Rowid {
cf50: 48 31 32 32 32 30 7d 20 3c 53 31 30 37 30 30 3e H12220} <S10700>
cf60: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 .**.** Each entr
cf70: 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 y in an SQLite t
cf80: 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 able has a uniqu
cf90: 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a e 64-bit signed.
cfa0: 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 ** integer key c
cfb0: 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 alled the [ROWID
cfc0: 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 54 68 65 | "rowid"]. The
cfd0: 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 rowid is always
cfe0: 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 available.** as
cff0: 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 an undeclared c
d000: 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 olumn named ROWI
d010: 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 D, OID, or _ROWI
d020: 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 D_ as long as th
d030: 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 ose.** names are
d040: 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 not also used b
d050: 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 y explicitly dec
d060: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 lared columns. I
d070: 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 f.** the table h
d080: 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 as a column of t
d090: 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 ype [INTEGER PRI
d0a0: 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 MARY KEY] then t
d0b0: 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 hat column.** is
d0c0: 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 another alias f
d0d0: 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a or the rowid..**
d0e0: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
d0f0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f returns the [ro
d100: 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 wid] of the most
d110: 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 recent.** succe
d120: 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 ssful [INSERT] i
d130: 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 nto the database
d140: 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 from the [datab
d150: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a ase connection].
d160: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ** in the first
d170: 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f argument. If no
d180: 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 successful [INS
d190: 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 ERT]s.** have ev
d1a0: 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 er occurred on t
d1b0: 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e hat database con
d1c0: 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 nection, zero is
d1d0: 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
d1e0: 20 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 If an [INSERT]
d1f0: 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 occurs within a
d200: 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68 trigger, then th
d210: 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 e [rowid] of the
d220: 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 inserted.** row
d230: 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 is returned by
d240: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 this routine as
d250: 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 long as the trig
d260: 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ger is running..
d270: 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 ** But once the
d280: 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 trigger terminat
d290: 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 es, the value re
d2a0: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 turned by this r
d2b0: 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 outine.** revert
d2c0: 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 s to the last va
d2d0: 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 lue inserted bef
d2e0: 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 ore the trigger
d2f0: 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 fired..**.** An
d300: 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 [INSERT] that fa
d310: 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e ils due to a con
d320: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f straint violatio
d330: 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 n is not a.** su
d340: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
d350: 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 ] and does not c
d360: 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 hange the value
d370: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 returned by this
d380: 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 .** routine. Th
d390: 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 us INSERT OR FAI
d3a0: 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e L, INSERT OR IGN
d3b0: 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 ORE, INSERT OR R
d3c0: 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 OLLBACK,.** and
d3d0: 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 INSERT OR ABORT
d3e0: 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 make no changes
d3f0: 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 to the return va
d400: 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 lue of this.** r
d410: 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 outine when thei
d420: 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c r insertion fail
d430: 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20 s. When INSERT
d440: 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e OR REPLACE.** en
d450: 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 counters a const
d460: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c raint violation,
d470: 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 it does not fai
d480: 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 l. The.** INSER
d490: 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 T continues to c
d4a0: 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 ompletion after
d4b0: 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 deleting rows th
d4c0: 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 at caused.** the
d4d0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 constraint prob
d4e0: 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 lem so INSERT OR
d4f0: 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c REPLACE will al
d500: 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 ways change.** t
d510: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
d520: 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 of this interfac
d530: 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 e..**.** For the
d540: 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 purposes of thi
d550: 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 s routine, an [I
d560: 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 NSERT] is consid
d570: 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 ered to.** be su
d580: 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 ccessful even if
d590: 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e it is subsequen
d5a0: 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e tly rolled back.
d5b0: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
d5c0: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 32 31 5d nts:.** [H12221]
d5d0: 20 5b 48 31 32 32 32 33 5d 0a 2a 2a 0a 2a 2a 20 [H12223].**.**
d5e0: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
d5f0: 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 read performs a
d600: 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 new [INSERT] on
d610: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 the same.** data
d620: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
d630: 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 while the [sqlit
d640: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
d650: 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 owid()].** funct
d660: 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 ion is running a
d670: 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 nd thus changes
d680: 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 the last insert
d690: 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e [rowid],.** then
d6a0: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
d6b0: 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
d6c0: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
d6d0: 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 d()] is.** unpre
d6e0: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 dictable and mig
d6f0: 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 ht not equal eit
d700: 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 her the old or t
d710: 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 he new.** last i
d720: 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a nsert [rowid]..*
d730: 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 /.sqlite3_int64
d740: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
d750: 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 ert_rowid(sqlite
d760: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
d770: 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 3REF: Count The
d780: 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d Number Of Rows M
d790: 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d odified {H12240}
d7a0: 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S10600>.**.**
d7b0: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
d7c0: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
d7d0: 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 of database row
d7e0: 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e s that were chan
d7f0: 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 ged.** or insert
d800: 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 ed or deleted by
d810: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
d820: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c ly completed SQL
d830: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e statement.** on
d840: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
d850: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 onnection] speci
d860: 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 fied by the firs
d870: 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 t parameter..**
d880: 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 Only changes tha
d890: 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 t are directly s
d8a0: 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
d8b0: 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 [INSERT], [UPDAT
d8c0: 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 E],.** or [DELET
d8d0: 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 E] statement are
d8e0: 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c counted. Auxil
d8f0: 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 iary changes cau
d900: 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 sed by.** trigge
d910: 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 rs are not count
d920: 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c ed. Use the [sql
d930: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
d940: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a es()] function.*
d950: 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f * to find the to
d960: 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 tal number of ch
d970: 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 anges including
d980: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 changes caused b
d990: 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a y triggers..**.*
d9a0: 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 * A "row change"
d9b0: 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 is a change to
d9c0: 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 a single row of
d9d0: 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a a single table.*
d9e0: 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 * caused by an I
d9f0: 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f NSERT, DELETE, o
da00: 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 r UPDATE stateme
da10: 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a nt. Rows that.*
da20: 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 * are changed as
da30: 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 side effects of
da40: 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 REPLACE constra
da50: 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a int resolution,.
da60: 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f ** rollback, ABO
da70: 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 RT processing, D
da80: 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 ROP TABLE, or by
da90: 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 any other.** me
daa0: 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 chanisms do not
dab0: 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 count as direct
dac0: 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a row changes..**.
dad0: 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f ** A "trigger co
dae0: 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 ntext" is a scop
daf0: 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 e of execution t
db00: 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a hat begins and.*
db10: 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 * ends with the
db20: 73 63 72 69 70 74 20 6f 66 20 61 20 74 72 69 67 script of a trig
db30: 67 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 ger. Most SQL s
db40: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a tatements are.**
db50: 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 evaluated outsi
db60: 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 de of any trigge
db70: 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20 r. This is the
db80: 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 "top level".** t
db90: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 rigger context.
dba0: 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69 If a trigger fi
dbb0: 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 res from the top
dbc0: 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 level, a.** new
dbd0: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 trigger context
dbe0: 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 is entered for
dbf0: 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 the duration of
dc00: 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 that one.** trig
dc10: 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 ger. Subtrigger
dc20: 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 s create subcont
dc30: 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 exts for their d
dc40: 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 uration..**.** C
dc50: 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
dc60: 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 exec()] or [sqli
dc70: 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 te3_step()] recu
dc80: 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 rsively does.**
dc90: 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 not create a new
dca0: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 trigger context
dcb0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e ..**.** This fun
dcc0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
dcd0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 e number of dire
dce0: 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 ct row changes i
dcf0: 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 n the.** most re
dd00: 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 cent INSERT, UPD
dd10: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 ATE, or DELETE s
dd20: 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 tatement within
dd30: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 the same.** trig
dd40: 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a ger context..**.
dd50: 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e 20 63 61 ** Thus, when ca
dd60: 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f lled from the to
dd70: 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 p level, this fu
dd80: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 nction returns t
dd90: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
dda0: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d changes in the m
ddb0: 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 ost recent INSER
ddc0: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 T, UPDATE, or DE
ddd0: 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 LETE.** that als
dde0: 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 o occurred at th
ddf0: 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69 e top level. Wi
de00: 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 thin the body of
de10: 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 a trigger,.** t
de20: 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 he sqlite3_chang
de30: 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 es() interface c
de40: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 an be called to
de50: 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 find the number
de60: 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e of.** changes in
de70: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
de80: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 ly completed INS
de90: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 ERT, UPDATE, or
dea0: 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d DELETE.** statem
deb0: 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 ent within the b
dec0: 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ody of the same
ded0: 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 trigger..** Howe
dee0: 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 ver, the number
def0: 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f returned does no
df00: 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 t include change
df10: 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 s.** caused by s
df20: 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 ubtriggers since
df30: 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 those have thei
df40: 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a r own context..*
df50: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c *.** SQLite impl
df60: 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 ements the comma
df70: 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 nd "DELETE FROM
df80: 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 table" without a
df90: 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a WHERE clause.**
dfa0: 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 by dropping and
dfb0: 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 recreating the
dfc0: 74 61 62 6c 65 2e 20 20 44 6f 69 6e 67 20 73 6f table. Doing so
dfd0: 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 is much faster
dfe0: 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 than going.** th
dff0: 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 rough and deleti
e000: 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c ng individual el
e010: 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 ements from the
e020: 74 61 62 6c 65 2e 20 20 42 65 63 61 75 73 65 20 table. Because
e030: 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d of this.** optim
e040: 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c ization, the del
e050: 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 etions in "DELET
e060: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 E FROM table" ar
e070: 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 e not row change
e080: 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f s and.** will no
e090: 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20 t be counted by
e0a0: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e the sqlite3_chan
e0b0: 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 ges() or [sqlite
e0c0: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
e0d0: 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c )].** functions,
e0e0: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 regardless of t
e0f0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 he number of ele
e100: 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 ments that were
e110: 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e originally.** in
e120: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 the table. To
e130: 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 get an accurate
e140: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d count of the num
e150: 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 ber of rows dele
e160: 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c ted, use.** "DEL
e170: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 ETE FROM table W
e180: 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e HERE 1" instead.
e190: 20 20 4f 72 20 72 65 63 6f 6d 70 69 6c 65 20 75 Or recompile u
e1a0: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c sing the.** [SQL
e1b0: 49 54 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54 ITE_OMIT_TRUNCAT
e1c0: 45 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 E_OPTIMIZATION]
e1d0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
e1e0: 69 6f 6e 20 74 6f 20 64 69 73 61 62 6c 65 20 74 ion to disable t
e1f0: 68 65 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 he.** optimizati
e200: 6f 6e 20 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65 on on all querie
e210: 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 s..**.** Require
e220: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 34 ments:.** [H1224
e230: 31 5d 20 5b 48 31 32 32 34 33 5d 0a 2a 2a 0a 2a 1] [H12243].**.*
e240: 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 * If a separate
e250: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 thread makes cha
e260: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 nges on the same
e270: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
e280: 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 tion.** while [s
e290: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
e2a0: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 ] is running the
e2b0: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 n the value retu
e2c0: 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 rned.** is unpre
e2d0: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 dictable and not
e2e0: 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a meaningful..*/.
e2f0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e int sqlite3_chan
e300: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a ges(sqlite3*);..
e310: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
e320: 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 Total Number Of
e330: 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 Rows Modified {H
e340: 31 32 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a 12260} <S10600>.
e350: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 **.** This funct
e360: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 ion returns the
e370: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 number of row ch
e380: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 anges caused by
e390: 49 4e 53 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54 INSERT,.** UPDAT
e3a0: 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 E or DELETE stat
e3b0: 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 ements since the
e3c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
e3d0: 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 ction] was opene
e3e0: 64 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 d..** The count
e3f0: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 includes all cha
e400: 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72 nges from all tr
e410: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 73 2e 20 igger contexts.
e420: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 However,.** the
e430: 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 count does not
e440: 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 include changes
e450: 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e used to implemen
e460: 74 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 t REPLACE constr
e470: 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c aints,.** do rol
e480: 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 lbacks or ABORT
e490: 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 44 processing, or D
e4a0: 52 4f 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73 ROP table proces
e4b0: 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 sing..** The cha
e4c0: 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 nges are counted
e4d0: 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 as soon as the
e4e0: 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d statement that m
e4f0: 61 6b 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 akes them is.**
e500: 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 completed (when
e510: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 the statement ha
e520: 6e 64 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 ndle is passed t
e530: 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 o [sqlite3_reset
e540: 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
e550: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e e3_finalize()]).
e560: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d .**.** SQLite im
e570: 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d plements the com
e580: 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f mand "DELETE FRO
e590: 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 M table" without
e5a0: 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a a WHERE clause.
e5b0: 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 ** by dropping a
e5c0: 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 nd recreating th
e5d0: 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 e table. (This
e5e0: 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 is much faster t
e5f0: 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 han going.** thr
e600: 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e ough and deletin
e610: 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 g individual ele
e620: 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 ments from the t
e630: 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 able.) Because
e640: 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d of this.** optim
e650: 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c ization, the del
e660: 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 etions in "DELET
e670: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 E FROM table" ar
e680: 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 e not row change
e690: 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f s and.** will no
e6a0: 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20 t be counted by
e6b0: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e the sqlite3_chan
e6c0: 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 ges() or [sqlite
e6d0: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
e6e0: 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c )].** functions,
e6f0: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 regardless of t
e700: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 he number of ele
e710: 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 ments that were
e720: 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e originally.** in
e730: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 the table. To
e740: 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 get an accurate
e750: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d count of the num
e760: 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 ber of rows dele
e770: 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c ted, use.** "DEL
e780: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 ETE FROM table W
e790: 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e HERE 1" instead.
e7a0: 20 20 20 4f 72 20 72 65 63 6f 6d 70 69 6c 65 20 Or recompile
e7b0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 using the.** [SQ
e7c0: 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 LITE_OMIT_TRUNCA
e7d0: 54 45 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 5d TE_OPTIMIZATION]
e7e0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
e7f0: 74 69 6f 6e 20 74 6f 20 64 69 73 61 62 6c 65 20 tion to disable
e800: 74 68 65 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 the.** optimizat
e810: 69 6f 6e 20 6f 6e 20 61 6c 6c 20 71 75 65 72 69 ion on all queri
e820: 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c es..**.** See al
e830: 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f so the [sqlite3_
e840: 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 changes()] inter
e850: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 face..**.** Requ
e860: 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
e870: 32 32 36 31 5d 20 5b 48 31 32 32 36 33 5d 0a 2a 2261] [H12263].*
e880: 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 *.** If a separa
e890: 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 te thread makes
e8a0: 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 changes on the s
e8b0: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
e8c0: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 nection.** while
e8d0: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f [sqlite3_total_
e8e0: 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 changes()] is ru
e8f0: 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 nning then the v
e900: 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 alue.** returned
e910: 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c is unpredictabl
e920: 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e e and not meanin
e930: 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c gful..*/.int sql
e940: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
e950: 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f es(sqlite3*);../
e960: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
e970: 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d nterrupt A Long-
e980: 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 Running Query {H
e990: 31 32 32 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 12270} <S30500>.
e9a0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 **.** This funct
e9b0: 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 ion causes any p
e9c0: 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 ending database
e9d0: 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f operation to abo
e9e0: 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e rt and.** return
e9f0: 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 at its earliest
ea00: 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 opportunity. Th
ea10: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 is routine is ty
ea20: 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 pically.** calle
ea30: 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f d in response to
ea40: 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 a user action s
ea50: 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 uch as pressing
ea60: 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 "Cancel".** or C
ea70: 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 trl-C where the
ea80: 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e user wants a lon
ea90: 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f g query operatio
eaa0: 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d n to halt.** imm
eab0: 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ediately..**.**
eac0: 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 It is safe to ca
ead0: 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 ll this routine
eae0: 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 from a thread di
eaf0: 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 fferent from the
eb00: 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 .** thread that
eb10: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e is currently run
eb20: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 ning the databas
eb30: 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 e operation. Bu
eb40: 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 t it.** is not s
eb50: 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 afe to call this
eb60: 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 routine with a
eb70: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
eb80: 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 tion] that.** is
eb90: 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 closed or might
eba0: 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 close before sq
ebb0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
ebc0: 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a ) returns..**.**
ebd0: 20 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 If an SQL opera
ebe0: 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 tion is very nea
ebf0: 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 rly finished at
ec00: 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a the time when.**
ec10: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
ec20: 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 pt() is called,
ec30: 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f then it might no
ec40: 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 t have an opport
ec50: 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 unity.** to be i
ec60: 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d nterrupted and m
ec70: 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f ight continue to
ec80: 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a completion..**.
ec90: 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 ** An SQL operat
eca0: 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 ion that is inte
ecb0: 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 rrupted will ret
ecc0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 urn [SQLITE_INTE
ecd0: 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 RRUPT]..** If th
ece0: 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 e interrupted SQ
ecf0: 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 L operation is a
ed00: 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 n INSERT, UPDATE
ed10: 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 , or DELETE.** t
ed20: 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e hat is inside an
ed30: 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 explicit transa
ed40: 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 ction, then the
ed50: 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 entire transacti
ed60: 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f on.** will be ro
ed70: 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 lled back automa
ed80: 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 tically..**.** A
ed90: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
eda0: 5f 69 6e 74 65 72 72 75 70 74 28 29 20 68 61 73 _interrupt() has
edb0: 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 no effect on SQ
edc0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 L statements.**
edd0: 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 that are started
ede0: 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 69 after sqlite3_i
edf0: 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 nterrupt() retur
ee00: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ns..**.** Requir
ee10: 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 ements:.** [H122
ee20: 37 31 5d 20 5b 48 31 32 32 37 32 5d 0a 2a 2a 0a 71] [H12272].**.
ee30: 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 ** If the databa
ee40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c se connection cl
ee50: 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 oses while [sqli
ee60: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d te3_interrupt()]
ee70: 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 .** is running t
ee80: 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 hen bad things w
ee90: 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 ill likely happe
eea0: 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 n..*/.void sqlit
eeb0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c e3_interrupt(sql
eec0: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
eed0: 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 API3REF: Determi
eee0: 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 ne If An SQL Sta
eef0: 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 tement Is Comple
ef00: 74 65 20 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 te {H10510} <S70
ef10: 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 200>.**.** These
ef20: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 routines are us
ef30: 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 eful for command
ef40: 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 -line input to d
ef50: 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a etermine if the.
ef60: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 ** currently ent
ef70: 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 ered text seems
ef80: 74 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 to form complete
ef90: 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 a SQL statement
efa0: 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 or.** if additi
efb0: 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 onal input is ne
efc0: 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 eded before send
efd0: 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 ing the text int
efe0: 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 o.** SQLite for
eff0: 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 parsing. These
f000: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
f010: 74 72 75 65 20 69 66 20 74 68 65 20 69 6e 70 75 true if the inpu
f020: 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 t string.** appe
f030: 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 ars to be a comp
f040: 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 lete SQL stateme
f050: 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 nt. A statement
f060: 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 is judged to be
f070: 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 .** complete if
f080: 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 it ends with a s
f090: 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 emicolon token a
f0a0: 6e 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67 nd is not a frag
f0b0: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 ment of a.** CRE
f0c0: 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 ATE TRIGGER stat
f0d0: 65 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f ement. Semicolo
f0e0: 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 ns that are embe
f0f0: 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 dded within.** s
f100: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f tring literals o
f110: 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 r quoted identif
f120: 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d ier names or com
f130: 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a ments are not.**
f140: 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b independent tok
f150: 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 ens (they are pa
f160: 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 rt of the token
f170: 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 in which they ar
f180: 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 e.** embedded) a
f190: 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 nd thus do not c
f1a0: 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d ount as a statem
f1b0: 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a ent terminator..
f1c0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
f1d0: 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 ines do not pars
f1e0: 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d e the SQL statem
f1f0: 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c ents thus.** wil
f200: 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e l not detect syn
f210: 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 tactically incor
f220: 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 rect SQL..**.**
f230: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 Requirements: [H
f240: 31 30 35 31 31 5d 20 5b 48 31 30 35 31 32 5d 0a 10511] [H10512].
f250: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 **.** The input
f260: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 to [sqlite3_comp
f270: 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 lete()] must be
f280: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
f290: 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e d.** UTF-8 strin
f2a0: 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 g..**.** The inp
f2b0: 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ut to [sqlite3_c
f2c0: 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 omplete16()] mus
f2d0: 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d t be a zero-term
f2e0: 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 inated.** UTF-16
f2f0: 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 string in nativ
f300: 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f e byte order..*/
f310: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d .int sqlite3_com
f320: 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 plete(const char
f330: 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 *sql);.int sqli
f340: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 te3_complete16(c
f350: 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b onst void *sql);
f360: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
f370: 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c : Register A Cal
f380: 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 lback To Handle
f390: 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f SQLITE_BUSY Erro
f3a0: 72 73 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 rs {H12310} <S40
f3b0: 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 400>.**.** This
f3c0: 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 routine sets a c
f3d0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
f3e0: 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 that might be i
f3f0: 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a nvoked whenever.
f400: 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 ** an attempt is
f410: 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 made to open a
f420: 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 database table t
f430: 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 hat another thre
f440: 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 ad.** or process
f450: 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a has locked..**.
f460: 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 63 ** If the busy c
f470: 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c allback is NULL,
f480: 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 then [SQLITE_BU
f490: 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 SY] or [SQLITE_I
f4a0: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a OERR_BLOCKED].**
f4b0: 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d is returned imm
f4c0: 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e ediately upon en
f4d0: 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c countering the l
f4e0: 6f 63 6b 2e 20 49 66 20 74 68 65 20 62 75 73 79 ock. If the busy
f4f0: 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 callback.** is
f500: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 not NULL, then t
f510: 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c he callback will
f520: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 be invoked with
f530: 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a two arguments..
f540: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
f550: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
f560: 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 handler is a cop
f570: 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 y of the void* p
f580: 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 ointer which.**
f590: 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 is the third arg
f5a0: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
f5b0: 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e _busy_handler().
f5c0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 The second arg
f5d0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 ument to.** the
f5e0: 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b handler callback
f5f0: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
f600: 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 f times that the
f610: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 busy handler ha
f620: 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 s.** been invoke
f630: 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 d for this locki
f640: 6e 67 20 65 76 65 6e 74 2e 20 20 49 66 20 74 68 ng event. If th
f650: 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 e.** busy callba
f660: 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 ck returns 0, th
f670: 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c en no additional
f680: 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 attempts are ma
f690: 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 de to.** access
f6a0: 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 the database and
f6b0: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f [SQLITE_BUSY] o
f6c0: 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f r [SQLITE_IOERR_
f6d0: 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 BLOCKED] is retu
f6e0: 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 rned..** If the
f6f0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
f700: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 non-zero, then
f710: 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a another attempt.
f720: 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 ** is made to op
f730: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
f740: 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 for reading and
f750: 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 the cycle repeat
f760: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 s..**.** The pre
f770: 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 sence of a busy
f780: 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 handler does not
f790: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 guarantee that
f7a0: 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b it will be invok
f7b0: 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 ed.** when there
f7c0: 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 is lock content
f7d0: 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 64 ion. If SQLite d
f7e0: 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 etermines that i
f7f0: 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 nvoking the busy
f800: 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c .** handler coul
f810: 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 d result in a de
f820: 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 adlock, it will
f830: 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 go ahead and ret
f840: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 urn [SQLITE_BUSY
f850: 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f ].** or [SQLITE_
f860: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 IOERR_BLOCKED] i
f870: 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 nstead of invoki
f880: 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ng the busy hand
f890: 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 ler..** Consider
f8a0: 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 a scenario wher
f8b0: 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 e one process is
f8c0: 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 holding a read
f8d0: 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 lock that.** it
f8e0: 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f is trying to pro
f8f0: 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 mote to a reserv
f900: 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 ed lock and.** a
f910: 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
f920: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 is holding a res
f930: 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 erved lock that
f940: 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 it is trying.**
f950: 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e to promote to an
f960: 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e exclusive lock.
f970: 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 The first proc
f980: 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 ess cannot proce
f990: 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 ed.** because it
f9a0: 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 is blocked by t
f9b0: 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 he second and th
f9c0: 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 e second process
f9d0: 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 cannot.** proce
f9e0: 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 ed because it is
f9f0: 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 blocked by the
fa00: 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 first. If both
fa10: 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 processes.** inv
fa20: 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e oke the busy han
fa30: 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 dlers, neither w
fa40: 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f ill make any pro
fa50: 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 gress. Therefor
fa60: 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 e,.** SQLite ret
fa70: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 urns [SQLITE_BUS
fa80: 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 Y] for the first
fa90: 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 process, hoping
faa0: 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 that this.** wi
fab0: 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 ll induce the fi
fac0: 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 rst process to r
fad0: 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 elease its read
fae0: 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a lock and allow.*
faf0: 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f * the second pro
fb00: 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e cess to proceed.
fb10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 .**.** The defau
fb20: 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b lt busy callback
fb30: 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 is NULL..**.**
fb40: 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 The [SQLITE_BUSY
fb50: 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 ] error is conve
fb60: 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f rted to [SQLITE_
fb70: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a IOERR_BLOCKED].*
fb80: 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 * when SQLite is
fb90: 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f in the middle o
fba0: 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 f a large transa
fbb0: 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 ction where all
fbc0: 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 the.** changes w
fbd0: 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f ill not fit into
fbe0: 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 the in-memory c
fbf0: 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 ache. SQLite wi
fc00: 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f ll.** already ho
fc10: 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f ld a RESERVED lo
fc20: 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 ck on the databa
fc30: 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 se file, but it
fc40: 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d needs.** to prom
fc50: 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f ote this lock to
fc60: 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 EXCLUSIVE so th
fc70: 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 at it can spill
fc80: 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 cache.** pages i
fc90: 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 nto the database
fca0: 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 file without ha
fcb0: 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 rm to concurrent
fcc0: 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 .** readers. If
fcd0: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f it is unable to
fce0: 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 promote the loc
fcf0: 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d k, then the in-m
fd00: 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 emory.** cache w
fd10: 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 ill be left in a
fd20: 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 n inconsistent s
fd30: 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 tate and so the
fd40: 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 error.** code is
fd50: 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 promoted from t
fd60: 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 he relatively be
fd70: 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 nign [SQLITE_BUS
fd80: 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 Y] to.** the mor
fd90: 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 e severe [SQLITE
fda0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e _IOERR_BLOCKED].
fdb0: 20 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 This error cod
fdc0: 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 e promotion.** f
fdd0: 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 orces an automat
fde0: 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 ic rollback of t
fdf0: 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 he changes. See
fe00: 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d the.** <a href=
fe10: 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 "/cvstrac/wiki?p
fe20: 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f =CorruptionFollo
fe30: 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a wingBusyError">.
fe40: 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c ** CorruptionFol
fe50: 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c lowingBusyError<
fe60: 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f /a> wiki page fo
fe70: 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f r a discussion o
fe80: 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 f why.** this is
fe90: 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a important..**.*
fea0: 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 * There can only
feb0: 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 be a single bus
fec0: 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 y handler define
fed0: 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 d for each.** [d
fee0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
fef0: 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 on]. Setting a
ff00: 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 new busy handler
ff10: 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 clears any.** p
ff20: 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 reviously set ha
ff30: 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 ndler. Note tha
ff40: 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 t calling [sqlit
ff50: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
ff60: 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 )].** will also
ff70: 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 set or clear the
ff80: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a busy handler..*
ff90: 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 *.** The busy ca
ffa0: 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f llback should no
ffb0: 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f t take any actio
ffc0: 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 ns which modify
ffd0: 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
ffe0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
fff0: 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 invoked the busy
10000 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 handler. Any s
10010 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 uch actions.** r
10020 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e esult in undefin
10030 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 ed behavior..**
10040 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
10050 3a 0a 2a 2a 20 5b 48 31 32 33 31 31 5d 20 5b 48 :.** [H12311] [H
10060 31 32 33 31 32 5d 20 5b 48 31 32 33 31 34 5d 20 12312] [H12314]
10070 5b 48 31 32 33 31 36 5d 20 5b 48 31 32 33 31 38 [H12316] [H12318
10080 5d 0a 2a 2a 0a 2a 2a 20 41 20 62 75 73 79 20 68 ].**.** A busy h
10090 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 andler must not
100a0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 close the databa
100b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
100c0 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 or [prepared st
100d0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e atement] that in
100e0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 voked the busy h
100f0 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 andler..*/.int s
10100 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
10110 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e ler(sqlite3*, in
10120 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c t(*)(void*,int),
10130 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*);../*.**
10140 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 CAPI3REF: Set A
10150 42 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 Busy Timeout {H1
10160 32 33 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2340} <S40410>.*
10170 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
10180 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 e sets a [sqlite
10190 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 3_busy_handler |
101a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 busy handler] t
101b0 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f hat sleeps.** fo
101c0 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d r a specified am
101d0 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 ount of time whe
101e0 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 n a table is loc
101f0 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 ked. The handle
10200 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 r.** will sleep
10210 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 multiple times u
10220 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d ntil at least "m
10230 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 s" milliseconds
10240 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 of sleeping.** h
10250 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e ave accumulated.
10260 20 7b 48 31 32 33 34 33 7d 20 41 66 74 65 72 20 {H12343} After
10270 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 "ms" millisecond
10280 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a s of sleeping,.*
10290 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 * the handler re
102a0 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 turns 0 which ca
102b0 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 uses [sqlite3_st
102c0 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a ep()] to return.
102d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ** [SQLITE_BUSY]
102e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 or [SQLITE_IOER
102f0 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a R_BLOCKED]..**.*
10300 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 * Calling this r
10310 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 outine with an a
10320 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 rgument less tha
10330 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 n or equal to ze
10340 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 ro.** turns off
10350 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 all busy handler
10360 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 s..**.** There c
10370 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e an only be a sin
10380 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 gle busy handler
10390 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 for a particula
103a0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 r.** [database c
103b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 onnection] any a
103c0 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e ny given moment.
103d0 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 If another bus
103e0 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 y handler.** was
103f0 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 defined (using
10400 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 [sqlite3_busy_h
10410 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 andler()]) prior
10420 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 to calling.** t
10430 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 his routine, tha
10440 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e t other busy han
10450 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e dler is cleared.
10460 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
10470 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 34 31 5d nts:.** [H12341]
10480 20 5b 48 31 32 33 34 33 5d 20 5b 48 31 32 33 34 [H12343] [H1234
10490 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 4].*/.int sqlite
104a0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 3_busy_timeout(s
104b0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 qlite3*, int ms)
104c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
104d0 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 F: Convenience R
104e0 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e outines For Runn
104f0 69 6e 67 20 51 75 65 72 69 65 73 20 7b 48 31 32 ing Queries {H12
10500 33 37 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 370} <S10000>.**
10510 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 .** Definition:
10520 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c A <b>result tabl
10530 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 e</b> is memory
10540 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 data structure c
10550 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a reated by the.**
10560 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 [sqlite3_get_ta
10570 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ble()] interface
10580 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c . A result tabl
10590 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a e records the.**
105a0 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 complete query
105b0 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 results from one
105c0 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 or more queries
105d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c ..**.** The tabl
105e0 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 e conceptually h
105f0 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 as a number of r
10600 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e ows and columns.
10610 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e But.** these n
10620 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 umbers are not p
10630 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c art of the resul
10640 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 t table itself.
10650 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 These.** number
10660 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 s are obtained s
10670 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 eparately. Let
10680 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 N be the number
10690 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d of rows.** and M
106a0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f be the number o
106b0 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a f columns..**.**
106c0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
106d0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
106e0 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d ointers to zero-
106f0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 terminated UTF-8
10700 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 strings..** The
10710 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 re are (N+1)*M e
10720 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 lements in the a
10730 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 rray. The first
10740 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e M pointers poin
10750 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 t.** to zero-ter
10760 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 minated strings
10770 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 that contain th
10780 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 e names of the c
10790 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 olumns..** The r
107a0 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 emaining entries
107b0 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 all point to qu
107c0 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 ery results. NU
107d0 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 LL values result
107e0 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e .** in NULL poin
107f0 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 ters. All other
10800 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 values are in t
10810 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d heir UTF-8 zero-
10820 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 terminated.** st
10830 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 ring representat
10840 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 ion as returned
10850 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by [sqlite3_colu
10860 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a mn_text()]..**.*
10870 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 * A result table
10880 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f might consist o
10890 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 f one or more me
108a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 mory allocations
108b0 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 ..** It is not s
108c0 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 afe to pass a re
108d0 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 sult table direc
108e0 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f tly to [sqlite3_
108f0 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 free()]..** A re
10900 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c sult table shoul
10910 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 d be deallocated
10920 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
10930 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a free_table()]..*
10940 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 *.** As an examp
10950 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 le of the result
10960 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 table format, s
10970 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 uppose a query r
10980 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 esult.** is as f
10990 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
109a0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
109b0 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 ** Name
109c0 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 | Age.**
109d0 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------
109e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a -------------.**
109f0 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 Alice
10a00 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 | 43.**
10a10 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c Bob |
10a20 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 28.** Ci
10a30 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a ndy | 21.*
10a40 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
10a50 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 uote>.**.** Ther
10a60 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e e are two column
10a70 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 (M==2) and thre
10a80 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 e rows (N==3).
10a90 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 Thus the.** resu
10aa0 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 lt table has 8 e
10ab0 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 ntries. Suppose
10ac0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
10ad0 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 e is stored.** i
10ae0 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 n an array names
10af0 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e azResult. Then
10b00 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 azResult holds
10b10 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a this content:.**
10b20 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
10b30 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 <pre>.**
10b40 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 azResult[0]
10b50 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 = "Name";.**
10b60 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
10b70 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 ;1] = "Age";.**
10b80 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
10b90 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 #91;2] = "Alice"
10ba0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
10bb0 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 sult[3] = "4
10bc0 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 3";.** az
10bd0 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 Result[4] =
10be0 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 "Bob";.**
10bf0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d azResult[5]
10c00 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 = "28";.**
10c10 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
10c20 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 6] = "Cindy";.**
10c30 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
10c40 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a [7] = "21";.
10c50 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
10c60 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
10c70 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
10c80 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 le() function ev
10c90 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d aluates one or m
10ca0 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e ore.** semicolon
10cb0 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 -separated SQL s
10cc0 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 tatements in the
10cd0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
10ce0 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 UTF-8.** string
10cf0 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 of its 2nd para
10d00 6d 65 74 65 72 2e 20 20 49 74 20 72 65 74 75 72 meter. It retur
10d10 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c ns a result tabl
10d20 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e e to the.** poin
10d30 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 ter given in its
10d40 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 3rd parameter..
10d50 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 **.** After the
10d60 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e calling function
10d70 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 has finished us
10d80 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 ing the result,
10d90 69 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 it should.** pas
10da0 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f s the pointer to
10db0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
10dc0 65 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 e to sqlite3_fre
10dd0 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 e_table() in ord
10de0 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 er to.** release
10df0 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 the memory that
10e00 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 was malloced.
10e10 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 Because of the w
10e20 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ay the.** [sqlit
10e30 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 e3_malloc()] hap
10e40 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 pens within sqli
10e50 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c te3_get_table(),
10e60 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 the calling.**
10e70 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f function must no
10e80 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 t try to call [s
10e90 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 qlite3_free()] d
10ea0 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a irectly. Only.*
10eb0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f * [sqlite3_free_
10ec0 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 table()] is able
10ed0 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 to release the
10ee0 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 memory properly
10ef0 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a and safely..**.*
10f00 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 * The sqlite3_ge
10f10 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 t_table() interf
10f20 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 ace is implement
10f30 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 ed as a wrapper
10f40 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 around.** [sqlit
10f50 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 e3_exec()]. The
10f60 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
10f70 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 le() routine doe
10f80 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 s not have acces
10f90 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 s.** to any inte
10fa0 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 rnal data struct
10fb0 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 ures of SQLite.
10fc0 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 It uses only th
10fd0 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 e public.** inte
10fe0 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 rface defined he
10ff0 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 re. As a conseq
11000 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 uence, errors th
11010 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a at occur in the.
11020 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 ** wrapper layer
11030 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 outside of the
11040 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 internal [sqlite
11050 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 3_exec()] call a
11060 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 re not.** reflec
11070 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e ted in subsequen
11080 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 t calls to [sqli
11090 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f te3_errcode()] o
110a0 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 r [sqlite3_errms
110b0 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 g()]..**.** Requ
110c0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
110d0 32 33 37 31 5d 20 5b 48 31 32 33 37 33 5d 20 5b 2371] [H12373] [
110e0 48 31 32 33 37 34 5d 20 5b 48 31 32 33 37 36 5d H12374] [H12376]
110f0 20 5b 48 31 32 33 37 39 5d 20 5b 48 31 32 33 38 [H12379] [H1238
11100 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 2].*/.int sqlite
11110 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 3_get_table(. s
11120 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
11130 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 /* An open
11140 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f database */. co
11150 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 nst char *zSql,
11160 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 /* SQL to be
11170 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 evaluated */.
11180 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c char ***pazResul
11190 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 t, /* Results
111a0 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f of the query */
111b0 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 . int *pnRow,
111c0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 /* Numb
111d0 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 er of result row
111e0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a s written here *
111f0 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d /. int *pnColum
11200 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d n, /* Num
11210 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f ber of result co
11220 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 lumns written he
11230 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 re */. char **p
11240 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a zErrmsg /*
11250 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 Error msg writt
11260 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f en here */.);.vo
11270 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f id sqlite3_free_
11280 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 table(char **res
11290 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ult);../*.** CAP
112a0 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 I3REF: Formatted
112b0 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 String Printing
112c0 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 Functions {H174
112d0 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 00} <S70000><S20
112e0 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 000>.**.** These
112f0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f routines are wo
11300 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 rkalikes of the
11310 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c "printf()" famil
11320 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a y of functions.*
11330 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 * from the stand
11340 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a ard C library..*
11350 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
11360 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 _mprintf() and s
11370 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 qlite3_vmprintf(
11380 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 ) routines write
11390 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 their.** result
113a0 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 s into memory ob
113b0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
113c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a ite3_malloc()]..
113d0 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 ** The strings r
113e0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 eturned by these
113f0 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 two routines sh
11400 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 ould be.** relea
11410 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f sed by [sqlite3_
11420 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 free()]. Both r
11430 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 outines return a
11440 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 .** NULL pointer
11450 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c if [sqlite3_mal
11460 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 loc()] is unable
11470 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f to allocate eno
11480 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f ugh.** memory to
11490 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 hold the result
114a0 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a ing string..**.*
114b0 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 * In sqlite3_snp
114c0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 rintf() routine
114d0 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 is similar to "s
114e0 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a nprintf()" from.
114f0 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 ** the standard
11500 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 C library. The
11510 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 result is writte
11520 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 n into the.** bu
11530 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 ffer supplied as
11540 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
11550 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 meter whose size
11560 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 is given by.**
11570 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
11580 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 ter. Note that t
11590 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a he order of the.
115a0 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 ** first two par
115b0 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 ameters is rever
115c0 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 sed from snprint
115d0 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e f(). This is an
115e0 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 .** historical a
115f0 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e ccident that can
11600 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 not be fixed wit
11610 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a hout breaking.**
11620 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
11630 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 tibility. Note
11640 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 also that sqlite
11650 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 3_snprintf().**
11660 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
11670 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 r to its buffer
11680 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e instead of the n
11690 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 umber of.** char
116a0 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 acters actually
116b0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 written into the
116c0 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d buffer. We adm
116d0 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e it that.** the n
116e0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 umber of charact
116f0 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c ers written woul
11700 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 d be a more usef
11710 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c ul return.** val
11720 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 ue but we cannot
11730 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c change the impl
11740 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 ementation of sq
11750 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
11760 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 .** now without
11770 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 breaking compati
11780 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 bility..**.** As
11790 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 long as the buf
117a0 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 fer size is grea
117b0 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 ter than zero, s
117c0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
117d0 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 ).** guarantees
117e0 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 that the buffer
117f0 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 is always zero-t
11800 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 erminated. The
11810 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 first.** paramet
11820 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f er "n" is the to
11830 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 tal size of the
11840 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e buffer, includin
11850 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 g space for.** t
11860 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 he zero terminat
11870 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 or. So the long
11880 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 est string that
11890 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c can be completel
118a0 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c y.** written wil
118b0 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 l be n-1 charact
118c0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ers..**.** These
118d0 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d routines all im
118e0 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 plement some add
118f0 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 itional formatti
11900 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 ng.** options th
11910 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f at are useful fo
11920 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 r constructing S
11930 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a QL statements..*
11940 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 * All of the usu
11950 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d al printf() form
11960 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 atting options a
11970 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 pply. In additi
11980 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 on, there.** is
11990 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 are "%q", "%Q",
119a0 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 and "%z" options
119b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f ..**.** The %q o
119c0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
119d0 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 %s in that it s
119e0 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c ubstitutes a nul
119f0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 l-terminated.**
11a00 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 string from the
11a10 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 argument list.
11a20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 But %q also doub
11a30 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 les every '\'' c
11a40 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 haracter..** %q
11a50 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 is designed for
11a60 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 use inside a str
11a70 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 ing literal. By
11a80 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 doubling each '
11a90 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 \''.** character
11aa0 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 it escapes that
11ab0 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 character and a
11ac0 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 llows it to be i
11ad0 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 nserted into.**
11ae0 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a the string..**.*
11af0 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 * For example, a
11b00 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 ssume the string
11b10 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 variable zText
11b20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 contains text as
11b30 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
11b40 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
11b50 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 >.** char *zTex
11b60 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 t = "It's a happ
11b70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 y day!";.** </pr
11b80 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
11b90 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 **.** One can us
11ba0 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 e this text in a
11bb0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 n SQL statement
11bc0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
11bd0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
11be0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 re>.** char *zS
11bf0 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 QL = sqlite3_mpr
11c00 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 intf("INSERT INT
11c10 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 O table VALUES('
11c20 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a %q')", zText);.*
11c30 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 * sqlite3_exec(
11c40 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 db, zSQL, 0, 0,
11c50 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 0);.** sqlite3_
11c60 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c free(zSQL);.** <
11c70 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
11c80 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 e>.**.** Because
11c90 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 the %q format s
11ca0 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 tring is used, t
11cb0 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 he '\'' characte
11cc0 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 r in zText.** is
11cd0 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 escaped and the
11ce0 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 SQL generated i
11cf0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a s as follows:.**
11d00 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
11d10 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 <pre>.** INSERT
11d20 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c INTO table1 VAL
11d30 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 UES('It''s a hap
11d40 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 py day!').** </p
11d50 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
11d60 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 .**.** This is c
11d70 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 orrect. Had we
11d80 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 used %s instead
11d90 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 of %q, the gener
11da0 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c ated SQL.** woul
11db0 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 d have looked li
11dc0 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c ke this:.**.** <
11dd0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
11de0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f .** INSERT INTO
11df0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 table1 VALUES('
11e00 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 It's a happy day
11e10 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f !');.** </pre></
11e20 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
11e30 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 * This second ex
11e40 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 ample is an SQL
11e50 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 syntax error. A
11e60 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 s a general rule
11e70 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 you should.** a
11e80 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 lways use %q ins
11e90 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 tead of %s when
11ea0 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 inserting text i
11eb0 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 nto a string lit
11ec0 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eral..**.** The
11ed0 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 %Q option works
11ee0 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 like %q except i
11ef0 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 t also adds sing
11f00 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 le quotes around
11f10 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 .** the outside
11f20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 of the total str
11f30 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c ing. Additional
11f40 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d ly, if the param
11f50 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 eter in the.** a
11f60 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 rgument list is
11f70 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
11f80 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 %Q substitutes t
11f90 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 he text "NULL" (
11fa0 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c without.** singl
11fb0 65 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 e quotes) in pla
11fc0 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 ce of the %Q opt
11fd0 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 ion. So, for ex
11fe0 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 ample, one could
11ff0 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f say:.**.** <blo
12000 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
12010 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 char *zSQL = s
12020 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 qlite3_mprintf("
12030 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
12040 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a e VALUES(%Q)", z
12050 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 Text);.** sqlit
12060 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c e3_exec(db, zSQL
12070 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 , 0, 0, 0);.**
12080 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 sqlite3_free(zSQ
12090 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 L);.** </pre></b
120a0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
120b0 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 The code above
120c0 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f will render a co
120d0 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d rrect SQL statem
120e0 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a ent in the zSQL.
120f0 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e ** variable even
12100 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 if the zText va
12110 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c riable is a NULL
12120 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
12130 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 The "%z" formatt
12140 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 ing option works
12150 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 exactly like "%
12160 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 s" with the.** a
12170 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 ddition that aft
12180 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 er the string ha
12190 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 s been read and
121a0 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 copied into.** t
121b0 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 he result, [sqli
121c0 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 te3_free()] is c
121d0 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 alled on the inp
121e0 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d ut string. {END}
121f0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
12200 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 34 30 33 5d nts:.** [H17403]
12210 20 5b 48 31 37 34 30 36 5d 20 5b 48 31 37 34 30 [H17406] [H1740
12220 37 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 7].*/.char *sqli
12230 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 te3_mprintf(cons
12240 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 t char*,...);.ch
12250 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 ar *sqlite3_vmpr
12260 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a intf(const char*
12270 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 , va_list);.char
12280 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e *sqlite3_snprin
12290 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e tf(int,char*,con
122a0 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a st char*, ...);.
122b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
122c0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 Memory Allocati
122d0 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 48 31 on Subsystem {H1
122e0 37 33 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 7300} <S20000>.*
122f0 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 *.** The SQLite
12300 63 6f 72 65 20 20 75 73 65 73 20 74 68 65 73 65 core uses these
12310 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 three routines
12320 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f for all of its o
12330 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d wn.** internal m
12340 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
12350 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 needs. "Core" i
12360 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 n the previous s
12370 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 entence.** does
12380 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 not include oper
12390 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 ating-system spe
123a0 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d cific VFS implem
123b0 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a entation. The.*
123c0 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 * Windows VFS us
123d0 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 es native malloc
123e0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f () and free() fo
123f0 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e r some operation
12400 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c s..**.** The sql
12410 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f ite3_malloc() ro
12420 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 utine returns a
12430 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f pointer to a blo
12440 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 ck.** of memory
12450 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 at least N bytes
12460 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 in length, wher
12470 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d e N is the param
12480 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 eter..** If sqli
12490 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 te3_malloc() is
124a0 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e unable to obtain
124b0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 sufficient free
124c0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 .** memory, it r
124d0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
124e0 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20 70 inter. If the p
124f0 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a arameter N to.**
12500 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
12510 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 ) is zero or neg
12520 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 ative then sqlit
12530 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 e3_malloc() retu
12540 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f rns.** a NULL po
12550 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c inter..**.** Cal
12560 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 ling sqlite3_fre
12570 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 e() with a point
12580 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 er previously re
12590 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c turned.** by sql
125a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 ite3_malloc() or
125b0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
125c0 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 () releases that
125d0 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 memory so.** th
125e0 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 at it might be r
125f0 65 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c 69 eused. The sqli
12600 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 te3_free() routi
12610 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 ne is.** a no-op
12620 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 if is called wi
12630 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 th a NULL pointe
12640 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 r. Passing a NU
12650 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f LL pointer.** to
12660 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
12670 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 is harmless. Af
12680 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c ter being freed,
12690 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c memory.** shoul
126a0 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 d neither be rea
126b0 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 d nor written.
126c0 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 Even reading pre
126d0 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a viously freed.**
126e0 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 memory might re
126f0 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e sult in a segmen
12700 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 tation fault or
12710 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 other severe err
12720 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f or..** Memory co
12730 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d rruption, a segm
12740 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 entation fault,
12750 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 or other severe
12760 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 error.** might r
12770 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 esult if sqlite3
12780 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 _free() is calle
12790 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c d with a non-NUL
127a0 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a L pointer that.*
127b0 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e * was not obtain
127c0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ed from sqlite3_
127d0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 malloc() or sqli
127e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a te3_realloc()..*
127f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
12800 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 _realloc() inter
12810 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f face attempts to
12820 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 resize a.** pri
12830 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 or memory alloca
12840 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 tion to be at le
12850 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 ast N bytes, whe
12860 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 re N is the.** s
12870 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e econd parameter.
12880 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c The memory all
12890 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 ocation to be re
128a0 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 sized is the fir
128b0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e st.** parameter.
128c0 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 If the first p
128d0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
128e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a te3_realloc().**
128f0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
12900 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 er then its beha
12910 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 vior is identica
12920 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 l to calling.**
12930 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e sqlite3_malloc(N
12940 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 ) where N is the
12950 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
12960 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 r to sqlite3_rea
12970 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 lloc()..** If th
12980 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
12990 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
129a0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 alloc() is zero
129b0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 or.** negative t
129c0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
129d0 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 is exactly the
129e0 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a same as calling.
129f0 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 ** sqlite3_free(
12a00 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 P) where P is th
12a10 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
12a20 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 r to sqlite3_rea
12a30 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 lloc()..** sqlit
12a40 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 e3_realloc() ret
12a50 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
12a60 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 o a memory alloc
12a70 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c ation.** of at l
12a80 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 east N bytes in
12a90 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 size or NULL if
12aa0 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 sufficient memor
12ab0 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 y is unavailable
12ac0 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 ..** If M is the
12ad0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 size of the pri
12ae0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 or allocation, t
12af0 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 hen min(N,M) byt
12b00 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 es.** of the pri
12b10 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 or allocation ar
12b20 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 e copied into th
12b30 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 e beginning of b
12b40 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a uffer returned.*
12b50 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 * by sqlite3_rea
12b60 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 lloc() and the p
12b70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
12b80 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 is freed..** If
12b90 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
12ba0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 ) returns NULL,
12bb0 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 then the prior a
12bc0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 llocation.** is
12bd0 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a not freed..**.**
12be0 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 The memory retu
12bf0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
12c00 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c malloc() and sql
12c10 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a ite3_realloc().*
12c20 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 * is always alig
12c30 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 ned to at least
12c40 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 an 8 byte bounda
12c50 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 ry. {END}.**.**
12c60 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c The default impl
12c70 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
12c80 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
12c90 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 ion subsystem us
12ca0 65 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 es.** the malloc
12cb0 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e (), realloc() an
12cc0 64 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 d free() provide
12cd0 64 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 d by the standar
12ce0 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 d C library..**
12cf0 7b 48 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 {H17382} However
12d00 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 , if SQLite is c
12d10 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
12d20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 .** SQLITE_MEMOR
12d30 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 Y_SIZE=<i>NNN</i
12d40 3e 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 > C preprocessor
12d50 20 6d 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69 macro (where <i
12d60 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 >NNN</i>.** is a
12d70 6e 20 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e n integer), then
12d80 20 53 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 SQLite create a
12d90 20 73 74 61 74 69 63 20 61 72 72 61 79 20 6f 66 static array of
12da0 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e at least.** <i>
12db0 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e NNN</i> bytes in
12dc0 20 73 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74 size and uses t
12dd0 68 61 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c hat array for al
12de0 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 l of its dynamic
12df0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
12e00 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e ation needs. {EN
12e10 44 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d D} Additional m
12e20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
12e30 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 options.** may b
12e40 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
12e50 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a e releases..**.*
12e60 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 * In SQLite vers
12e70 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e ion 3.5.0 and 3.
12e80 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 5.1, it was poss
12e90 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a ible to define.*
12ea0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 * the SQLITE_OMI
12eb0 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 T_MEMORY_ALLOCAT
12ec0 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 ION which would
12ed0 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d cause the built-
12ee0 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 in.** implementa
12ef0 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f tion of these ro
12f00 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 utines to be omi
12f10 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 tted. That capa
12f20 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 bility.** is no
12f30 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e longer provided.
12f40 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 Only built-in
12f50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
12f60 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a s can be used..*
12f70 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 *.** The Windows
12f80 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 OS interface la
12f90 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 yer calls.** the
12fa0 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 system malloc()
12fb0 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 and free() dire
12fc0 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 ctly when conver
12fd0 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 ting.** filename
12fe0 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 s between the UT
12ff0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 F-8 encoding use
13000 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 d by SQLite.** a
13010 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 nd whatever file
13020 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 name encoding is
13030 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 used by the par
13040 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a ticular Windows.
13050 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e ** installation.
13060 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 Memory allocat
13070 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 ion errors are d
13080 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 etected, but.**
13090 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 they are reporte
130a0 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 d back as [SQLIT
130b0 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a E_CANTOPEN] or.*
130c0 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d * [SQLITE_IOERR]
130d0 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 rather than [SQ
130e0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a LITE_NOMEM]..**.
130f0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
13100 0a 2a 2a 20 5b 48 31 37 33 30 33 5d 20 5b 48 31 .** [H17303] [H1
13110 37 33 30 34 5d 20 5b 48 31 37 33 30 35 5d 20 5b 7304] [H17305] [
13120 48 31 37 33 30 36 5d 20 5b 48 31 37 33 31 30 5d H17306] [H17310]
13130 20 5b 48 31 37 33 31 32 5d 20 5b 48 31 37 33 31 [H17312] [H1731
13140 35 5d 20 5b 48 31 37 33 31 38 5d 0a 2a 2a 20 5b 5] [H17318].** [
13150 48 31 37 33 32 31 5d 20 5b 48 31 37 33 32 32 5d H17321] [H17322]
13160 20 5b 48 31 37 33 32 33 5d 0a 2a 2a 0a 2a 2a 20 [H17323].**.**
13170 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 The pointer argu
13180 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 ments to [sqlite
13190 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 3_free()] and [s
131a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
131b0 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 ].** must be eit
131c0 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 her NULL or else
131d0 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e pointers obtain
131e0 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a ed from a prior.
131f0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 ** invocation of
13200 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
13210 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
13220 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 realloc()] that
13230 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 have.** not yet
13240 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a been released..*
13250 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
13260 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 tion must not re
13270 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 ad or write any
13280 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f part of.** a blo
13290 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 ck of memory aft
132a0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 er it has been r
132b0 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a eleased using.**
132c0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
132d0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
132e0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 alloc()]..*/.voi
132f0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f d *sqlite3_mallo
13300 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 c(int);.void *sq
13310 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f lite3_realloc(vo
13320 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 id*, int);.void
13330 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 sqlite3_free(voi
13340 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
13350 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
13360 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 ocator Statistic
13370 73 20 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 s {H17370} <S302
13380 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 10>.**.** SQLite
13390 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 provides these
133a0 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 two interfaces f
133b0 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 or reporting on
133c0 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 the status.** of
133d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 the [sqlite3_ma
133e0 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 lloc()], [sqlite
133f0 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 3_free()], and [
13400 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
13410 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 )].** routines,
13420 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 which form the b
13430 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 uilt-in memory a
13440 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 llocation subsys
13450 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 tem..**.** Requi
13460 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 rements:.** [H17
13470 33 37 31 5d 20 5b 48 31 37 33 37 33 5d 20 5b 48 371] [H17373] [H
13480 31 37 33 37 34 5d 20 5b 48 31 37 33 37 35 5d 0a 17374] [H17375].
13490 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 */.sqlite3_int64
134a0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f sqlite3_memory_
134b0 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 used(void);.sqli
134c0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
134d0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
134e0 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 er(int resetFlag
134f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
13500 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f EF: Pseudo-Rando
13510 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 m Number Generat
13520 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 30 or {H17390} <S20
13530 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 000>.**.** SQLit
13540 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 e contains a hig
13550 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f h-quality pseudo
13560 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 -random number g
13570 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 enerator (PRNG)
13580 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 used to.** selec
13590 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 t random [ROWID
135a0 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 | ROWIDs] when i
135b0 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 nserting new rec
135c0 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c ords into a tabl
135d0 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 e that.** alread
135e0 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 y uses the large
135f0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 st possible [ROW
13600 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 ID]. The PRNG i
13610 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a s also used for.
13620 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 ** the build-in
13630 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e random() and ran
13640 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 domblob() SQL fu
13650 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 nctions. This i
13660 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a nterface allows.
13670 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** applications
13680 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 to access the sa
13690 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 me PRNG for othe
136a0 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a r purposes..**.*
136b0 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 * A call to this
136c0 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 routine stores
136d0 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f N bytes of rando
136e0 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 mness into buffe
136f0 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 r P..**.** The f
13700 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 irst time this r
13710 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 outine is invoke
13720 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e d (either intern
13730 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 ally or by.** th
13740 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 e application) t
13750 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 he PRNG is seede
13760 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 d using randomne
13770 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 ss obtained.** f
13780 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e rom the xRandomn
13790 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 ess method of th
137a0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 e default [sqlit
137b0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a e3_vfs] object..
137c0 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 ** On all subseq
137d0 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 uent invocations
137e0 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e , the pseudo-ran
137f0 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 domness is gener
13800 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c ated.** internal
13810 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 ly and without r
13820 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b ecourse to the [
13830 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 sqlite3_vfs] xRa
13840 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 ndomness.** meth
13850 6f 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 od..**.** Requir
13860 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 ements:.** [H173
13870 39 32 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 92].*/.void sqli
13880 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 te3_randomness(i
13890 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a nt N, void *P);.
138a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
138b0 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 Compile-Time Au
138c0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c thorization Call
138d0 62 61 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c backs {H12500} <
138e0 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S70100>.**.** Th
138f0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 is routine regis
13900 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 ters a authorize
13910 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 r callback with
13920 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 a particular.**
13930 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
13940 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 tion], supplied
13950 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
13960 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 ument..** The au
13970 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
13980 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 k is invoked as
13990 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 SQL statements a
139a0 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 re being compile
139b0 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 d.** by [sqlite3
139c0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 _prepare()] or i
139d0 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c ts variants [sql
139e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
139f0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
13a00 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 prepare16()] and
13a10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
13a20 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 e16_v2()]. At v
13a30 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 arious.** points
13a40 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 during the comp
13a50 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c ilation process,
13a60 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 as logic is bei
13a70 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f ng created.** to
13a80 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 perform various
13a90 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 actions, the au
13aa0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
13ab0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a k is invoked to.
13ac0 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 ** see if those
13ad0 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f actions are allo
13ae0 77 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 wed. The author
13af0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 izer callback sh
13b00 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b ould.** return [
13b10 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c SQLITE_OK] to al
13b20 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 low the action,
13b30 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
13b40 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a to disallow the.
13b50 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 ** specific acti
13b60 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 on but allow the
13b70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
13b80 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 o continue to be
13b90 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 .** compiled, or
13ba0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 [SQLITE_DENY] t
13bb0 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 o cause the enti
13bc0 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 re SQL statement
13bd0 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 to be.** reject
13be0 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 ed with an error
13bf0 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 . If the author
13c00 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 izer callback re
13c10 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c turns.** any val
13c20 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 ue other than [S
13c30 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b QLITE_IGNORE], [
13c40 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b SQLITE_OK], or [
13c50 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 SQLITE_DENY].**
13c60 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 then the [sqlite
13c70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
13c80 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 or equivalent ca
13c90 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 ll that triggere
13ca0 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 d.** the authori
13cb0 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 zer will fail wi
13cc0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 th an error mess
13cd0 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 age..**.** When
13ce0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
13cf0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
13d00 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 , that means the
13d10 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 operation.** re
13d20 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 quested is ok.
13d30 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 When the callbac
13d40 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 k returns [SQLIT
13d50 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 E_DENY], the.**
13d60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
13d70 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 _v2()] or equiva
13d80 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 lent call that t
13d90 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 riggered the.**
13da0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 authorizer will
13db0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 fail with an err
13dc0 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 or message expla
13dd0 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 ining that.** ac
13de0 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 cess is denied.
13df0 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a If the authoriz
13e00 65 72 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 er code is [SQLI
13e10 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 TE_READ].** and
13e20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
13e30 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e urns [SQLITE_IGN
13e40 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a ORE] then the.**
13e50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
13e60 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 ment] statement
13e70 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 is constructed t
13e80 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 o substitute.**
13e90 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 a NULL value in
13ea0 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 place of the tab
13eb0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 le column that w
13ec0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 ould have.** bee
13ed0 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 n read if [SQLIT
13ee0 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 E_OK] had been r
13ef0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 eturned. The [S
13f00 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a QLITE_IGNORE].**
13f10 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 return can be u
13f20 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 sed to deny an u
13f30 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 ntrusted user ac
13f40 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 cess to individu
13f50 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 al.** columns of
13f60 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 a table..**.**
13f70 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
13f80 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f ter to the autho
13f90 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
13fa0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
13fb0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 third.** paramet
13fc0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
13fd0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
13fe0 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 54 68 () interface. Th
13ff0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
14000 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c er.** to the cal
14010 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 lback is an inte
14020 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 ger [SQLITE_COPY
14030 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 | action code]
14040 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a that specifies.*
14050 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 * the particular
14060 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 action to be au
14070 74 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 68 thorized. The th
14080 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 ird through sixt
14090 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 h parameters.**
140a0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
140b0 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 are zero-termina
140c0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 ted strings that
140d0 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f contain additio
140e0 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 nal.** details a
140f0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 bout the action
14100 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 to be authorized
14110 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f ..**.** An autho
14120 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 rizer is used wh
14130 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 en [sqlite3_prep
14140 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d are | preparing]
14150 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
14160 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 ts from an untru
14170 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 sted source, to
14180 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 ensure that the
14190 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
141a0 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 * do not try to
141b0 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 access data they
141c0 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 are not allowed
141d0 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 to see, or that
141e0 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 they do not.**
141f0 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d try to execute m
14200 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 alicious stateme
14210 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 nts that damage
14220 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 the database. F
14230 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 or.** example, a
14240 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 n application ma
14250 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 y allow a user t
14260 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 o enter arbitrar
14270 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 y.** SQL queries
14280 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 for evaluation
14290 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 by a database.
142a0 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 But the applicat
142b0 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 ion does.** not
142c0 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f want the user to
142d0 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 be able to make
142e0 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 arbitrary chang
142f0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 es to the.** dat
14300 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f abase. An autho
14310 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e rizer could then
14320 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 be put in place
14330 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 while the.** us
14340 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 er-entered SQL i
14350 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 s being [sqlite3
14360 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 _prepare | prepa
14370 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 red] that.** dis
14380 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e allows everythin
14390 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 g except [SELECT
143a0 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a ] statements..**
143b0 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 .** Applications
143c0 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 that need to pr
143d0 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 ocess SQL from u
143e0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 ntrusted sources
143f0 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 .** might also c
14400 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 onsider lowering
14410 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 resource limits
14420 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
14430 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 limit()].** and
14440 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 limiting databas
14450 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 e size using the
14460 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 [max_page_count
14470 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e ] [PRAGMA].** in
14480 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 addition to usi
14490 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 ng an authorizer
144a0 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 ..**.** Only a s
144b0 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 ingle authorizer
144c0 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 can be in place
144d0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 on a database c
144e0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 onnection.** at
144f0 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 a time. Each ca
14500 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 ll to sqlite3_se
14510 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 t_authorizer ove
14520 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 rrides the.** pr
14530 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 evious call. Di
14540 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 sable the author
14550 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 izer by installi
14560 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 ng a NULL callba
14570 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f ck..** The autho
14580 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 rizer is disable
14590 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a d by default..**
145a0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a .** The authoriz
145b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 er callback must
145c0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 not do anything
145d0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 that will modif
145e0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 y.** the databas
145f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 e connection tha
14600 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 t invoked the au
14610 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
14620 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 k..** Note that
14630 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
14640 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 _v2()] and [sqli
14650 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 te3_step()] both
14660 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a modify their.**
14670 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
14680 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 tions for the me
14690 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 aning of "modify
146a0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 " in this paragr
146b0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 aph..**.** When
146c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
146d0 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 _v2()] is used t
146e0 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 o prepare a stat
146f0 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 ement, the.** st
14700 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 atement might be
14710 20 72 65 70 72 65 70 61 72 65 64 20 64 75 72 69 reprepared duri
14720 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ng [sqlite3_step
14730 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a ()] due to a .**
14740 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 schema change.
14750 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c Hence, the appl
14760 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 ication should e
14770 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a nsure that the.*
14780 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 * correct author
14790 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 izer callback re
147a0 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 mains in place d
147b0 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 uring the [sqlit
147c0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a e3_step()]..**.*
147d0 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 * Note that the
147e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
147f0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f ack is invoked o
14800 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 nly during.** [s
14810 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
14820 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 ] or its variant
14830 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f s. Authorizatio
14840 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 n is not.** perf
14850 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 ormed during sta
14860 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f tement evaluatio
14870 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 n in [sqlite3_st
14880 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 ep()]..**.** Req
14890 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
148a0 31 32 35 30 31 5d 20 5b 48 31 32 35 30 32 5d 20 12501] [H12502]
148b0 5b 48 31 32 35 30 33 5d 20 5b 48 31 32 35 30 34 [H12503] [H12504
148c0 5d 20 5b 48 31 32 35 30 35 5d 20 5b 48 31 32 35 ] [H12505] [H125
148d0 30 36 5d 20 5b 48 31 32 35 30 37 5d 20 5b 48 31 06] [H12507] [H1
148e0 32 35 31 30 5d 0a 2a 2a 20 5b 48 31 32 35 31 31 2510].** [H12511
148f0 5d 20 5b 48 31 32 35 31 32 5d 20 5b 48 31 32 35 ] [H12512] [H125
14900 32 30 5d 20 5b 48 31 32 35 32 31 5d 20 5b 48 31 20] [H12521] [H1
14910 32 35 32 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 2522].*/.int sql
14920 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
14930 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c zer(. sqlite3*,
14940 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 . int (*xAuth)(
14950 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
14960 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
14970 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f *,const char*,co
14980 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f nst char*),. vo
14990 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b id *pUserData.);
149a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
149b0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 : Authorizer Ret
149c0 75 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39 urn Codes {H1259
149d0 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 0} <H12500>.**.*
149e0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 * The [sqlite3_s
149f0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 et_authorizer |
14a00 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
14a10 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 ack function] mu
14a20 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 st.** return eit
14a30 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 her [SQLITE_OK]
14a40 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 or one of these
14a50 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e two constants in
14a60 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 order.** to sig
14a70 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 nal SQLite wheth
14a80 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 er or not the ac
14a90 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 tion is permitte
14aa0 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b d. See the.** [
14ab0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
14ac0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 orizer | authori
14ad0 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f zer documentatio
14ae0 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 n] for additiona
14af0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e l.** information
14b00 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
14b10 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f ITE_DENY 1 /
14b20 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 * Abort the SQL
14b30 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 statement with a
14b40 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 n error */.#defi
14b50 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 ne SQLITE_IGNORE
14b60 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 2 /* Don't al
14b70 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 low access, but
14b80 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 don't generate a
14b90 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a n error */../*.*
14ba0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 * CAPI3REF: Auth
14bb0 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f orizer Action Co
14bc0 64 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 des {H12550} <H1
14bd0 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 2500>.**.** The
14be0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
14bf0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 horizer()] inter
14c00 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 face registers a
14c10 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
14c20 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e on.** that is in
14c30 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 voked to authori
14c40 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 ze certain SQL s
14c50 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 tatement actions
14c60 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 . The.** second
14c70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
14c80 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e e callback is an
14c90 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 integer code th
14ca0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 at specifies.**
14cb0 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 what action is b
14cc0 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e eing authorized.
14cd0 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 These are the
14ce0 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 integer action c
14cf0 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 odes that.** the
14d00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
14d10 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 back may be pass
14d20 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ed..**.** These
14d30 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 action code valu
14d40 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 es signify what
14d50 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f kind of operatio
14d60 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 n is to be.** au
14d70 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 thorized. The 3
14d80 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d rd and 4th param
14d90 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 eters to the aut
14da0 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 horization.** ca
14db0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
14dc0 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 will be paramete
14dd0 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e rs or NULL depen
14de0 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 ding on which of
14df0 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 these.** codes
14e00 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 is used as the s
14e10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e econd parameter.
14e20 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 The 5th parame
14e30 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 ter to the.** au
14e40 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
14e50 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 k is the name of
14e60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 the database ("
14e70 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a main", "temp",.*
14e80 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 * etc.) if appli
14e90 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 cable. The 6th
14ea0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
14eb0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
14ec0 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e back.** is the n
14ed0 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 ame of the inner
14ee0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 -most trigger or
14ef0 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 view that is re
14f00 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a sponsible for.**
14f10 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 the access atte
14f20 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 mpt or NULL if t
14f30 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d his access attem
14f40 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 pt is directly f
14f50 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c rom.** top-level
14f60 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a SQL code..**.**
14f70 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
14f80 2a 20 5b 48 31 32 35 35 31 5d 20 5b 48 31 32 35 * [H12551] [H125
14f90 35 32 5d 20 5b 48 31 32 35 35 33 5d 20 5b 48 31 52] [H12553] [H1
14fa0 32 35 35 34 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2554].*/./******
14fb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
14fc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
14fd0 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a ***** 3rd ******
14fe0 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a ****** 4th *****
14ff0 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 ******/.#define
15000 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e SQLITE_CREATE_IN
15010 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 DEX 1
15020 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
15030 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
15040 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
15050 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 QLITE_CREATE_TAB
15060 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 LE 2
15070 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
15080 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
15090 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
150a0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
150b0 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f _INDEX 3 /
150c0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
150d0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
150e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
150f0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
15100 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a TABLE 4 /*
15110 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
15120 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
15130 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
15140 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 TE_CREATE_TEMP_T
15150 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 RIGGER 5 /*
15160 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
15170 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
15180 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
15190 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 E_CREATE_TEMP_VI
151a0 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 EW 6 /* V
151b0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
151c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
151d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
151e0 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 _CREATE_TRIGGER
151f0 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 7 /* Tr
15200 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 igger Name Ta
15210 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
15220 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
15230 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 CREATE_VIEW
15240 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 8 /* Vie
15250 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c w Name NUL
15260 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
15270 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
15280 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 ELETE
15290 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 9 /* Tabl
152a0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
152b0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
152c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
152d0 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 OP_INDEX
152e0 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 10 /* Index
152f0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
15300 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
15310 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
15320 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 P_TABLE
15330 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 11 /* Table
15340 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
15350 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
15360 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
15370 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 _TEMP_INDEX
15380 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 12 /* Index N
15390 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
153a0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
153b0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
153c0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 TEMP_TABLE
153d0 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 13 /* Table Na
153e0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
153f0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
15400 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
15410 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 EMP_TRIGGER 1
15420 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 4 /* Trigger N
15430 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
15440 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
15450 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
15460 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 MP_VIEW 15
15470 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View Name
15480 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
15490 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
154a0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 SQLITE_DROP_TRI
154b0 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 GGER 16
154c0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
154d0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
154e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
154f0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 SQLITE_DROP_VIEW
15500 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 17
15510 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
15520 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
15530 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
15540 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 QLITE_INSERT
15550 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 18
15560 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
15570 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
15580 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
15590 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 LITE_PRAGMA
155a0 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 19 /
155b0 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 * Pragma Name
155c0 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 1st arg or NUL
155d0 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c L */.#define SQL
155e0 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 ITE_READ
155f0 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 /*
15600 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
15610 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 Column Name
15620 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
15630 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 TE_SELECT
15640 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 21 /*
15650 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
15660 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
15670 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
15680 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 E_TRANSACTION
15690 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 22 /* O
156a0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e peration N
156b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
156c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
156d0 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 _UPDATE
156e0 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 23 /* Ta
156f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f ble Name Co
15700 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f lumn Name */
15710 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
15720 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 ATTACH
15730 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 24 /* Fil
15740 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c ename NUL
15750 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
15760 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
15770 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 ETACH
15780 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 25 /* Data
15790 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c base Name NULL
157a0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
157b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c define SQLITE_AL
157c0 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 TER_TABLE
157d0 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 26 /* Datab
157e0 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 ase Name Table
157f0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
15800 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 efine SQLITE_REI
15810 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 NDEX
15820 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 27 /* Index
15830 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
15840 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
15850 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c fine SQLITE_ANAL
15860 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 YZE
15870 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 28 /* Table N
15880 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
15890 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
158a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
158b0 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 E_VTABLE
158c0 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 29 /* Table Na
158d0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e me Module N
158e0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
158f0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 ne SQLITE_DROP_V
15900 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 TABLE 3
15910 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 0 /* Table Nam
15920 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 e Module Na
15930 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
15940 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f e SQLITE_FUNCTIO
15950 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 N 31
15960 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 /* NULL
15970 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e Function N
15980 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 ame */.#define
15990 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e SQLITE_SAVEPOIN
159a0 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 T 32
159b0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 /* Operation
159c0 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e Savepoint N
159d0 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ame */.#define
159e0 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 SQLITE_COPY
159f0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 0
15a00 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 /* No longer us
15a10 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ed */../*.** CAP
15a20 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 I3REF: Tracing A
15a30 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e nd Profiling Fun
15a40 63 74 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 ctions {H12280}
15a50 3c 53 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 <S60400>.** EXPE
15a60 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
15a70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
15a80 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 gister callback
15a90 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 functions that c
15aa0 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a an be used for.*
15ab0 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 * tracing and pr
15ac0 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 ofiling the exec
15ad0 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 ution of SQL sta
15ae0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 tements..**.** T
15af0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
15b00 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 tion registered
15b10 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 by sqlite3_trace
15b20 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 () is invoked at
15b30 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 .** various time
15b40 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 s when an SQL st
15b50 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 atement is being
15b60 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 run by [sqlite3
15b70 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 _step()]..** The
15b80 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
15b90 73 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 s a UTF-8 render
15ba0 69 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73 ing of the SQL s
15bb0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a tatement text.**
15bc0 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e as the statemen
15bd0 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 t first begins e
15be0 78 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74 xecuting. Addit
15bf0 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 ional callbacks
15c00 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 occur.** as each
15c10 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 triggered subpr
15c20 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 ogram is entered
15c30 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 . The callbacks
15c40 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a for triggers.**
15c50 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 contain a UTF-8
15c60 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 SQL comment tha
15c70 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 t identifies the
15c80 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 trigger..**.**
15c90 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e The callback fun
15ca0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 ction registered
15cb0 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 by sqlite3_prof
15cc0 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ile() is invoked
15cd0 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 .** as each SQL
15ce0 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 statement finish
15cf0 65 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65 es. The profile
15d00 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 callback contai
15d10 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e ns.** the origin
15d20 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 al statement tex
15d30 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 t and an estimat
15d40 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 e of wall-clock
15d50 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c time.** of how l
15d60 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 ong that stateme
15d70 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a nt took to run..
15d80 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
15d90 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 38 31 5d 20 ts:.** [H12281]
15da0 5b 48 31 32 32 38 32 5d 20 5b 48 31 32 32 38 33 [H12282] [H12283
15db0 5d 20 5b 48 31 32 32 38 34 5d 20 5b 48 31 32 32 ] [H12284] [H122
15dc0 38 35 5d 20 5b 48 31 32 32 38 37 5d 20 5b 48 31 85] [H12287] [H1
15dd0 32 32 38 38 5d 20 5b 48 31 32 32 38 39 5d 0a 2a 2288] [H12289].*
15de0 2a 20 5b 48 31 32 32 39 30 5d 0a 2a 2f 0a 53 51 * [H12290].*/.SQ
15df0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 LITE_EXPERIMENTA
15e00 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f L void *sqlite3_
15e10 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 trace(sqlite3*,
15e20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f void(*xTrace)(vo
15e30 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 id*,const char*)
15e40 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 , void*);.SQLITE
15e50 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f _EXPERIMENTAL vo
15e60 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 id *sqlite3_prof
15e70 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 ile(sqlite3*,.
15e80 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 void(*xProfile)
15e90 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 (void*,const cha
15ea0 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 r*,sqlite3_uint6
15eb0 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 4), void*);../*.
15ec0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 ** CAPI3REF: Que
15ed0 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c ry Progress Call
15ee0 62 61 63 6b 73 20 7b 48 31 32 39 31 30 7d 20 3c backs {H12910} <
15ef0 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S60400>.**.** Th
15f00 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 is routine confi
15f10 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b gures a callback
15f20 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a function - the.
15f30 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c ** progress call
15f40 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69 back - that is i
15f50 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 nvoked periodica
15f60 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a lly during long.
15f70 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 ** running calls
15f80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 to [sqlite3_exe
15f90 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 c()], [sqlite3_s
15fa0 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 tep()] and.** [s
15fb0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
15fc0 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 ()]. An example
15fd0 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a use for this.**
15fe0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f interface is to
15ff0 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 keep a GUI upda
16000 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 ted during a lar
16010 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 ge query..**.**
16020 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 If the progress
16030 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
16040 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f non-zero, the o
16050 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 peration is.** i
16060 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 nterrupted. Thi
16070 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 s feature can be
16080 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 used to impleme
16090 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 nt a.** "Cancel"
160a0 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 button on a GUI
160b0 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 progress dialog
160c0 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 box..**.** The
160d0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 progress handler
160e0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 must not do any
160f0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 thing that will
16100 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 modify.** the da
16110 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
16120 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 n that invoked t
16130 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
16140 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ler..** Note tha
16150 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 t [sqlite3_prepa
16160 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
16170 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f lite3_step()] bo
16180 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a th modify their.
16190 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
161a0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 ections for the
161b0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 meaning of "modi
161c0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 fy" in this para
161d0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 graph..**.** Req
161e0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
161f0 31 32 39 31 31 5d 20 5b 48 31 32 39 31 32 5d 20 12911] [H12912]
16200 5b 48 31 32 39 31 33 5d 20 5b 48 31 32 39 31 34 [H12913] [H12914
16210 5d 20 5b 48 31 32 39 31 35 5d 20 5b 48 31 32 39 ] [H12915] [H129
16220 31 36 5d 20 5b 48 31 32 39 31 37 5d 20 5b 48 31 16] [H12917] [H1
16230 32 39 31 38 5d 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 2918].**.*/.void
16240 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 sqlite3_progres
16250 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 s_handler(sqlite
16260 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 3*, int, int(*)(
16270 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a void*), void*);.
16280 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
16290 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 Opening A New D
162a0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
162b0 6f 6e 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 on {H12700} <S40
162c0 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 200>.**.** These
162d0 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 routines open a
162e0 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 n SQLite databas
162f0 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d e file whose nam
16300 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 e is given by th
16310 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 e.** filename ar
16320 67 75 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 gument. The file
16330 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 name argument is
16340 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
16350 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c UTF-8 for.** sql
16360 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 ite3_open() and
16370 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
16380 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 ) and as UTF-16
16390 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
163a0 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 te.** order for
163b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
163c0 2e 20 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f . A [database co
163d0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 nnection] handle
163e0 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 is usually.** r
163f0 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 eturned in *ppDb
16400 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 , even if an err
16410 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 or occurs. The
16420 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 only exception i
16430 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c s that.** if SQL
16440 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f ite is unable to
16450 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 allocate memory
16460 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 to hold the [sq
16470 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a lite3] object,.*
16480 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 * a NULL will be
16490 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 written into *p
164a0 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 pDb instead of a
164b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
164c0 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a [sqlite3].** obj
164d0 65 63 74 2e 20 49 66 20 74 68 65 20 64 61 74 61 ect. If the data
164e0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 base is opened (
164f0 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 and/or created)
16500 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 successfully, th
16510 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b en.** [SQLITE_OK
16520 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 ] is returned.
16530 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 Otherwise an [er
16540 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 ror code] is ret
16550 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b urned. The.** [
16560 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
16570 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 ] or [sqlite3_er
16580 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e rmsg16()] routin
16590 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 es can be used t
165a0 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 o obtain.** an E
165b0 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 nglish language
165c0 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 description of t
165d0 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 he error..**.**
165e0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f The default enco
165f0 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 ding for the dat
16600 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 abase will be UT
16610 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 F-8 if.** sqlite
16620 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 3_open() or sqli
16630 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
16640 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 called and.** U
16650 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 TF-16 in the nat
16660 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 ive byte order i
16670 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 f sqlite3_open16
16680 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a () is used..**.*
16690 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 * Whether or not
166a0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
166b0 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e when it is open
166c0 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a ed, resources.**
166d0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
166e0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
166f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c onnection] handl
16700 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 e should be rele
16710 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 ased by.** passi
16720 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 ng it to [sqlite
16730 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 3_close()] when
16740 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 it is no longer
16750 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
16760 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e The sqlite3_open
16770 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 _v2() interface
16780 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 works like sqlit
16790 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 e3_open().** exc
167a0 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 ept that it acce
167b0 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e pts two addition
167c0 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f al parameters fo
167d0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e r additional con
167e0 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 trol.** over the
167f0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f new database co
16800 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 nnection. The f
16810 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 lags parameter c
16820 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a an take one of.*
16830 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 * the following
16840 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 three values, op
16850 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 tionally combine
16860 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b d with the .** [
16870 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
16880 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f TEX] or [SQLITE_
16890 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 OPEN_FULLMUTEX]
168a0 66 6c 61 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c flags:.**.** <dl
168b0 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 >.** <dt>[SQLITE
168c0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c _OPEN_READONLY]<
168d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
168e0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
168f0 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 ed in read-only
16900 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 mode. If the da
16910 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a tabase does not.
16920 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 ** already exist
16930 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 , an error is re
16940 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a turned.</dd>.**.
16950 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f ** <dt>[SQLITE_O
16960 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f PEN_READWRITE]</
16970 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 dt>.** <dd>The d
16980 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
16990 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e d for reading an
169a0 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 d writing if pos
169b0 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e sible, or readin
169c0 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 g.** only if the
169d0 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 file is write p
169e0 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 rotected by the
169f0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
16a00 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 . In either.**
16a10 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 case the databas
16a20 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 e must already e
16a30 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 xist, otherwise
16a40 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 an error is retu
16a50 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a rned.</dd>.**.**
16a60 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 <dt>[SQLITE_OPE
16a70 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b N_READWRITE] | [
16a80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
16a90 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TE]</dt>.** <dd>
16aa0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 The database is
16ab0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 opened for readi
16ac0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 ng and writing,
16ad0 61 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69 and is creates i
16ae0 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 t if.** it does
16af0 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 not already exis
16b00 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 t. This is the b
16b10 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 ehavior that is
16b20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a always used for.
16b30 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ** sqlite3_open(
16b40 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 ) and sqlite3_op
16b50 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 en16().</dd>.**
16b60 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 </dl>.**.** If t
16b70 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 he 3rd parameter
16b80 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
16b90 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 _v2() is not one
16ba0 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 of the.** combi
16bb0 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 nations shown ab
16bc0 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 ove or one of th
16bd0 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 e combinations s
16be0 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 hown above combi
16bf0 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ned.** with the
16c00 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d [SQLITE_OPEN_NOM
16c10 55 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 UTEX] or [SQLITE
16c20 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d _OPEN_FULLMUTEX]
16c30 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 flags,.** then
16c40 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
16c50 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
16c60 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f If the [SQLITE_
16c70 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c OPEN_NOMUTEX] fl
16c80 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 ag is set, then
16c90 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
16ca0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 nection.** opens
16cb0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 in the multi-th
16cc0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 read [threading
16cd0 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 mode] as long as
16ce0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 the single-thre
16cf0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e ad.** mode has n
16d00 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 ot been set at c
16d10 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 ompile-time or s
16d20 74 61 72 74 2d 74 69 6d 65 2e 20 20 49 66 20 74 tart-time. If t
16d30 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 he.** [SQLITE_OP
16d40 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c EN_FULLMUTEX] fl
16d50 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 ag is set then t
16d60 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
16d70 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 ection opens.**
16d80 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 in the serialize
16d90 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 d [threading mod
16da0 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 e] unless single
16db0 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 -thread was.** p
16dc0 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 reviously select
16dd0 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 ed at compile-ti
16de0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 me or start-time
16df0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 ..**.** If the f
16e00 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d ilename is ":mem
16e10 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 ory:", then a pr
16e20 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 ivate, temporary
16e30 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 in-memory datab
16e40 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 ase.** is create
16e50 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 d for the connec
16e60 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d tion. This in-m
16e70 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 emory database w
16e80 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a ill vanish when.
16e90 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
16ea0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c connection is cl
16eb0 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 osed. Future ve
16ec0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
16ed0 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 might.** make u
16ee0 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c se of additional
16ef0 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d special filenam
16f00 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 es that begin wi
16f10 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 th the ":" chara
16f20 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 cter..** It is r
16f30 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
16f40 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 when a database
16f50 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c filename actuall
16f60 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 y does begin wit
16f70 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 h.** a ":" chara
16f80 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 cter you should
16f90 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e prefix the filen
16fa0 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e ame with a pathn
16fb0 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 ame such as.** "
16fc0 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 ./" to avoid amb
16fd0 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 iguity..**.** If
16fe0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 the filename is
16ff0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
17000 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 , then a private
17010 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f , temporary.** o
17020 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 n-disk database
17030 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e will be created.
17040 20 20 54 68 69 73 20 70 72 69 76 61 74 65 20 64 This private d
17050 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a atabase will be.
17060 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ** automatically
17070 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e deleted as soon
17080 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 as the database
17090 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 connection is c
170a0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 losed..**.** The
170b0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
170c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 r to sqlite3_ope
170d0 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 n_v2() is the na
170e0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 me of the.** [sq
170f0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
17100 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 t that defines t
17110 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
17120 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 tem interface th
17130 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 at.** the new da
17140 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
17150 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 n should use. I
17160 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
17170 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e ameter is.** a N
17180 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
17190 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 the default [sq
171a0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
171b0 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a t is used..**.**
171c0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 <b>Note to Wind
171d0 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 ows users:</b>
171e0 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 The encoding use
171f0 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 d for the filena
17200 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f me argument.** o
17210 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 f sqlite3_open()
17220 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 and sqlite3_ope
17230 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 n_v2() must be U
17240 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 TF-8, not whatev
17250 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 er.** codepage i
17260 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 s currently defi
17270 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 ned. Filenames
17280 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 containing inter
17290 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 national.** char
172a0 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 acters must be c
172b0 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d onverted to UTF-
172c0 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 8 prior to passi
172d0 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 ng them into.**
172e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f sqlite3_open() o
172f0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
17300 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 2()..**.** Requi
17310 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 rements:.** [H12
17320 37 30 31 5d 20 5b 48 31 32 37 30 32 5d 20 5b 48 701] [H12702] [H
17330 31 32 37 30 33 5d 20 5b 48 31 32 37 30 34 5d 20 12703] [H12704]
17340 5b 48 31 32 37 30 36 5d 20 5b 48 31 32 37 30 37 [H12706] [H12707
17350 5d 20 5b 48 31 32 37 30 39 5d 20 5b 48 31 32 37 ] [H12709] [H127
17360 31 31 5d 0a 2a 2a 20 5b 48 31 32 37 31 32 5d 20 11].** [H12712]
17370 5b 48 31 32 37 31 33 5d 20 5b 48 31 32 37 31 34 [H12713] [H12714
17380 5d 20 5b 48 31 32 37 31 37 5d 20 5b 48 31 32 37 ] [H12717] [H127
17390 31 39 5d 20 5b 48 31 32 37 32 31 5d 20 5b 48 31 19] [H12721] [H1
173a0 32 37 32 33 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 2723].*/.int sql
173b0 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e ite3_open(. con
173c0 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d st char *filenam
173d0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 e, /* Database
173e0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 filename (UTF-8
173f0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a ) */. sqlite3 *
17400 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f *ppDb /
17410 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 * OUT: SQLite db
17420 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e handle */.);.in
17430 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 t sqlite3_open16
17440 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a (. const void *
17450 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 filename, /* D
17460 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 atabase filename
17470 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 (UTF-16) */. s
17480 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 qlite3 **ppDb
17490 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 /* OUT: S
174a0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 QLite db handle
174b0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 */.);.int sqlite
174c0 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 3_open_v2(. con
174d0 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d st char *filenam
174e0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 e, /* Database
174f0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 filename (UTF-8
17500 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a ) */. sqlite3 *
17510 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f *ppDb, /
17520 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 * OUT: SQLite db
17530 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 handle */. int
17540 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 flags,
17550 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f /* Flags */
17560 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
17570 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 Vfs /* Na
17580 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 me of VFS module
17590 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f to use */.);../
175a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 *.** CAPI3REF: E
175b0 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d rror Codes And M
175c0 65 73 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d essages {H12800}
175d0 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S60200>.**.**
175e0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 The sqlite3_errc
175f0 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ode() interface
17600 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 returns the nume
17610 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 ric [result code
17620 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 ] or.** [extende
17630 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 d result code] f
17640 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 or the most rece
17650 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 nt failed sqlite
17660 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 3_* API call.**
17670 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
17680 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
17690 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 ection]. If a pr
176a0 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 ior API call fai
176b0 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d led.** but the m
176c0 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 ost recent API c
176d0 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 all succeeded, t
176e0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
176f0 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f from.** sqlite3_
17700 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 errcode() is und
17710 65 66 69 6e 65 64 2e 20 20 54 68 65 20 73 71 6c efined. The sql
17720 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 ite3_extended_er
17730 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 rcode().** inter
17740 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 face is the same
17750 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 except that it
17760 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 always returns t
17770 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 he .** [extended
17780 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 result code] ev
17790 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 en when extended
177a0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 result codes ar
177b0 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a e.** disabled..*
177c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
177d0 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 _errmsg() and sq
177e0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 lite3_errmsg16()
177f0 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d return English-
17800 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 language.** text
17810 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 that describes
17820 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 the error, as ei
17830 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 ther UTF-8 or UT
17840 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c F-16 respectivel
17850 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 y..** Memory to
17860 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d hold the error m
17870 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 essage string is
17880 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 managed interna
17890 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c lly..** The appl
178a0 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 ication does not
178b0 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 need to worry a
178c0 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 bout freeing the
178d0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 result..** Howe
178e0 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 ver, the error s
178f0 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f tring might be o
17900 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 verwritten or de
17910 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 allocated by.**
17920 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 subsequent calls
17930 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 to other SQLite
17940 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 interface funct
17950 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e ions..**.** When
17960 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 the serialized
17970 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
17980 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d is in use, it m
17990 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 ight be the.** c
179a0 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e ase that a secon
179b0 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f d error occurs o
179c0 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 n a separate thr
179d0 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a ead in between.*
179e0 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 * the time of th
179f0 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e e first error an
17a00 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 d the call to th
17a10 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a ese interfaces..
17a20 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 ** When that hap
17a30 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 pens, the second
17a40 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 error will be r
17a50 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 eported since th
17a60 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ese.** interface
17a70 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 s always report
17a80 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
17a90 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 result. To avoi
17aa0 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 d.** this, each
17ab0 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 thread can obtai
17ac0 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 n exclusive use
17ad0 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 of the [database
17ae0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a connection] D.*
17af0 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 * by invoking [s
17b00 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 qlite3_mutex_ent
17b10 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f er]([sqlite3_db_
17b20 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 mutex](D)) befor
17b30 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 e beginning.** t
17b40 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f o use D and invo
17b50 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 king [sqlite3_mu
17b60 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 tex_leave]([sqli
17b70 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 te3_db_mutex](D)
17b80 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 ) after.** all c
17b90 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 alls to the inte
17ba0 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 rfaces listed he
17bb0 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 re are completed
17bc0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e ..**.** If an in
17bd0 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 terface fails wi
17be0 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 th SQLITE_MISUSE
17bf0 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 , that means the
17c00 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 interface.** wa
17c10 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 s invoked incorr
17c20 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 ectly by the app
17c30 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 lication. In th
17c40 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 at case, the.**
17c50 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d error code and m
17c60 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 essage may or ma
17c70 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a y not be set..**
17c80 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
17c90 3a 0a 2a 2a 20 5b 48 31 32 38 30 31 5d 20 5b 48 :.** [H12801] [H
17ca0 31 32 38 30 32 5d 20 5b 48 31 32 38 30 33 5d 20 12802] [H12803]
17cb0 5b 48 31 32 38 30 37 5d 20 5b 48 31 32 38 30 38 [H12807] [H12808
17cc0 5d 20 5b 48 31 32 38 30 39 5d 0a 2a 2f 0a 69 6e ] [H12809].*/.in
17cd0 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 t sqlite3_errcod
17ce0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a e(sqlite3 *db);.
17cf0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 int sqlite3_exte
17d00 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c nded_errcode(sql
17d10 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 ite3 *db);.const
17d20 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 char *sqlite3_e
17d30 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b rrmsg(sqlite3*);
17d40 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
17d50 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 ite3_errmsg16(sq
17d60 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
17d70 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 CAPI3REF: SQL St
17d80 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b atement Object {
17d90 48 31 33 30 30 30 7d 20 3c 48 31 33 30 31 30 3e H13000} <H13010>
17da0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 .** KEYWORDS: {p
17db0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
17dc0 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 t} {prepared sta
17dd0 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 tements}.**.** A
17de0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
17df0 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 is object repres
17e00 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 ents a single SQ
17e10 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 L statement..**
17e20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 This object is v
17e30 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 ariously known a
17e40 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 s a "prepared st
17e50 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a atement" or a.**
17e60 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 "compiled SQL s
17e70 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d tatement" or sim
17e80 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d ply as a "statem
17e90 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ent"..**.** The
17ea0 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d life of a statem
17eb0 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 ent object goes
17ec0 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 something like t
17ed0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a his:.**.** <ol>.
17ee0 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 ** <li> Create t
17ef0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 he object using
17f00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
17f10 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 _v2()] or a rela
17f20 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 ted.** func
17f30 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 tion..** <li> Bi
17f40 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f nd values to [ho
17f50 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 st parameters] u
17f60 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 sing the sqlite3
17f70 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 _bind_*().**
17f80 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a interfaces..**
17f90 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 <li> Run the SQ
17fa0 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 L by calling [sq
17fb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e lite3_step()] on
17fc0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e e or more times.
17fd0 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 .** <li> Reset t
17fe0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 he statement usi
17ff0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
18000 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 t()] then go bac
18010 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 k.** to ste
18020 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 p 2. Do this ze
18030 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ro or more times
18040 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f ..** <li> Destro
18050 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 y the object usi
18060 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
18070 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c lize()]..** </ol
18080 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f >.**.** Refer to
18090 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f documentation o
180a0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 n individual met
180b0 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 hods above for a
180c0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
180d0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 ormation..*/.typ
180e0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
180f0 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 te3_stmt sqlite3
18100 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 _stmt;../*.** CA
18110 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 PI3REF: Run-time
18120 20 4c 69 6d 69 74 73 20 7b 48 31 32 37 36 30 7d Limits {H12760}
18130 20 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20600>.**.**
18140 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 This interface a
18150 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f llows the size o
18160 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 f various constr
18170 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 ucts to be limit
18180 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 ed.** on a conne
18190 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 ction by connect
181a0 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 ion basis. The
181b0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
181c0 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 is the.** [datab
181d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
181e0 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 whose limit is t
181f0 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 o be set or quer
18200 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 ied. The.** sec
18210 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
18220 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d one of the [lim
18230 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 it categories] t
18240 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 hat define a.**
18250 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 class of constru
18260 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c cts to be size l
18270 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 imited. The thi
18280 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 rd parameter is
18290 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 the.** new limit
182a0 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 for that constr
182b0 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 uct. The functi
182c0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f on returns the o
182d0 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 ld limit..**.**
182e0 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 If the new limit
182f0 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e is a negative n
18300 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 umber, the limit
18310 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a is unchanged..*
18320 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 * For the limit
18330 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 category of SQLI
18340 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 TE_LIMIT_XYZ the
18350 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d re is a .** [lim
18360 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 its | hard upper
18370 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62 bound].** set b
18380 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 y a compile-time
18390 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C preprocessor
183a0 6d 61 63 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20 macro named .**
183b0 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 [limits | SQLITE
183c0 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54 _MAX_XYZ]..** (T
183d0 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 he "_LIMIT_" in
183e0 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e the name is chan
183f0 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 ged to "_MAX_".)
18400 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20 .** Attempts to
18410 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 increase a limit
18420 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 above its hard
18430 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a upper bound are.
18440 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e ** silently trun
18450 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 cated to the har
18460 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a d upper limit..*
18470 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 *.** Run time li
18480 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 mits are intende
18490 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 d for use in app
184a0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d lications that m
184b0 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 anage.** both th
184c0 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c eir own internal
184d0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c database and al
184e0 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 so databases tha
184f0 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 t are controlled
18500 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 .** by untrusted
18510 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 external source
18520 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 s. An example a
18530 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 pplication might
18540 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f be a.** web bro
18550 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 wser that has it
18560 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 s own databases
18570 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 for storing hist
18580 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 ory and.** separ
18590 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f ate databases co
185a0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 ntrolled by Java
185b0 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 Script applicati
185c0 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a ons downloaded.*
185d0 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e * off the Intern
185e0 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 et. The interna
185f0 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 l databases can
18600 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 be given the.**
18610 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c large, default l
18620 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 imits. Database
18630 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 s managed by ext
18640 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 ernal sources ca
18650 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 n.** be given mu
18660 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 ch smaller limit
18670 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 s designed to pr
18680 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f event a denial o
18690 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 f service.** att
186a0 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 ack. Developers
186b0 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 might also want
186c0 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c to use the [sql
186d0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
186e0 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 zer()].** interf
186f0 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 ace to further c
18700 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 ontrol untrusted
18710 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 SQL. The size
18720 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a of the database.
18730 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e ** created by an
18740 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 untrusted scrip
18750 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e t can be contain
18760 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 ed using the.**
18770 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d [max_page_count]
18780 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a [PRAGMA]..**.**
18790 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 New run-time li
187a0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d mit categories m
187b0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
187c0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a uture releases..
187d0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
187e0 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 36 32 5d 20 ts:.** [H12762]
187f0 5b 48 31 32 37 36 36 5d 20 5b 48 31 32 37 36 39 [H12766] [H12769
18800 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ].*/.int sqlite3
18810 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c _limit(sqlite3*,
18820 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 int id, int new
18830 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 Val);../*.** CAP
18840 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 I3REF: Run-Time
18850 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 Limit Categories
18860 20 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36 {H12790} <H1276
18870 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 0>.** KEYWORDS:
18880 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d {limit category}
18890 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 {limit categori
188a0 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 es}.**.** These
188b0 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 constants define
188c0 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d various perform
188d0 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 ance limits.** t
188e0 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 hat can be lower
188f0 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 ed at run-time u
18900 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 sing [sqlite3_li
18910 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 mit()]..** The s
18920 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d ynopsis of the m
18930 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 eanings of the v
18940 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 arious limits is
18950 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a shown below..**
18960 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f Additional info
18970 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c rmation is avail
18980 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 able at [limits
18990 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 | Limits in SQLi
189a0 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a te]..**.** <dl>.
189b0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ** <dt>SQLITE_LI
189c0 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a MIT_LENGTH</dt>.
189d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
189e0 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 um size of any s
189f0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 tring or BLOB or
18a00 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a table row.<dd>.
18a10 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
18a20 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 _LIMIT_SQL_LENGT
18a30 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
18a40 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 e maximum length
18a50 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 of an SQL state
18a60 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ment.</dd>.**.**
18a70 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 <dt>SQLITE_LIMI
18a80 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a T_COLUMN</dt>.**
18a90 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
18aa0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
18ab0 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 ns in a table de
18ac0 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 finition or in t
18ad0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 he.** result set
18ae0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f of a [SELECT] o
18af0 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 r the maximum nu
18b00 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
18b10 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f in an index.** o
18b20 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 r in an ORDER BY
18b30 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 or GROUP BY cla
18b40 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 use.</dd>.**.**
18b50 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
18b60 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e _EXPR_DEPTH</dt>
18b70 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
18b80 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 mum depth of the
18b90 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 parse tree on a
18ba0 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f ny expression.</
18bb0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
18bc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f LITE_LIMIT_COMPO
18bd0 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a UND_SELECT</dt>.
18be0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
18bf0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 um number of ter
18c00 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 ms in a compound
18c10 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e SELECT statemen
18c20 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 t.</dd>.**.** <d
18c30 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 t>SQLITE_LIMIT_V
18c40 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c DBE_OP</dt>.** <
18c50 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
18c60 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 umber of instruc
18c70 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 tions in a virtu
18c80 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 al machine progr
18c90 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d am.** used to im
18ca0 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 plement an SQL s
18cb0 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a tatement.</dd>.*
18cc0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
18cd0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 LIMIT_FUNCTION_A
18ce0 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 RG</dt>.** <dd>T
18cf0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
18d00 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f r of arguments o
18d10 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 n a function.</d
18d20 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
18d30 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 ITE_LIMIT_ATTACH
18d40 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ED</dt>.** <dd>T
18d50 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
18d60 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 r of [ATTACH | a
18d70 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
18d80 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c s].</dd>.**.** <
18d90 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
18da0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e LIKE_PATTERN_LEN
18db0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e GTH</dt>.** <dd>
18dc0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 The maximum leng
18dd0 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 th of the patter
18de0 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 n argument to th
18df0 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b e [LIKE] or.** [
18e00 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e GLOB] operators.
18e10 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
18e20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 SQLITE_LIMIT_VAR
18e30 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 IABLE_NUMBER</dt
18e40 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
18e50 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 imum number of v
18e60 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 ariables in an S
18e70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 QL statement tha
18e80 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e t can.** be boun
18e90 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e d.</dd>.** </dl>
18ea0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
18eb0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 TE_LIMIT_LENGTH
18ec0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
18ed0 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0.#define SQL
18ee0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 ITE_LIMIT_SQL_LE
18ef0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 NGTH
18f00 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
18f10 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d LITE_LIMIT_COLUM
18f20 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 N
18f30 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
18f40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 QLITE_LIMIT_EXPR
18f50 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 _DEPTH
18f60 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 3.#define
18f70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d SQLITE_LIMIT_COM
18f80 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 POUND_SELECT
18f90 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 4.#define
18fa0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 SQLITE_LIMIT_VD
18fb0 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 BE_OP
18fc0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 5.#defin
18fd0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 e SQLITE_LIMIT_F
18fe0 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 UNCTION_ARG
18ff0 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6.#defi
19000 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
19010 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 ATTACHED
19020 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 7.#def
19030 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
19040 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 _LIKE_PATTERN_LE
19050 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 NGTH 8.#de
19060 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
19070 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 T_VARIABLE_NUMBE
19080 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f R 9../
19090 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
190a0 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 ompiling An SQL
190b0 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 Statement {H1301
190c0 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 0} <S10000>.** K
190d0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 EYWORDS: {SQL st
190e0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 atement compiler
190f0 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 }.**.** To execu
19100 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c te an SQL query,
19110 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 it must first b
19120 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 e compiled into
19130 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 a byte-code.** p
19140 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 rogram using one
19150 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
19160 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 es..**.** The fi
19170 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 rst argument, "d
19180 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 b", is a [databa
19190 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f se connection] o
191a0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a btained from a.*
191b0 2a 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 * prior call to
191c0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
191d0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f , [sqlite3_open_
191e0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 v2()] or [sqlite
191f0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 3_open16()]..**.
19200 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 ** The second ar
19210 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 gument, "zSql",
19220 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 is the statement
19230 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c to be compiled,
19240 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 encoded.** as e
19250 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 ither UTF-8 or U
19260 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 TF-16. The sqli
19270 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e te3_prepare() an
19280 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
19290 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 e_v2().** interf
192a0 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 aces use UTF-8,
192b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 and sqlite3_prep
192c0 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 are16() and sqli
192d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
192e0 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 ().** use UTF-16
192f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e ..**.** If the n
19300 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 Byte argument is
19310 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c less than zero,
19320 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 then zSql is re
19330 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 ad up to the.**
19340 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 first zero termi
19350 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 20 nator. If nByte
19360 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c is non-negative,
19370 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 then it is the
19380 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 maximum.** numbe
19390 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 r of bytes read
193a0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 from zSql. Whe
193b0 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e n nByte is non-n
193c0 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 egative, the.**
193d0 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 zSql string ends
193e0 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66 at either the f
193f0 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 irst '\000' or '
19400 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65 \u0000' characte
19410 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 r or.** the nByt
19420 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 e-th byte, which
19430 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 ever comes first
19440 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 . If the caller
19450 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 knows.** that th
19460 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e e supplied strin
19470 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 g is nul-termina
19480 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 ted, then there
19490 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 is a small.** pe
194a0 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 rformance advant
194b0 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 age to be gained
194c0 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e by passing an n
194d0 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 Byte parameter t
194e0 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 hat.** is equal
194f0 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 to the number of
19500 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e bytes in the in
19510 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e put string <i>in
19520 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 cluding</i>.** t
19530 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f he nul-terminato
19540 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a r bytes..**.** *
19550 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 pzTail is made t
19560 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 o point to the f
19570 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20 74 irst byte past t
19580 68 65 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a he end of the.**
19590 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 first SQL state
195a0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 ment in zSql. T
195b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e hese routines on
195c0 6c 79 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 ly compile the f
195d0 69 72 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e irst.** statemen
195e0 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 t in zSql, so *p
195f0 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f zTail is left po
19600 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72 inting to what r
19610 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 emains.** uncomp
19620 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 iled..**.** *ppS
19630 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e tmt is left poin
19640 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c ting to a compil
19650 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ed [prepared sta
19660 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e tement] that can
19670 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 be.** executed
19680 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 using [sqlite3_s
19690 74 65 70 28 29 5d 2e 20 20 49 66 20 74 68 65 72 tep()]. If ther
196a0 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a e is an error, *
196b0 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a ppStmt is set.**
196c0 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 to NULL. If th
196d0 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e e input text con
196e0 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 tains no SQL (if
196f0 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e the input is an
19700 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 empty.** string
19710 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 or a comment) t
19720 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 hen *ppStmt is s
19730 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b et to NULL..** {
19740 41 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c A13018} The call
19750 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 ing procedure is
19760 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
19770 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f deleting the co
19780 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 mpiled.** SQL st
19790 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 atement using [s
197a0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
197b0 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 )] after it has
197c0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 finished with it
197d0 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 ..**.** On succe
197e0 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 ss, [SQLITE_OK]
197f0 69 73 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 is returned, oth
19800 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 erwise an [error
19810 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
19820 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
19830 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
19840 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 () and sqlite3_p
19850 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e repare16_v2() in
19860 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 terfaces are.**
19870 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
19880 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 all new programs
19890 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 . The two older
198a0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 interfaces are r
198b0 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 etained.** for b
198c0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
198d0 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 bility, but thei
198e0 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 r use is discour
198f0 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 aged..** In the
19900 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c "v2" interfaces,
19910 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
19920 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 atement.** that
19930 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 is returned (the
19940 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 [sqlite3_stmt]
19950 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 object) contains
19960 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a a copy of the.*
19970 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 * original SQL t
19980 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 ext. This causes
19990 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 the [sqlite3_st
199a0 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 ep()] interface
199b0 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 to.** behave a d
199c0 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 ifferently in tw
199d0 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f o ways:.**.** <o
199e0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 l>.** <li>.** If
199f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 the database sc
19a00 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e hema changes, in
19a10 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 stead of returni
19a20 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d ng [SQLITE_SCHEM
19a30 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 A] as it.** alwa
19a40 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b ys used to do, [
19a50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
19a60 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c will automatical
19a70 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 ly recompile the
19a80 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e SQL.** statemen
19a90 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e t and try to run
19aa0 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 it again. If t
19ab0 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 he schema has ch
19ac0 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 anged in.** a wa
19ad0 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 y that makes the
19ae0 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f statement no lo
19af0 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c nger valid, [sql
19b00 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c ite3_step()] wil
19b10 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 l still.** retur
19b20 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 n [SQLITE_SCHEMA
19b30 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 ]. But unlike t
19b40 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 he legacy behavi
19b50 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 or, [SQLITE_SCHE
19b60 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 MA] is.** now a
19b70 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 fatal error. Ca
19b80 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 lling [sqlite3_p
19b90 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 repare_v2()] aga
19ba0 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 in will not make
19bb0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f the.** error go
19bc0 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 away. Note: us
19bd0 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 e [sqlite3_errms
19be0 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 g()] to find the
19bf0 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 text.** of the
19c00 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 parsing error th
19c10 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e at results in an
19c20 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
19c30 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 return..** </li
19c40 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 >.**.** <li>.**
19c50 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 When an error oc
19c60 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 curs, [sqlite3_s
19c70 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 tep()] will retu
19c80 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 rn one of the de
19c90 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 tailed.** [error
19ca0 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 codes] or [exte
19cb0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 nded error codes
19cc0 5d 2e 20 20 54 68 65 20 6c 65 67 61 63 79 20 62 ]. The legacy b
19cd0 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 ehavior was that
19ce0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
19cf0 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 p()] would only
19d00 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 return a generic
19d10 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
19d20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 result code.** a
19d30 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 nd you would hav
19d40 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f e to make a seco
19d50 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nd call to [sqli
19d60 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 te3_reset()] in
19d70 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 order.** to find
19d80 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 the underlying
19d90 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f cause of the pro
19da0 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 blem. With the "
19db0 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 v2" prepare.** i
19dc0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 nterfaces, the u
19dd0 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e nderlying reason
19de0 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 for the error i
19df0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 s returned immed
19e00 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e iately..** </li>
19e10 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ol>.**.**
19e20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
19e30 20 5b 48 31 33 30 31 31 5d 20 5b 48 31 33 30 31 [H13011] [H1301
19e40 32 5d 20 5b 48 31 33 30 31 33 5d 20 5b 48 31 33 2] [H13013] [H13
19e50 30 31 34 5d 20 5b 48 31 33 30 31 35 5d 20 5b 48 014] [H13015] [H
19e60 31 33 30 31 36 5d 20 5b 48 31 33 30 31 39 5d 20 13016] [H13019]
19e70 5b 48 31 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a 69 [H13021].**.*/.i
19e80 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nt sqlite3_prepa
19e90 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 re(. sqlite3 *d
19ea0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
19eb0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
19ec0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
19ed0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
19ee0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
19ef0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f UTF-8 encoded */
19f00 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
19f10 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
19f20 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
19f30 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
19f40 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
19f50 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
19f60 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
19f70 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
19f80 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 char **pzTail
19f90 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
19fa0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
19fb0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
19fc0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 ;.int sqlite3_pr
19fd0 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 epare_v2(. sqli
19fe0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
19ff0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
1a000 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
1a010 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 t char *zSql,
1a020 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
1a030 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f ment, UTF-8 enco
1a040 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
1a050 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
1a060 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
1a070 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
1a080 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
1a090 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
1a0a0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
1a0b0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
1a0c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 const char **pzT
1a0d0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
1a0e0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
1a0f0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
1a100 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 l */.);.int sqli
1a110 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 te3_prepare16(.
1a120 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
1a130 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
1a140 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
1a150 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 const void *zSq
1a160 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
1a170 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 statement, UTF-1
1a180 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6 encoded */. i
1a190 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
1a1a0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
1a1b0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
1a1c0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
1a1d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
1a1e0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
1a1f0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
1a200 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
1a210 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
1a220 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
1a230 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
1a240 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e of zSql */.);.in
1a250 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
1a260 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 e16_v2(. sqlite
1a270 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
1a280 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
1a290 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
1a2a0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 void *zSql,
1a2b0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
1a2c0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 nt, UTF-16 encod
1a2d0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
1a2e0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
1a2f0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 /* Maximum lengt
1a300 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
1a310 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 es. */. sqlite3
1a320 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
1a330 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
1a340 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
1a350 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 onst void **pzTa
1a360 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
1a370 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
1a380 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
1a390 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
1a3a0 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 PI3REF: Retrievi
1a3b0 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c ng Statement SQL
1a3c0 20 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30 {H13100} <H1300
1a3d0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 0>.**.** This in
1a3e0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
1a3f0 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 sed to retrieve
1a400 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 a saved copy of
1a410 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 the original.**
1a420 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f SQL text used to
1a430 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 create a [prepa
1a440 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 red statement] i
1a450 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 f that statement
1a460 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 was.** compiled
1a470 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 using either [s
1a480 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1a490 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
1a4a0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
1a4b0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
1a4c0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 31 30 31 ents:.** [H13101
1a4d0 5d 20 5b 48 31 33 31 30 32 5d 20 5b 48 31 33 31 ] [H13102] [H131
1a4e0 30 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 03].*/.const cha
1a4f0 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 r *sqlite3_sql(s
1a500 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
1a510 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
1a520 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 3REF: Dynamicall
1a530 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 y Typed Value Ob
1a540 6a 65 63 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 ject {H15000} <S
1a550 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 20200>.** KEYWOR
1a560 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 DS: {protected s
1a570 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 qlite3_value} {u
1a580 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
1a590 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 e3_value}.**.**
1a5a0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 SQLite uses the
1a5b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
1a5c0 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e ject to represen
1a5d0 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 t all values.**
1a5e0 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 that can be stor
1a5f0 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 ed in a database
1a600 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 table. SQLite u
1a610 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 ses dynamic typi
1a620 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 ng.** for the va
1a630 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 lues it stores.
1a640 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e Values stored in
1a650 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
1a660 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 bjects.** can be
1a670 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 integers, float
1a680 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 ing point values
1a690 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 , strings, BLOBs
1a6a0 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a , or NULL..**.**
1a6b0 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 An sqlite3_valu
1a6c0 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 e object may be
1a6d0 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 either "protecte
1a6e0 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 d" or "unprotect
1a6f0 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 ed"..** Some int
1a700 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 erfaces require
1a710 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 a protected sqli
1a720 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 te3_value. Othe
1a730 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 r interfaces.**
1a740 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 will accept eith
1a750 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f er a protected o
1a760 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 r an unprotected
1a770 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a sqlite3_value..
1a780 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 ** Every interfa
1a790 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 ce that accepts
1a7a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 sqlite3_value ar
1a7b0 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 guments specifie
1a7c0 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 s.** whether or
1a7d0 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 not it requires
1a7e0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 a protected sqli
1a7f0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a te3_value..**.**
1a800 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 The terms "prot
1a810 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 ected" and "unpr
1a820 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 otected" refer t
1a830 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 o whether or not
1a840 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 .** a mutex is h
1a850 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c eld. A internal
1a860 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 mutex is held f
1a870 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a or a protected.*
1a880 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
1a890 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 object but no mu
1a8a0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 tex is held for
1a8b0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a an unprotected.*
1a8c0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
1a8d0 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 object. If SQLi
1a8e0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 te is compiled t
1a8f0 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 o be single-thre
1a900 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 aded.** (with [S
1a910 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
1a920 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 =0] and with [sq
1a930 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 lite3_threadsafe
1a940 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 ()] returning 0)
1a950 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 .** or if SQLite
1a960 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f is run in one o
1a970 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 f reduced mutex
1a980 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 modes .** [SQLIT
1a990 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
1a9a0 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 HREAD] or [SQLIT
1a9b0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
1a9c0 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 READ].** then th
1a9d0 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e ere is no distin
1a9e0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 ction between pr
1a9f0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 otected and unpr
1aa00 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 otected.** sqlit
1aa10 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
1aa20 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 and they can be
1aa30 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 used interchang
1aa40 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c eably. However,
1aa50 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 .** for maximum
1aa60 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 code portability
1aa70 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 it is recommend
1aa80 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 ed that applicat
1aa90 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 ions.** still ma
1aaa0 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 ke the distincti
1aab0 6f 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 65 on between betwe
1aac0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 en protected and
1aad0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 unprotected.**
1aae0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
1aaf0 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 jects even when
1ab00 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 not strictly req
1ab10 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 uired..**.** The
1ab20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
1ab30 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 bjects that are
1ab40 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 passed as parame
1ab50 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a ters into the.**
1ab60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
1ab70 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d of [application-
1ab80 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
1ab90 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 tions] are prote
1aba0 63 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c cted..** The sql
1abb0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
1abc0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a t returned by.**
1abd0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
1abe0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 _value()] is unp
1abf0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 rotected..** Unp
1ac00 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
1ac10 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d _value objects m
1ac20 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 ay only be used
1ac30 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 with.** [sqlite3
1ac40 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d _result_value()]
1ac50 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 and [sqlite3_bi
1ac60 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 nd_value()]..**
1ac70 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c The [sqlite3_val
1ac80 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 ue_blob | sqlite
1ac90 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 3_value_type()]
1aca0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 family of.** int
1acb0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 erfaces require
1acc0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
1acd0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 3_value objects.
1ace0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
1acf0 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 ct Mem sqlite3_v
1ad00 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 alue;../*.** CAP
1ad10 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 I3REF: SQL Funct
1ad20 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 ion Context Obje
1ad30 63 74 20 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 ct {H16001} <S20
1ad40 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 200>.**.** The c
1ad50 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 ontext in which
1ad60 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 an SQL function
1ad70 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 executes is stor
1ad80 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 ed in an.** sqli
1ad90 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 te3_context obje
1ada0 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74 ct. A pointer t
1adb0 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e o an sqlite3_con
1adc0 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 text object.** i
1add0 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 s always first p
1ade0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 arameter to [app
1adf0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
1ae00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e SQL functions].
1ae10 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
1ae20 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
1ae30 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
1ae40 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 ntation will pas
1ae50 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 s this.** pointe
1ae60 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 r through into c
1ae70 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
1ae80 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 _result_int | sq
1ae90 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c lite3_result()],
1aea0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 .** [sqlite3_agg
1aeb0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
1aec0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 ], [sqlite3_user
1aed0 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _data()],.** [sq
1aee0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 lite3_context_db
1aef0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c _handle()], [sql
1af00 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
1af10 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b ()],.** and/or [
1af20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
1af30 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 ata()]..*/.typed
1af40 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
1af50 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 3_context sqlite
1af60 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 3_context;../*.*
1af70 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 * CAPI3REF: Bind
1af80 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 ing Values To Pr
1af90 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
1afa0 73 20 7b 48 31 33 35 30 30 7d 20 3c 53 37 30 33 s {H13500} <S703
1afb0 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 00>.** KEYWORDS:
1afc0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
1afd0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 } {host paramete
1afe0 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 rs} {host parame
1aff0 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 ter name}.** KEY
1b000 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 WORDS: {SQL para
1b010 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 meter} {SQL para
1b020 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 meters} {paramet
1b030 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a er binding}.**.*
1b040 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 * In the SQL str
1b050 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 ings input to [s
1b060 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1b070 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 2()] and its var
1b080 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 iants,.** litera
1b090 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 ls may be replac
1b0a0 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 ed by a [paramet
1b0b0 65 72 5d 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 er] in one of th
1b0c0 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a ese forms:.**.**
1b0d0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f <ul>.** <li> ?
1b0e0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a .** <li> ?NNN.*
1b0f0 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 * <li> :VVV.**
1b100 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c <li> @VVV.** <l
1b110 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c i> $VVV.** </ul
1b120 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 >.**.** In the p
1b130 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 arameter forms s
1b140 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 hown above NNN i
1b150 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 s an integer lit
1b160 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 eral,.** and VVV
1b170 20 69 73 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d is an alpha-num
1b180 65 72 69 63 20 70 61 72 61 6d 65 74 65 72 20 6e eric parameter n
1b190 61 6d 65 2e 20 54 68 65 20 76 61 6c 75 65 73 20 ame. The values
1b1a0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 of these.** para
1b1b0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c meters (also cal
1b1c0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 led "host parame
1b1d0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 ter names" or "S
1b1e0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a QL parameters").
1b1f0 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 ** can be set us
1b200 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
1b210 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
1b220 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a s defined here..
1b230 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
1b240 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
1b250 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
1b260 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 routines is alw
1b270 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 ays.** a pointer
1b280 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
1b290 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 _stmt] object re
1b2a0 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b turned from.** [
1b2b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1b2c0 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 v2()] or its var
1b2d0 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 iants..**.** The
1b2e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
1b2f0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 is the index of
1b300 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 the SQL paramet
1b310 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a er to be set..**
1b320 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 The leftmost SQ
1b330 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 L parameter has
1b340 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 an index of 1.
1b350 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 When the same na
1b360 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d med.** SQL param
1b370 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 eter is used mor
1b380 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 e than once, sec
1b390 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 ond and subseque
1b3a0 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 nt.** occurrence
1b3b0 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 s have the same
1b3c0 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 index as the fir
1b3d0 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a st occurrence..*
1b3e0 2a 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 * The index for
1b3f0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 named parameters
1b400 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 can be looked u
1b410 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b p using the.** [
1b420 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
1b430 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 ameter_index()]
1b440 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 API if desired.
1b450 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f The index.** fo
1b460 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 r "?NNN" paramet
1b470 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 ers is the value
1b480 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 of NNN..** The
1b490 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 NNN value must b
1b4a0 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 e between 1 and
1b4b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d the [sqlite3_lim
1b4c0 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 it()].** paramet
1b4d0 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 er [SQLITE_LIMIT
1b4e0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
1b4f0 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 ] (default value
1b500 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 : 999)..**.** Th
1b510 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
1b520 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f is the value to
1b530 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 bind to the par
1b540 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e ameter..**.** In
1b550 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 those routines
1b560 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 that have a four
1b570 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 th argument, its
1b580 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a value is the.**
1b590 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
1b5a0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 in the paramete
1b5b0 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a r. To be clear:
1b5c0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 the value is th
1b5d0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c e.** number of <
1b5e0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 u>bytes</u> in t
1b5f0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 he value, not th
1b600 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
1b610 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68 acters..** If th
1b620 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
1b630 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 er is negative,
1b640 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 the length of th
1b650 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 e string is.** t
1b660 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
1b670 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 es up to the fir
1b680 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 st zero terminat
1b690 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 or..**.** The fi
1b6a0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 fth argument to
1b6b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
1b6c0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e b(), sqlite3_bin
1b6d0 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a d_text(), and.**
1b6e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
1b6f0 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74 xt16() is a dest
1b700 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 ructor used to d
1b710 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c ispose of the BL
1b720 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 OB or.** string
1b730 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 after SQLite has
1b740 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 finished with i
1b750 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 68 20 t. If the fifth
1b760 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 argument is.** t
1b770 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 he special value
1b780 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d [SQLITE_STATIC]
1b790 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 , then SQLite as
1b7a0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a sumes that the.*
1b7b0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 * information is
1b7c0 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 in static, unma
1b7d0 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 naged space and
1b7e0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
1b7f0 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 be freed..** If
1b800 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d the fifth argum
1b810 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 ent has the valu
1b820 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 e [SQLITE_TRANSI
1b830 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 ENT], then.** SQ
1b840 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f Lite makes its o
1b850 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 wn private copy
1b860 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 of the data imme
1b870 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a diately, before.
1b880 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 ** the sqlite3_b
1b890 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 ind_*() routine
1b8a0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 returns..**.** T
1b8b0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
1b8c0 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 zeroblob() routi
1b8d0 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 ne binds a BLOB
1b8e0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 of length N that
1b8f0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 .** is filled wi
1b900 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65 th zeroes. A ze
1b910 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 roblob uses a fi
1b920 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 xed amount of me
1b930 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e mory.** (just an
1b940 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 integer to hold
1b950 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 its size) while
1b960 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f it is being pro
1b970 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 cessed..** Zerob
1b980 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 lobs are intende
1b990 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c d to serve as pl
1b9a0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 aceholders for B
1b9b0 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f LOBs whose.** co
1b9c0 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 ntent is later w
1b9d0 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 ritten using.**
1b9e0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
1b9f0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c en | incremental
1ba00 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 BLOB I/O] routi
1ba10 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69 nes..** A negati
1ba20 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 ve value for the
1ba30 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 zeroblob result
1ba40 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 s in a zero-leng
1ba50 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 th BLOB..**.** T
1ba60 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
1ba70 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 *() routines mus
1ba80 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65 t be called afte
1ba90 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 r.** [sqlite3_pr
1baa0 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 epare_v2()] (and
1bab0 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f its variants) o
1bac0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
1bad0 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 ()] and.** befor
1bae0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
1baf0 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 )]..** Bindings
1bb00 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 are not cleared
1bb10 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
1bb20 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 reset()] routine
1bb30 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 ..** Unbound par
1bb40 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 ameters are inte
1bb50 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e rpreted as NULL.
1bb60 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
1bb70 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 tines return [SQ
1bb80 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
1bb90 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 ess or an error
1bba0 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 code if.** anyth
1bbb0 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 ing goes wrong.
1bbc0 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 [SQLITE_RANGE]
1bbd0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 is returned if t
1bbe0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 he parameter.**
1bbf0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 index is out of
1bc00 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f range. [SQLITE_
1bc10 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e NOMEM] is return
1bc20 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 ed if malloc() f
1bc30 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 ails..** [SQLITE
1bc40 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62 _MISUSE] might b
1bc50 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 e returned if th
1bc60 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
1bc70 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 called on a.**
1bc80 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 virtual machine
1bc90 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e that is the wron
1bca0 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68 g state or which
1bcb0 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65 has already bee
1bcc0 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 n finalized..**
1bcd0 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 Detection of mis
1bce0 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c use is unreliabl
1bcf0 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 e. Applications
1bd00 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 should not depe
1bd10 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f nd.** on SQLITE_
1bd20 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20 MISUSE returns.
1bd30 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 SQLITE_MISUSE i
1bd40 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e s intended to in
1bd50 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f dicate a.** a lo
1bd60 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65 gic error in the
1bd70 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 application. F
1bd80 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
1bd90 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a f SQLite might.*
1bda0 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72 20 74 * panic rather t
1bdb0 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54 han return SQLIT
1bdc0 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 E_MISUSE..**.**
1bdd0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
1bde0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
1bdf0 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b r_count()],.** [
1be00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
1be10 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 ameter_name()],
1be20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e and [sqlite3_bin
1be30 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
1be40 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 x()]..**.** Requ
1be50 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
1be60 33 35 30 36 5d 20 5b 48 31 33 35 30 39 5d 20 5b 3506] [H13509] [
1be70 48 31 33 35 31 32 5d 20 5b 48 31 33 35 31 35 5d H13512] [H13515]
1be80 20 5b 48 31 33 35 31 38 5d 20 5b 48 31 33 35 32 [H13518] [H1352
1be90 31 5d 20 5b 48 31 33 35 32 34 5d 20 5b 48 31 33 1] [H13524] [H13
1bea0 35 32 37 5d 0a 2a 2a 20 5b 48 31 33 35 33 30 5d 527].** [H13530]
1beb0 20 5b 48 31 33 35 33 33 5d 20 5b 48 31 33 35 33 [H13533] [H1353
1bec0 36 5d 20 5b 48 31 33 35 33 39 5d 20 5b 48 31 33 6] [H13539] [H13
1bed0 35 34 32 5d 20 5b 48 31 33 35 34 35 5d 20 5b 48 542] [H13545] [H
1bee0 31 33 35 34 38 5d 20 5b 48 31 33 35 35 31 5d 0a 13548] [H13551].
1bef0 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 **.*/.int sqlite
1bf00 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 3_bind_blob(sqli
1bf10 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
1bf20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
1bf30 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 n, void(*)(void
1bf40 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 *));.int sqlite3
1bf50 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c _bind_double(sql
1bf60 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
1bf70 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 double);.int sq
1bf80 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 lite3_bind_int(s
1bf90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
1bfa0 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c t, int);.int sql
1bfb0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 ite3_bind_int64(
1bfc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
1bfd0 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 nt, sqlite3_int6
1bfe0 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 4);.int sqlite3_
1bff0 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 bind_null(sqlite
1c000 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 3_stmt*, int);.i
1c010 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
1c020 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d text(sqlite3_stm
1c030 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 t*, int, const c
1c040 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 har*, int n, voi
1c050 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e d(*)(void*));.in
1c060 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 t sqlite3_bind_t
1c070 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ext16(sqlite3_st
1c080 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
1c090 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 void*, int, void
1c0a0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 (*)(void*));.int
1c0b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 sqlite3_bind_va
1c0c0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lue(sqlite3_stmt
1c0d0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 *, int, const sq
1c0e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
1c0f0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
1c100 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 zeroblob(sqlite3
1c110 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 _stmt*, int, int
1c120 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 n);../*.** CAPI
1c130 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 3REF: Number Of
1c140 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 20 7b SQL Parameters {
1c150 48 31 33 36 30 30 7d 20 3c 53 37 30 33 30 30 3e H13600} <S70300>
1c160 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
1c170 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ine can be used
1c180 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 to find the numb
1c190 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d er of [SQL param
1c1a0 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b eters].** in a [
1c1b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1c1c0 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 nt]. SQL parame
1c1d0 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 ters are tokens
1c1e0 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 of the.** form "
1c1f0 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 ?", "?NNN", ":AA
1c200 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 A", "$AAA", or "
1c210 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 @AAA" that serve
1c220 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 as.** placehold
1c230 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 ers for values t
1c240 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 hat are [sqlite3
1c250 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 _bind_blob | bou
1c260 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 nd].** to the pa
1c270 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 rameters at a la
1c280 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 ter time..**.**
1c290 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 This routine act
1c2a0 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 ually returns th
1c2b0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c e index of the l
1c2c0 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 argest (rightmos
1c2d0 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e t).** parameter.
1c2e0 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 For all forms e
1c2f0 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 xcept ?NNN, this
1c300 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 will correspond
1c310 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 to the.** numbe
1c320 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 r of unique para
1c330 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 meters. If para
1c340 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e meters of the ?N
1c350 4e 4e 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 NN are used,.**
1c360 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 there may be gap
1c370 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a s in the list..*
1c380 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
1c390 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
1c3a0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
1c3b0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
1c3c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
1c3d0 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 me()], and.** [s
1c3e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1c3f0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
1c400 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
1c410 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 30 31 5d 0a ts:.** [H13601].
1c420 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
1c430 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
1c440 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
1c450 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1c460 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 REF: Name Of A H
1c470 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b 48 ost Parameter {H
1c480 31 33 36 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a 13620} <S70300>.
1c490 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
1c4a0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ne returns a poi
1c4b0 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 nter to the name
1c4c0 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 of the n-th.**
1c4d0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 [SQL parameter]
1c4e0 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 in a [prepared s
1c4f0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 tatement]..** SQ
1c500 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 L parameters of
1c510 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 the form "?NNN"
1c520 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 or ":AAA" or "@A
1c530 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a AA" or "$AAA".**
1c540 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 have a name whi
1c550 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 ch is the string
1c560 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 "?NNN" or ":AAA
1c570 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 " or "@AAA" or "
1c580 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 $AAA".** respect
1c590 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 ively..** In oth
1c5a0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e er words, the in
1c5b0 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 itial ":" or "$"
1c5c0 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a or "@" or "?".*
1c5d0 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 * is included as
1c5e0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d part of the nam
1c5f0 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 e..** Parameters
1c600 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 of the form "?"
1c610 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f without a follo
1c620 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 wing integer hav
1c630 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 e no name.** and
1c640 20 61 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72 are also referr
1c650 65 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d ed to as "anonym
1c660 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e ous parameters".
1c670 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
1c680 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 host parameter
1c690 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 has an index of
1c6a0 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 1, not 0..**.**
1c6b0 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 If the value n i
1c6c0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f s out of range o
1c6d0 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 r if the n-th pa
1c6e0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 rameter is.** na
1c6f0 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c meless, then NUL
1c700 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 L is returned.
1c710 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
1c720 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 ing is.** always
1c730 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 in UTF-8 encodi
1c740 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e ng even if the n
1c750 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 amed parameter w
1c760 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 as.** originally
1c770 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 specified as UT
1c780 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 F-16 in [sqlite3
1c790 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 _prepare16()] or
1c7a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
1c7b0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a pare16_v2()]..**
1c7c0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
1c7d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
1c7e0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
1c7f0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
1c800 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
1c810 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 nt()], and.** [s
1c820 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1c830 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
1c840 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
1c850 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 32 31 5d 0a ts:.** [H13621].
1c860 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
1c870 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1c880 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 meter_name(sqlit
1c890 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a e3_stmt*, int);.
1c8a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1c8b0 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 Index Of A Para
1c8c0 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 meter With A Giv
1c8d0 65 6e 20 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d en Name {H13640}
1c8e0 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S70300>.**.**
1c8f0 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 Return the index
1c900 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d of an SQL param
1c910 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e eter given its n
1c920 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 ame. The.** ind
1c930 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 ex value returne
1c940 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f d is suitable fo
1c950 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 r use as the sec
1c960 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ond.** parameter
1c970 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e to [sqlite3_bin
1c980 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
1c990 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a ind()]. A zero.
1c9a0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 ** is returned i
1c9b0 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 f no matching pa
1c9c0 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 rameter is found
1c9d0 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 . The parameter
1c9e0 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 .** name must be
1c9f0 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 given in UTF-8
1ca00 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 even if the orig
1ca10 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a inal statement.*
1ca20 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 * was prepared f
1ca30 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 rom UTF-16 text
1ca40 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 using [sqlite3_p
1ca50 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a repare16_v2()]..
1ca60 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
1ca70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
1ca80 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 ob|sqlite3_bind(
1ca90 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
1caa0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
1cab0 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 ount()], and.**
1cac0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
1cad0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
1cae0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
1caf0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 34 31 ents:.** [H13641
1cb00 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ].*/.int sqlite3
1cb10 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
1cb20 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 index(sqlite3_st
1cb30 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 mt*, const char
1cb40 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *zName);../*.**
1cb50 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 CAPI3REF: Reset
1cb60 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 All Bindings On
1cb70 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
1cb80 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 ment {H13660} <S
1cb90 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 70300>.**.** Con
1cba0 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 trary to the int
1cbb0 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 uition of many,
1cbc0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
1cbd0 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 ] does not reset
1cbe0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 .** the [sqlite3
1cbf0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e _bind_blob | bin
1cc00 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 dings] on a [pre
1cc10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1cc20 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f ..** Use this ro
1cc30 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 utine to reset a
1cc40 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 ll host paramete
1cc50 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a rs to NULL..**.*
1cc60 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
1cc70 2a 2a 20 5b 48 31 33 36 36 31 5d 0a 2a 2f 0a 69 ** [H13661].*/.i
1cc80 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 nt sqlite3_clear
1cc90 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 _bindings(sqlite
1cca0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
1ccb0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 CAPI3REF: Numbe
1ccc0 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 r Of Columns In
1ccd0 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 A Result Set {H1
1cce0 33 37 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 3710} <S10700>.*
1ccf0 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 *.** Return the
1cd00 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
1cd10 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 s in the result
1cd20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 set returned by
1cd30 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
1cd40 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 statement]. Thi
1cd50 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
1cd60 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 s 0 if pStmt is
1cd70 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d an SQL.** statem
1cd80 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f ent that does no
1cd90 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 t return data (f
1cda0 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 or example an [U
1cdb0 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 52 PDATE])..**.** R
1cdc0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
1cdd0 5b 48 31 33 37 31 31 5d 0a 2a 2f 0a 69 6e 74 20 [H13711].*/.int
1cde0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
1cdf0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d ount(sqlite3_stm
1ce00 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
1ce10 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 * CAPI3REF: Colu
1ce20 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 mn Names In A Re
1ce30 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 32 30 sult Set {H13720
1ce40 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a } <S10700>.**.**
1ce50 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
1ce60 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 return the name
1ce70 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 assigned to a pa
1ce80 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a rticular column.
1ce90 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ** in the result
1cea0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 set of a [SELEC
1ceb0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 T] statement. T
1cec0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
1ced0 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 n_name().** inte
1cee0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
1cef0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 pointer to a zer
1cf00 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
1cf10 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 -8 string.** and
1cf20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
1cf30 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 name16() returns
1cf40 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
1cf50 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
1cf60 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 ** UTF-16 string
1cf70 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 . The first par
1cf80 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 ameter is the [p
1cf90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1cfa0 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 t].** that imple
1cfb0 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 ments the [SELEC
1cfc0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 T] statement. Th
1cfd0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
1cfe0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c er is the.** col
1cff0 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 umn number. The
1d000 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e leftmost column
1d010 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a is number 0..**
1d020 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 .** The returned
1d030 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 string pointer
1d040 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 is valid until e
1d050 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 ither the [prepa
1d060 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a red statement].*
1d070 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 * is destroyed b
1d080 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c y [sqlite3_final
1d090 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 ize()] or until
1d0a0 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f the next call to
1d0b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
1d0c0 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c mn_name() or sql
1d0d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
1d0e0 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 16() on the same
1d0f0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 column..**.** I
1d100 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 f sqlite3_malloc
1d110 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 () fails during
1d120 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f the processing o
1d130 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 f either routine
1d140 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 .** (for example
1d150 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 during a conver
1d160 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 sion from UTF-8
1d170 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 to UTF-16) then
1d180 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
1d190 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a r is returned..*
1d1a0 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 *.** The name of
1d1b0 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e a result column
1d1c0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
1d1d0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 the "AS" clause
1d1e0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c for.** that col
1d1f0 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 umn, if there is
1d200 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 an AS clause.
1d210 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 If there is no A
1d220 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e S clause.** then
1d230 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
1d240 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 column is unspe
1d250 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 cified and may c
1d260 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e hange from.** on
1d270 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c e release of SQL
1d280 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e ite to the next.
1d290 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
1d2a0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 32 31 5d nts:.** [H13721]
1d2b0 20 5b 48 31 33 37 32 33 5d 20 5b 48 31 33 37 32 [H13723] [H1372
1d2c0 34 5d 20 5b 48 31 33 37 32 35 5d 20 5b 48 31 33 4] [H13725] [H13
1d2d0 37 32 36 5d 20 5b 48 31 33 37 32 37 5d 0a 2a 2f 726] [H13727].*/
1d2e0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
1d2f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
1d300 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
1d310 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f int N);.const vo
1d320 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
1d330 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 mn_name16(sqlite
1d340 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 3_stmt*, int N);
1d350 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1d360 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 : Source Of Data
1d370 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 In A Query Resu
1d380 6c 74 20 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 lt {H13740} <S10
1d390 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 700>.**.** These
1d3a0 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 routines provid
1d3b0 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 e a means to det
1d3c0 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 ermine what colu
1d3d0 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 mn of what.** ta
1d3e0 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 ble in which dat
1d3f0 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f abase a result o
1d400 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 f a [SELECT] sta
1d410 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f tement comes fro
1d420 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f m..** The name o
1d430 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f f the database o
1d440 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d r table or colum
1d450 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 n can be returne
1d460 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 d as.** either a
1d470 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 UTF-8 or UTF-16
1d480 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 string. The _d
1d490 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 atabase_ routine
1d4a0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 s return.** the
1d4b0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 database name, t
1d4c0 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 he _table_ routi
1d4d0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 nes return the t
1d4e0 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a able name, and.*
1d4f0 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f * the origin_ ro
1d500 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
1d510 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a e column name..*
1d520 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 * The returned s
1d530 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 tring is valid u
1d540 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 ntil the [prepar
1d550 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 ed statement] is
1d560 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 destroyed.** us
1d570 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
1d580 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 alize()] or unti
1d590 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 l the same infor
1d5a0 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 mation is reques
1d5b0 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 ted.** again in
1d5c0 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f a different enco
1d5d0 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ding..**.** The
1d5e0 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 names returned a
1d5f0 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 re the original
1d600 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 un-aliased names
1d610 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 of the.** datab
1d620 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 ase, table, and
1d630 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 column..**.** Th
1d640 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
1d650 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e to the followin
1d660 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 g calls is a [pr
1d670 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1d680 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 ]..** These func
1d690 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 tions return inf
1d6a0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 ormation about t
1d6b0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 he Nth column re
1d6c0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 turned by.** the
1d6d0 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 statement, wher
1d6e0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e e N is the secon
1d6f0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d d function argum
1d700 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ent..**.** If th
1d710 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 e Nth column ret
1d720 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 urned by the sta
1d730 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 tement is an exp
1d740 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 ression or.** su
1d750 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f bquery and is no
1d760 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 t a column value
1d770 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 , then all of th
1d780 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 ese functions re
1d790 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 turn.** NULL. T
1d7a0 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 hese routine mig
1d7b0 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e ht also return N
1d7c0 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 ULL if a memory
1d7d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
1d7e0 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 .** occurs. Oth
1d7f0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 erwise, they ret
1d800 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 urn the name of
1d810 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 the attached dat
1d820 61 62 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 abase, table.**
1d830 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 and column that
1d840 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c query result col
1d850 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 umn was extracte
1d860 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 d from..**.** As
1d870 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 with all other
1d880 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f SQLite APIs, tho
1d890 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 se postfixed wit
1d8a0 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a h "16" return.**
1d8b0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 UTF-16 encoded
1d8c0 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 strings, the oth
1d8d0 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 er functions ret
1d8e0 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d urn UTF-8. {END}
1d8f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 .**.** These API
1d900 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c s are only avail
1d910 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 able if the libr
1d920 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 ary was compiled
1d930 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 with the.** [SQ
1d940 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 LITE_ENABLE_COLU
1d950 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 MN_METADATA] C-p
1d960 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 reprocessor symb
1d970 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a ol defined..**.*
1d980 2a 20 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 * {A13751}.** If
1d990 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 two or more thr
1d9a0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 eads call one or
1d9b0 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 more of these r
1d9c0 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 outines against
1d9d0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 the same.** prep
1d9e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 ared statement a
1d9f0 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 nd column at the
1da00 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 same time then
1da10 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a the results are.
1da20 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a ** undefined..**
1da30 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
1da40 3a 0a 2a 2a 20 5b 48 31 33 37 34 31 5d 20 5b 48 :.** [H13741] [H
1da50 31 33 37 34 32 5d 20 5b 48 31 33 37 34 33 5d 20 13742] [H13743]
1da60 5b 48 31 33 37 34 34 5d 20 5b 48 31 33 37 34 35 [H13744] [H13745
1da70 5d 20 5b 48 31 33 37 34 36 5d 20 5b 48 31 33 37 ] [H13746] [H137
1da80 34 38 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 48].**.** If two
1da90 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 or more threads
1daa0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 call one or mor
1dab0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f e.** [sqlite3_co
1dac0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
1dad0 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 me | column meta
1dae0 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d data interfaces]
1daf0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 .** for the same
1db00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1db10 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 ment] and result
1db20 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 column.** at th
1db30 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e e same time then
1db40 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
1db50 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 undefined..*/.c
1db60 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
1db70 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 e3_column_databa
1db80 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f se_name(sqlite3_
1db90 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
1dba0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
1dbb0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
1dbc0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
1dbd0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 tmt*,int);.const
1dbe0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
1dbf0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 olumn_table_name
1dc00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
1dc10 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
1dc20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
1dc30 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c table_name16(sql
1dc40 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
1dc50 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
1dc60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 ite3_column_orig
1dc70 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f in_name(sqlite3_
1dc80 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
1dc90 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
1dca0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
1dcb0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
1dcc0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t*,int);../*.**
1dcd0 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 CAPI3REF: Declar
1dce0 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 ed Datatype Of A
1dcf0 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 Query Result {H
1dd00 31 33 37 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 13760} <S10700>.
1dd10 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
1dd20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b parameter is a [
1dd30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1dd40 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 nt]..** If this
1dd50 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b statement is a [
1dd60 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
1dd70 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f t and the Nth co
1dd80 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 lumn of the.** r
1dd90 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 eturned result s
1dda0 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 et of that [SELE
1ddb0 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 CT] is a table c
1ddc0 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a olumn (not an.**
1ddd0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 expression or s
1dde0 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 ubquery) then th
1ddf0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 e declared type
1de00 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 of the table.**
1de10 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e column is return
1de20 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 ed. If the Nth
1de30 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 column of the re
1de40 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a sult set is an.*
1de50 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 * expression or
1de60 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 subquery, then a
1de70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 NULL pointer is
1de80 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 returned..** Th
1de90 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
1dea0 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d g is always UTF-
1deb0 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 8 encoded. {END}
1dec0 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 .**.** For examp
1ded0 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 le, given the da
1dee0 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a tabase schema:.*
1def0 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c *.** CREATE TABL
1df00 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 E t1(c1 VARIANT)
1df10 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 ;.**.** and the
1df20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d following statem
1df30 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c ent to be compil
1df40 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 ed:.**.** SELECT
1df50 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d c1 + 1, c1 FROM
1df60 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 t1;.**.** this
1df70 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 routine would re
1df80 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 turn the string
1df90 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 "VARIANT" for th
1dfa0 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a e second result.
1dfb0 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 ** column (i==1)
1dfc0 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 , and a NULL poi
1dfd0 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 nter for the fir
1dfe0 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e st result column
1dff0 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 (i==0)..**.** S
1e000 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d QLite uses dynam
1e010 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 ic run-time typi
1e020 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 ng. So just bec
1e030 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a ause a column.**
1e040 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 is declared to
1e050 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 contain a partic
1e060 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e ular type does n
1e070 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 ot mean that the
1e080 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 .** data stored
1e090 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 in that column i
1e0a0 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 s of the declare
1e0b0 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 d type. SQLite
1e0c0 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 is.** strongly t
1e0d0 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 yped, but the ty
1e0e0 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 ping is dynamic
1e0f0 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 not static. Typ
1e100 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 e.** is associat
1e110 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 ed with individu
1e120 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 al values, not w
1e130 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 ith the containe
1e140 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f rs.** used to ho
1e150 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e ld those values.
1e160 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
1e170 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 36 31 5d nts:.** [H13761]
1e180 20 5b 48 31 33 37 36 32 5d 20 5b 48 31 33 37 36 [H13762] [H1376
1e190 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 3].*/.const char
1e1a0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
1e1b0 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 _decltype(sqlite
1e1c0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
1e1d0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
1e1e0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 3_column_decltyp
1e1f0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
1e200 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 *,int);../*.** C
1e210 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 API3REF: Evaluat
1e220 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 e An SQL Stateme
1e230 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30 nt {H13200} <S10
1e240 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 000>.**.** After
1e250 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
1e260 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e tement] has been
1e270 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 prepared using
1e280 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 either.** [sqlit
1e290 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1e2a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
1e2b0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 pare16_v2()] or
1e2c0 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 one of the legac
1e2d0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 y.** interfaces
1e2e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1e2f0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
1e300 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 prepare16()], th
1e310 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d is function.** m
1e320 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e ust be called on
1e330 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 e or more times
1e340 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 to evaluate the
1e350 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a statement..**.**
1e360 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 The details of
1e370 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
1e380 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 the sqlite3_step
1e390 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 () interface dep
1e3a0 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 end.** on whethe
1e3b0 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 r the statement
1e3c0 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 was prepared usi
1e3d0 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 ng the newer "v2
1e3e0 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b " interface.** [
1e3f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1e400 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 v2()] and [sqlit
1e410 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
1e420 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 )] or the older
1e430 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 legacy.** interf
1e440 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ace [sqlite3_pre
1e450 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c pare()] and [sql
1e460 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
1e470 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 ]. The use of t
1e480 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 he.** new "v2" i
1e490 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f nterface is reco
1e4a0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 mmended for new
1e4b0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 applications but
1e4c0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 the legacy.** i
1e4d0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f nterface will co
1e4e0 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 ntinue to be sup
1e4f0 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e ported..**.** In
1e500 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
1e510 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 rface, the retur
1e520 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 n value will be
1e530 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 either [SQLITE_B
1e540 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 USY],.** [SQLITE
1e550 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f _DONE], [SQLITE_
1e560 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 ROW], [SQLITE_ER
1e570 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 ROR], or [SQLITE
1e580 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 _MISUSE]..** Wit
1e590 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 h the "v2" inter
1e5a0 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 face, any of the
1e5b0 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 other [result c
1e5c0 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 odes] or.** [ext
1e5d0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
1e5e0 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 es] might be ret
1e5f0 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a urned as well..*
1e600 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 *.** [SQLITE_BUS
1e610 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 Y] means that th
1e620 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e e database engin
1e630 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 e was unable to
1e640 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 acquire the.** d
1e650 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 atabase locks it
1e660 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 needs to do its
1e670 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 job. If the st
1e680 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f atement is a [CO
1e690 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 MMIT].** or occu
1e6a0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e rs outside of an
1e6b0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 explicit transa
1e6c0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 ction, then you
1e6d0 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a can retry the.**
1e6e0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 statement. If
1e6f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
1e700 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 not a [COMMIT]
1e710 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 and occurs withi
1e720 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 n a.** explicit
1e730 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e transaction then
1e740 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c you should roll
1e750 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 back the transac
1e760 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 tion before.** c
1e770 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a ontinuing..**.**
1e780 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d [SQLITE_DONE] m
1e790 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 eans that the st
1e7a0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 atement has fini
1e7b0 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a shed executing.*
1e7c0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 * successfully.
1e7d0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
1e7e0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 should not be ca
1e7f0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 lled again on th
1e800 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 is virtual.** ma
1e810 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 chine without fi
1e820 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c rst calling [sql
1e830 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f ite3_reset()] to
1e840 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 reset the virtu
1e850 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 al.** machine ba
1e860 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 ck to its initia
1e870 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 l state..**.** I
1e880 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d f the SQL statem
1e890 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 ent being execut
1e8a0 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 ed returns any d
1e8b0 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 ata, then [SQLIT
1e8c0 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 E_ROW].** is ret
1e8d0 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 urned each time
1e8e0 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 a new row of dat
1e8f0 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 a is ready for p
1e900 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 rocessing by the
1e910 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 .** caller. The
1e920 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 values may be ac
1e930 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 cessed using the
1e940 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 [column access
1e950 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 functions]..** s
1e960 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 qlite3_step() is
1e970 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f called again to
1e980 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 retrieve the ne
1e990 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a xt row of data..
1e9a0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 **.** [SQLITE_ER
1e9b0 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 ROR] means that
1e9c0 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 a run-time error
1e9d0 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 (such as a cons
1e9e0 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 traint.** violat
1e9f0 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 ion) has occurre
1ea00 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 d. sqlite3_step
1ea10 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 () should not be
1ea20 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e called again on
1ea30 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 .** the VM. More
1ea40 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 information may
1ea50 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c be found by cal
1ea60 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 ling [sqlite3_er
1ea70 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 rmsg()]..** With
1ea80 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
1ea90 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 rface, a more sp
1eaa0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 ecific error cod
1eab0 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a e (for example,.
1eac0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 ** [SQLITE_INTER
1ead0 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 RUPT], [SQLITE_S
1eae0 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f CHEMA], [SQLITE_
1eaf0 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f CORRUPT], and so
1eb00 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 forth).** can b
1eb10 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 e obtained by ca
1eb20 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 lling [sqlite3_r
1eb30 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a eset()] on the.*
1eb40 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
1eb50 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 ement]. In the
1eb60 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a "v2" interface,.
1eb70 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 ** the more spec
1eb80 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 ific error code
1eb90 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 is returned dire
1eba0 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f ctly by sqlite3_
1ebb0 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 step()..**.** [S
1ebc0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 QLITE_MISUSE] me
1ebd0 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 ans that the thi
1ebe0 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 s routine was ca
1ebf0 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 lled inappropria
1ec00 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 tely..** Perhaps
1ec10 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f it was called o
1ec20 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
1ec30 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 atement] that ha
1ec40 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 s.** already bee
1ec50 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c n [sqlite3_final
1ec60 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d ize | finalized]
1ec70 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 or on one that
1ec80 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c had.** previousl
1ec90 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 y returned [SQLI
1eca0 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 TE_ERROR] or [SQ
1ecb0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 LITE_DONE]. Or
1ecc0 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 it could.** be t
1ecd0 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 he case that the
1ece0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
1ecf0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 onnection is bei
1ed00 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f ng used by two o
1ed10 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 r.** more thread
1ed20 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f s at the same mo
1ed30 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a ment in time..**
1ed40 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 .** <b>Goofy Int
1ed50 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 erface Alert:</b
1ed60 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 > In the legacy
1ed70 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 interface, the s
1ed80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a qlite3_step().**
1ed90 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 API always retu
1eda0 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 rns a generic er
1edb0 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 ror code, [SQLIT
1edc0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 E_ERROR], follow
1edd0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 ing any.** error
1ede0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
1edf0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 ITE_BUSY] and [S
1ee00 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 QLITE_MISUSE].
1ee10 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a You must call.**
1ee20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
1ee30 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 )] or [sqlite3_f
1ee40 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 inalize()] in or
1ee50 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 der to find one
1ee60 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 of the.** specif
1ee70 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ic [error codes]
1ee80 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 that better des
1ee90 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 cribes the error
1eea0 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 ..** We admit th
1eeb0 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f at this is a goo
1eec0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 fy design. The
1eed0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e problem has been
1eee0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 fixed.** with t
1eef0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
1ef00 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 e. If you prepa
1ef10 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 re all of your S
1ef20 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
1ef30 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 using either [s
1ef40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1ef50 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
1ef60 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
1ef70 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 instead.** of t
1ef80 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 he legacy [sqlit
1ef90 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e e3_prepare()] an
1efa0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
1efb0 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 re16()] interfac
1efc0 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 es,.** then the
1efd0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 more specific [e
1efe0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 rror codes] are
1eff0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c returned directl
1f000 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f y.** by sqlite3_
1f010 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 step(). The use
1f020 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 of the "v2" int
1f030 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d erface is recomm
1f040 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 ended..**.** Req
1f050 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
1f060 31 33 32 30 32 5d 20 5b 48 31 35 33 30 34 5d 20 13202] [H15304]
1f070 5b 48 31 35 33 30 36 5d 20 5b 48 31 35 33 30 38 [H15306] [H15308
1f080 5d 20 5b 48 31 35 33 31 30 5d 0a 2a 2f 0a 69 6e ] [H15310].*/.in
1f090 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 t sqlite3_step(s
1f0a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
1f0b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1f0c0 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e Number of column
1f0d0 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 s in a result se
1f0e0 74 20 7b 48 31 33 37 37 30 7d 20 3c 53 31 30 37 t {H13770} <S107
1f0f0 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 00>.**.** Return
1f100 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
1f110 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 values in the cu
1f120 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 rrent row of the
1f130 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a result set..**.
1f140 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
1f150 0a 2a 2a 20 5b 48 31 33 37 37 31 5d 20 5b 48 31 .** [H13771] [H1
1f160 33 37 37 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 3772].*/.int sql
1f170 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
1f180 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
1f190 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
1f1a0 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 I3REF: Fundament
1f1b0 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 48 31 al Datatypes {H1
1f1c0 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53 0265} <S10110><S
1f1d0 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 10120>.** KEYWOR
1f1e0 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a DS: SQLITE_TEXT.
1f1f0 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45 **.** {H10266} E
1f200 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 very value in SQ
1f210 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 Lite has one of
1f220 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c five fundamental
1f230 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a datatypes:.**.*
1f240 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 * <ul>.** <li> 6
1f250 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 4-bit signed int
1f260 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d eger.** <li> 64-
1f270 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e bit IEEE floatin
1f280 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a g point number.*
1f290 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a * <li> string.**
1f2a0 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c <li> BLOB.** <l
1f2b0 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e i> NULL.** </ul>
1f2c0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 {END}.**.** The
1f2d0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 se constants are
1f2e0 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 codes for each
1f2f0 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a of those types..
1f300 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
1f310 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 the SQLITE_TEXT
1f320 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 constant was als
1f330 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 o used in SQLite
1f340 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f version 2.** fo
1f350 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 r a completely d
1f360 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 ifferent meaning
1f370 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 . Software that
1f380 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 links against b
1f390 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 oth.** SQLite ve
1f3a0 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 rsion 2 and SQLi
1f3b0 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f te version 3 sho
1f3c0 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f uld use SQLITE3_
1f3d0 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c TEXT, not.** SQL
1f3e0 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 ITE_TEXT..*/.#de
1f3f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
1f400 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 GER 1.#define S
1f410 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 QLITE_FLOAT 2
1f420 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1f430 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 BLOB 4.#defi
1f440 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 ne SQLITE_NULL
1f450 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 5.#ifdef SQLI
1f460 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 TE_TEXT.# undef
1f470 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 SQLITE_TEXT.#els
1f480 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 e.# define SQLIT
1f490 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e E_TEXT 3.#en
1f4a0 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 dif.#define SQLI
1f4b0 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a TE3_TEXT 3..
1f4c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1f4d0 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 Result Values Fr
1f4e0 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31 33 38 om A Query {H138
1f4f0 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 00} <S10700>.**
1f500 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d KEYWORDS: {colum
1f510 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f n access functio
1f520 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ns}.**.** These
1f530 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 routines form th
1f540 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 75 e "result set qu
1f550 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a ery" interface..
1f560 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
1f570 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f ines return info
1f580 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 rmation about a
1f590 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 single column of
1f5a0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
1f5b0 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 result row of a
1f5c0 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79 query. In every
1f5d0 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 case the first
1f5e0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f argument is a po
1f5f0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 inter.** to the
1f600 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1f610 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 ent] that is bei
1f620 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 ng evaluated (th
1f630 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a e [sqlite3_stmt*
1f640 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 ].** that was re
1f650 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c turned from [sql
1f660 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1f670 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 )] or one of its
1f680 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e variants).** an
1f690 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 d the second arg
1f6a0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 ument is the ind
1f6b0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e ex of the column
1f6c0 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 for which infor
1f6d0 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 mation.** should
1f6e0 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54 be returned. T
1f6f0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 he leftmost colu
1f700 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 mn of the result
1f710 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 set has the ind
1f720 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 ex 0..**.** If t
1f730 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
1f740 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e does not curren
1f750 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 tly point to a v
1f760 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 alid row, or if
1f770 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e the.** column in
1f780 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 dex is out of ra
1f790 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 nge, the result
1f7a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
1f7b0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
1f7c0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c may only be call
1f7d0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 ed when the most
1f7e0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a recent call to.
1f7f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
1f800 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 ()] has returned
1f810 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e [SQLITE_ROW] an
1f820 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 d neither.** [sq
1f830 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e lite3_reset()] n
1f840 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 or [sqlite3_fina
1f850 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 lize()] have bee
1f860 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 n called subsequ
1f870 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 ently..** If any
1f880 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
1f890 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 es are called af
1f8a0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ter [sqlite3_res
1f8b0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c et()] or.** [sql
1f8c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
1f8d0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 or after [sqlit
1f8e0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 e3_step()] has r
1f8f0 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 eturned.** somet
1f900 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 hing other than
1f910 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 [SQLITE_ROW], th
1f920 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
1f930 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b defined..** If [
1f940 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1f950 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 or [sqlite3_rese
1f960 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 t()] or [sqlite3
1f970 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 _finalize()].**
1f980 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 are called from
1f990 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 a different thre
1f9a0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 ad while any of
1f9b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a these routines.*
1f9c0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 * are pending, t
1f9d0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 hen the results
1f9e0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
1f9f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
1fa00 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 _column_type() r
1fa10 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
1fa20 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e he.** [SQLITE_IN
1fa30 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 TEGER | datatype
1fa40 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 code] for the i
1fa50 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 nitial data type
1fa60 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c .** of the resul
1fa70 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 t column. The r
1fa80 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 eturned value is
1fa90 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
1faa0 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 INTEGER],.** [SQ
1fab0 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 LITE_FLOAT], [SQ
1fac0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c LITE_TEXT], [SQL
1fad0 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 ITE_BLOB], or [S
1fae0 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 QLITE_NULL]. Th
1faf0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 e value.** retur
1fb00 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
1fb10 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 olumn_type() is
1fb20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 only meaningful
1fb30 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f if no type.** co
1fb40 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f nversions have o
1fb50 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 ccurred as descr
1fb60 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 ibed below. Aft
1fb70 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 er a type conver
1fb80 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c sion,.** the val
1fb90 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ue returned by s
1fba0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
1fbb0 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 pe() is undefine
1fbc0 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 d. Future.** ve
1fbd0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
1fbe0 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 may change the
1fbf0 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 behavior of sqli
1fc00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
1fc10 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 ).** following a
1fc20 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e type conversion
1fc30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 ..**.** If the r
1fc40 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 esult is a BLOB
1fc50 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 or UTF-8 string
1fc60 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 then the sqlite3
1fc70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a _column_bytes().
1fc80 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
1fc90 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
1fca0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 bytes in that B
1fcb0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a LOB or string..*
1fcc0 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 * If the result
1fcd0 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 is a UTF-16 stri
1fce0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ng, then sqlite3
1fcf0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
1fd00 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 converts.** the
1fd10 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 string to UTF-8
1fd20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 and then returns
1fd30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
1fd40 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 ytes..** If the
1fd50 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 result is a nume
1fd60 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 ric value then s
1fd70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
1fd80 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 tes() uses.** [s
1fd90 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
1fda0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 )] to convert th
1fdb0 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 at value to a UT
1fdc0 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 F-8 string and r
1fdd0 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 eturns.** the nu
1fde0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
1fdf0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a that string..**
1fe00 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 The value retur
1fe10 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 ned does not inc
1fe20 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 lude the zero te
1fe30 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 rminator at the
1fe40 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 end.** of the st
1fe50 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 ring. For clari
1fe60 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 ty: the value re
1fe70 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 turned is the nu
1fe80 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 mber of.** bytes
1fe90 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 in the string,
1fea0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f not the number o
1feb0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a f characters..**
1fec0 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 .** Strings retu
1fed0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
1fee0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e column_text() an
1fef0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
1ff00 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 _text16(),.** ev
1ff10 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 en empty strings
1ff20 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 , are always zer
1ff30 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 o terminated. T
1ff40 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c he return.** val
1ff50 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
1ff60 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f column_blob() fo
1ff70 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 r a zero-length
1ff80 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74 BLOB is an arbit
1ff90 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c rary.** pointer,
1ffa0 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 possibly even a
1ffb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
1ffc0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
1ffd0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
1ffe0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d ) routine is sim
1fff0 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f ilar to sqlite3_
20000 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a column_bytes().*
20010 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 * but leaves the
20020 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 result in UTF-1
20030 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 6 in native byte
20040 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f order instead o
20050 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 f UTF-8..** The
20060 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 zero terminator
20070 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 is not included
20080 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a in this count..*
20090 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 *.** The object
200a0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
200b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
200c0 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 e()] is an.** [u
200d0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
200e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
200f0 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 . An unprotecte
20100 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 d sqlite3_value
20110 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e object.** may on
20120 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 ly be used with
20130 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 [sqlite3_bind_va
20140 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 lue()] and [sqli
20150 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
20160 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b ()]..** If the [
20170 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
20180 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
20190 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a t returned by.**
201a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
201b0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 _value()] is use
201c0 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 d in any other w
201d0 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 ay, including ca
201e0 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e lls.** to routin
201f0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 es like [sqlite3
20200 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b _value_int()], [
20210 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
20220 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 xt()],.** or [sq
20230 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
20240 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 s()], then the b
20250 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
20260 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ined..**.** Thes
20270 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d e routines attem
20280 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 pt to convert th
20290 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 e value where ap
202a0 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a propriate. For.
202b0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 ** example, if t
202c0 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 he internal repr
202d0 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c esentation is FL
202e0 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 OAT and a text r
202f0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 esult.** is requ
20300 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f ested, [sqlite3_
20310 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 snprintf()] is u
20320 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 sed internally t
20330 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a o perform the.**
20340 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f conversion auto
20350 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 matically. The
20360 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 following table
20370 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 details the conv
20380 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 ersions.** that
20390 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a are applied:.**.
203a0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a ** <blockquote>.
203b0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 ** <table border
203c0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 ="1">.** <tr><th
203d0 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 > Internal<br>Ty
203e0 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 pe <th> Requeste
203f0 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 d<br>Type <th>
20400 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a Conversion.**.**
20410 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
20420 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 <td> INTEGER
20430 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
20440 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 0.** <tr><td>
20450 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c NULL <td> FL
20460 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 OAT <td> Resu
20470 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 lt is 0.0.** <tr
20480 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c ><td> NULL <
20490 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 td> TEXT <t
204a0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c d> Result is NUL
204b0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 L pointer.** <tr
204c0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c ><td> NULL <
204d0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
204e0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c d> Result is NUL
204f0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 L pointer.** <tr
20500 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c ><td> INTEGER <
20510 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
20520 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 d> Convert from
20530 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 integer to float
20540 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 .** <tr><td> INT
20550 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 EGER <td> TEX
20560 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 T <td> ASCII
20570 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
20580 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e integer.** <tr>
20590 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 <td> INTEGER <t
205a0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
205b0 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 > Same as INTEGE
205c0 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c R->TEXT.** <tr><
205d0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 td> FLOAT <td
205e0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e > INTEGER <td>
205f0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c Convert from fl
20600 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a oat to integer.*
20610 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 * <tr><td> FLOA
20620 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 T <td> TEXT
20630 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 <td> ASCII re
20640 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 ndering of the f
20650 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e loat.** <tr><td>
20660 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 FLOAT <td>
20670 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 BLOB <td> Sa
20680 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 me as FLOAT->TEX
20690 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 T.** <tr><td> T
206a0 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 EXT <td> INTE
206b0 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 GER <td> Use a
206c0 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 toi().** <tr><td
206d0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 > TEXT <td>
206e0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 FLOAT <td> U
206f0 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 se atof().** <tr
20700 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c ><td> TEXT <
20710 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
20720 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 d> No change.**
20730 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 <tr><td> BLOB
20740 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
20750 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f <td> Convert to
20760 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 TEXT then use a
20770 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 toi().** <tr><td
20780 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 > BLOB <td>
20790 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 FLOAT <td> C
207a0 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 onvert to TEXT t
207b0 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a hen use atof().*
207c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
207d0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 <td> TEXT
207e0 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 <td> Add a ze
207f0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 ro terminator if
20800 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 needed.** </tab
20810 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 le>.** </blockqu
20820 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 ote>.**.** The t
20830 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 able above makes
20840 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 reference to st
20850 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
20860 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 functions atoi(
20870 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e ).** and atof().
20880 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f SQLite does no
20890 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 t really use the
208a0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 se functions. I
208b0 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e t has its.** own
208c0 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 equivalent inte
208d0 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 rnal routines.
208e0 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 The atoi() and a
208f0 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a tof() names are.
20900 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 ** used in the t
20910 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 able for brevity
20920 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 and because the
20930 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 y are familiar t
20940 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 o most.** C prog
20950 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e rammers..**.** N
20960 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 ote that when ty
20970 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f pe conversions o
20980 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 ccur, pointers r
20990 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 eturned by prior
209a0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c .** calls to sql
209b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
209c0 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 (), sqlite3_colu
209d0 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f mn_text(), and/o
209e0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c r.** sqlite3_col
209f0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 umn_text16() may
20a00 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e be invalidated.
20a10 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 .** Type convers
20a20 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 ions and pointer
20a30 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d invalidations m
20a40 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e ight occur.** in
20a50 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 the following c
20a60 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ases:.**.** <ul>
20a70 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 .** <li> The ini
20a80 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 tial content is
20a90 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 a BLOB and sqlit
20aa0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
20ab0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 or.** sqli
20ac0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
20ad0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 6() is called.
20ae0 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f A zero-terminato
20af0 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 r might.**
20b00 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 need to be added
20b10 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c to the string.<
20b20 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 /li>.** <li> The
20b30 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
20b40 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 is UTF-8 text a
20b50 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
20b60 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a n_bytes16() or.*
20b70 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 * sqlite3_c
20b80 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 olumn_text16() i
20b90 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 s called. The c
20ba0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 ontent must be c
20bb0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 onverted.**
20bc0 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e to UTF-16.</li>
20bd0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 .** <li> The ini
20be0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 tial content is
20bf0 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 UTF-16 text and
20c00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
20c10 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 ytes() or.**
20c20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e sqlite3_column
20c30 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 _text() is calle
20c40 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 d. The content
20c50 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 must be converte
20c60 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 d.** to UTF
20c70 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c -8.</li>.** </ul
20c80 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 >.**.** Conversi
20c90 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d ons between UTF-
20ca0 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 16be and UTF-16l
20cb0 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e e are always don
20cc0 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 e in place and d
20cd0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 o.** not invalid
20ce0 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e ate a prior poin
20cf0 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 ter, though of c
20d00 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e ourse the conten
20d10 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a t of the buffer.
20d20 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f ** that the prio
20d30 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 r pointer points
20d40 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 to will have be
20d50 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 en modified. Ot
20d60 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 her kinds.** of
20d70 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 conversion are d
20d80 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 one in place whe
20d90 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 n it is possible
20da0 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 , but sometimes
20db0 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 they.** are not
20dc0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 possible and in
20dd0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f those cases prio
20de0 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 r pointers are i
20df0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a nvalidated..**.*
20e00 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 * The safest and
20e10 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 easiest to reme
20e20 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 mber policy is t
20e30 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 o invoke these r
20e40 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e outines.** in on
20e50 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
20e60 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c ng ways:.**.** <
20e70 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 ul>.** <li>sqli
20e80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
20e90 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 ) followed by sq
20ea0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
20eb0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c es()</li>.** <l
20ec0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e i>sqlite3_column
20ed0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 _blob() followed
20ee0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
20ef0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a mn_bytes()</li>.
20f00 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f ** <li>sqlite3_
20f10 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
20f20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 followed by sqli
20f30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
20f40 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 16()</li>.** </u
20f50 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 l>.**.** In othe
20f60 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f r words, you sho
20f70 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 uld call sqlite3
20f80 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a _column_text(),.
20f90 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
20fa0 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c n_blob(), or sql
20fb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
20fc0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 16() first to fo
20fd0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a rce the result.*
20fe0 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 * into the desir
20ff0 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 ed format, then
21000 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 invoke sqlite3_c
21010 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 olumn_bytes() or
21020 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
21030 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 mn_bytes16() to
21040 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 find the size of
21050 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f the result. Do
21060 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a not mix calls.*
21070 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c * to sqlite3_col
21080 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 umn_text() or sq
21090 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
210a0 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 b() with calls t
210b0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c o.** sqlite3_col
210c0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 umn_bytes16(), a
210d0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 nd do not mix ca
210e0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
210f0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a olumn_text16().*
21100 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 * with calls to
21110 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
21120 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 ytes()..**.** Th
21130 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 e pointers retur
21140 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e ned are valid un
21150 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 til a type conve
21160 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a rsion occurs as.
21170 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f ** described abo
21180 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 ve, or until [sq
21190 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 lite3_step()] or
211a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
211b0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
211c0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 3_finalize()] is
211d0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 called. The me
211e0 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 mory space used
211f0 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a to hold strings.
21200 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 ** and BLOBs is
21210 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 freed automatica
21220 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c lly. Do <b>not<
21230 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 /b> pass the poi
21240 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a nters returned.*
21250 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
21260 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 n_blob()], [sqli
21270 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
21280 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a )], etc. into.**
21290 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
212a0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 ]..**.** If a me
212b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
212c0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 error occurs dur
212d0 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 ing the evaluati
212e0 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 on of any.** of
212f0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 these routines,
21300 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 a default value
21310 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 is returned. Th
21320 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a e default value.
21330 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 ** is either the
21340 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 integer 0, the
21350 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e floating point n
21360 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 umber 0.0, or a
21370 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e NULL.** pointer.
21380 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c Subsequent cal
21390 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 ls to [sqlite3_e
213a0 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 rrcode()] will r
213b0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 eturn.** [SQLITE
213c0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 _NOMEM]..**.** R
213d0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
213e0 5b 48 31 33 38 30 33 5d 20 5b 48 31 33 38 30 36 [H13803] [H13806
213f0 5d 20 5b 48 31 33 38 30 39 5d 20 5b 48 31 33 38 ] [H13809] [H138
21400 31 32 5d 20 5b 48 31 33 38 31 35 5d 20 5b 48 31 12] [H13815] [H1
21410 33 38 31 38 5d 20 5b 48 31 33 38 32 31 5d 20 5b 3818] [H13821] [
21420 48 31 33 38 32 34 5d 0a 2a 2a 20 5b 48 31 33 38 H13824].** [H138
21430 32 37 5d 20 5b 48 31 33 38 33 30 5d 0a 2a 2f 0a 27] [H13830].*/.
21440 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
21450 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
21460 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
21470 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 nt iCol);.int sq
21480 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
21490 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a es(sqlite3_stmt*
214a0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 , int iCol);.int
214b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
214c0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f bytes16(sqlite3_
214d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
214e0 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 ;.double sqlite3
214f0 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 _column_double(s
21500 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
21510 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c t iCol);.int sql
21520 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 ite3_column_int(
21530 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
21540 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 nt iCol);.sqlite
21550 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
21560 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c column_int64(sql
21570 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
21580 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 iCol);.const uns
21590 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 igned char *sqli
215a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
215b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
215c0 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 nt iCol);.const
215d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
215e0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 lumn_text16(sqli
215f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
21600 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 Col);.int sqlite
21610 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 3_column_type(sq
21620 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
21630 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f iCol);.sqlite3_
21640 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 value *sqlite3_c
21650 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 olumn_value(sqli
21660 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
21670 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 Col);../*.** CAP
21680 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 I3REF: Destroy A
21690 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
216a0 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 ent Object {H133
216b0 30 30 7d 20 3c 53 37 30 33 30 30 3e 3c 53 33 30 00} <S70300><S30
216c0 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 100>.**.** The s
216d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
216e0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 ) function is ca
216f0 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 lled to delete a
21700 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
21710 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 ment]..** If the
21720 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65 statement was e
21730 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66 xecuted successf
21740 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 ully or not exec
21750 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 uted at all, the
21760 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 n.** SQLITE_OK i
21770 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20 65 s returned. If e
21780 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 xecution of the
21790 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 statement failed
217a0 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 then an.** [err
217b0 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 or code] or [ext
217c0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
217d0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a ] is returned..*
217e0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
217f0 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 e can be called
21800 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 at any point dur
21810 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f ing the executio
21820 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 n of the.** [pre
21830 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
21840 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61 . If the virtua
21850 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f l machine has no
21860 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 t.** completed e
21870 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 xecution when th
21880 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 is routine is ca
21890 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 lled, that is li
218a0 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 ke.** encounteri
218b0 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 ng an error or a
218c0 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 n [sqlite3_inter
218d0 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 rupt | interrupt
218e0 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 ]..** Incomplete
218f0 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 updates may be
21900 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 rolled back and
21910 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e transactions can
21920 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 celed,.** depend
21930 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 ing on the circu
21940 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 mstances, and th
21950 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 e.** [error code
21960 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 ] returned will
21970 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 be [SQLITE_ABORT
21980 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 ]..**.** Require
21990 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 31 33 30 ments:.** [H1130
219a0 32 5d 20 5b 48 31 31 33 30 34 5d 0a 2a 2f 0a 69 2] [H11304].*/.i
219b0 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c nt sqlite3_final
219c0 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ize(sqlite3_stmt
219d0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
219e0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 CAPI3REF: Reset
219f0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 A Prepared Stat
21a00 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 ement Object {H1
21a10 33 33 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 3330} <S70300>.*
21a20 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
21a30 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f _reset() functio
21a40 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 n is called to r
21a50 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 eset a [prepared
21a60 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f statement].** o
21a70 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 bject back to it
21a80 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c s initial state,
21a90 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d ready to be re-
21aa0 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 executed..** Any
21ab0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 SQL statement v
21ac0 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 ariables that ha
21ad0 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 d values bound t
21ae0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 o them using.**
21af0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
21b00 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 d_blob | sqlite3
21b10 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 _bind_*() API] r
21b20 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 etain their valu
21b30 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 es..** Use [sqli
21b40 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
21b50 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 gs()] to reset t
21b60 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a he bindings..**.
21b70 2a 2a 20 7b 48 31 31 33 33 32 7d 20 54 68 65 20 ** {H11332} The
21b80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
21b90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 )] interface res
21ba0 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 ets the [prepare
21bb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a d statement] S.*
21bc0 2a 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 * back
21bd0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 to the beginning
21be0 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e of its program.
21bf0 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 .**.** {H11334}
21c00 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
21c10 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nt call to [sqli
21c20 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 te3_step(S)] for
21c30 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
21c40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
21c50 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 ment] S returned
21c60 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 [SQLITE_ROW] or
21c70 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a [SQLITE_DONE],.
21c80 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 ** or i
21c90 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 f [sqlite3_step(
21ca0 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 S)] has never be
21cb0 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 fore been called
21cc0 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 on S,.**
21cd0 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 then [sqlite3
21ce0 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 _reset(S)] retur
21cf0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a ns [SQLITE_OK]..
21d00 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 **.** {H11336} I
21d10 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
21d20 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
21d30 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 e3_step(S)] for
21d40 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
21d50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
21d60 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 ent] S indicated
21d70 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a an error, then.
21d80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
21d90 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 ite3_reset(S)] r
21da0 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 eturns an approp
21db0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 riate [error cod
21dc0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 e]..**.** {H1133
21dd0 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 8} The [sqlite3_
21de0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 reset(S)] interf
21df0 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 ace does not cha
21e00 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a nge the values.*
21e10 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e * of an
21e20 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f y [sqlite3_bind_
21e30 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f blob|bindings] o
21e40 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 n the [prepared
21e50 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f statement] S..*/
21e60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 .int sqlite3_res
21e70 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 et(sqlite3_stmt
21e80 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
21e90 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 CAPI3REF: Create
21ea0 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c Or Redefine SQL
21eb0 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 Functions {H161
21ec0 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 00} <S20200>.**
21ed0 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 KEYWORDS: {funct
21ee0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 ion creation rou
21ef0 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 tines}.** KEYWOR
21f00 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e DS: {application
21f10 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
21f20 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 ction}.** KEYWOR
21f30 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e DS: {application
21f40 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
21f50 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 ctions}.**.** Th
21f60 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e ese two function
21f70 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 s (collectively
21f80 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 known as "functi
21f90 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 on creation rout
21fa0 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 ines").** are us
21fb0 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 ed to add SQL fu
21fc0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 nctions or aggre
21fd0 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 gates or to rede
21fe0 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f fine the behavio
21ff0 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 r.** of existing
22000 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f SQL functions o
22010 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 r aggregates. T
22020 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e he only differen
22030 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a ce between the.*
22040 2a 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 * two is that th
22050 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
22060 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 er, the name of
22070 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e the (scalar) fun
22080 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
22090 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 egate, is encode
220a0 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 d in UTF-8 for s
220b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
220c0 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 nction() and UTF
220d0 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 -16.** for sqlit
220e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
220f0 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 on16()..**.** Th
22100 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
22110 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 r is the [databa
22120 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
22130 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a o which the SQL.
22140 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 ** function is t
22150 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 o be added. If
22160 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d a single program
22170 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 uses more than
22180 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 one database.**
22190 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 connection inter
221a0 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 nally, then SQL
221b0 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 functions must b
221c0 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 e added individu
221d0 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 ally to.** each
221e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
221f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ion..**.** The s
22200 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
22210 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
22220 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
22230 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 to be created or
22240 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 .** redefined.
22250 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 The length of th
22260 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 e name is limite
22270 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 d to 255 bytes,
22280 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 exclusive of.**
22290 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 the zero-termina
222a0 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 tor. Note that
222b0 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 the name length
222c0 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 limit is in byte
222d0 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 s, not.** charac
222e0 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d ters. Any attem
222f0 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 pt to create a f
22300 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c unction with a l
22310 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 onger name.** wi
22320 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 ll result in [SQ
22330 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e LITE_ERROR] bein
22340 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a g returned..**.*
22350 2a 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 * The third para
22360 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 meter (nArg).**
22370 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
22380 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 arguments that
22390 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
223a0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
223b0 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 takes. If this
223c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 parameter is neg
223d0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 ative, then the
223e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
223f0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 ** aggregate may
22400 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 take any number
22410 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a of arguments..*
22420 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 *.** The fourth
22430 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 parameter, eText
22440 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 Rep, specifies w
22450 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 hat.** [SQLITE_U
22460 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 TF8 | text encod
22470 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 ing] this SQL fu
22480 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 nction prefers f
22490 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 or.** its parame
224a0 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 ters. Any SQL f
224b0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
224c0 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 tation should be
224d0 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a able to work.**
224e0 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 work with UTF-8
224f0 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 , UTF-16le, or U
22500 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f TF-16be. But so
22510 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f me implementatio
22520 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 ns may be.** mor
22530 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 e efficient with
22540 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 one encoding th
22550 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 an another. It
22560 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a is allowed to.**
22570 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
22580 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
22590 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 ) or sqlite3_cre
225a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
225b0 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d multiple.** tim
225c0 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 es with the same
225d0 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 function but wi
225e0 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c th different val
225f0 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e ues of eTextRep.
22600 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c .** When multipl
22610 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
22620 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 s of the same fu
22630 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c nction are avail
22640 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 able, SQLite.**
22650 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e will pick the on
22660 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 e that involves
22670 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 the least amount
22680 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 of data convers
22690 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 ion..** If there
226a0 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c is only a singl
226b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
226c0 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 which does not
226d0 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a care what text.*
226e0 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 * encoding is us
226f0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 ed, then the fou
22700 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f rth argument sho
22710 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 uld be [SQLITE_A
22720 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 NY]..**.** The f
22730 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 ifth parameter i
22740 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 s an arbitrary p
22750 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 ointer. The imp
22760 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
22770 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 he.** function c
22780 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 an gain access t
22790 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 o this pointer u
227a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 sing [sqlite3_us
227b0 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a er_data()]..**.*
227c0 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 * The seventh, e
227d0 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 ighth and ninth
227e0 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e parameters, xFun
227f0 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 c, xStep and xFi
22800 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e nal, are.** poin
22810 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 ters to C-langua
22820 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 ge functions tha
22830 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 t implement the
22840 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
22850 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 ** aggregate. A
22860 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 scalar SQL funct
22870 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 ion requires an
22880 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
22890 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 f the xFunc.** c
228a0 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 allback only, NU
228b0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 LL pointers shou
228c0 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20 ld be passed as
228d0 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 the xStep and xF
228e0 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 inal.** paramete
228f0 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 rs. An aggregate
22900 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 SQL function re
22910 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d quires an implem
22920 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 entation of xSte
22930 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 p.** and xFinal
22940 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 and NULL should
22950 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 be passed for xF
22960 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 unc. To delete a
22970 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 n existing.** SQ
22980 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 L function or ag
22990 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 gregate, pass NU
229a0 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 LL for all three
229b0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 function callba
229c0 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 cks..**.** It is
229d0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 permitted to re
229e0 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 gister multiple
229f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
22a00 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 of the same.** f
22a10 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 unctions with th
22a20 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 e same name but
22a30 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 with either diff
22a40 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 ering numbers of
22a50 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 .** arguments or
22a60 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 differing prefe
22a70 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 rred text encodi
22a80 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c ngs. SQLite wil
22a90 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 l use.** the imp
22aa0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 lementation most
22ab0 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 closely matches
22ac0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 the way in whic
22ad0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e h the.** SQL fun
22ae0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 ction is used.
22af0 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 A function imple
22b00 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 mentation with a
22b10 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a non-negative.**
22b20 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 nArg parameter
22b30 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 is a better matc
22b40 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f h than a functio
22b50 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
22b60 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 with.** a negat
22b70 69 76 65 20 6e 41 72 67 2e 20 20 41 20 66 75 6e ive nArg. A fun
22b80 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 ction where the
22b90 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 preferred text e
22ba0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 ncoding.** match
22bb0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
22bc0 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 encoding is a be
22bd0 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 tter.** match th
22be0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 an a function wh
22bf0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 ere the encoding
22c00 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 is different.
22c10 0a 2a 2a 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 .** A function w
22c20 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e here the encodin
22c30 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 g difference is
22c40 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 between UTF16le
22c50 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 and UTF16be.** i
22c60 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 s a closer match
22c70 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e than a function
22c80 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 where the encod
22c90 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 ing difference i
22ca0 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 s.** between UTF
22cb0 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 8 and UTF16..**.
22cc0 2a 2a 20 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 ** Built-in func
22cd0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 tions may be ove
22ce0 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 rloaded by new a
22cf0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
22d00 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a ed functions..**
22d10 20 54 68 65 20 66 69 72 73 74 20 61 70 70 6c 69 The first appli
22d20 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
22d30 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 67 unction with a g
22d40 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72 69 iven name overri
22d50 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 des all.** built
22d60 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e -in functions in
22d70 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 the same [datab
22d80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
22d90 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 with the same na
22da0 6d 65 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e me..** Subsequen
22db0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 t application-de
22dc0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 fined functions
22dd0 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 of the same name
22de0 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65 20 0a only override .
22df0 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69 63 61 ** prior applica
22e00 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
22e10 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 ctions that are
22e20 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68 20 66 an exact match f
22e30 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 or the.** number
22e40 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 61 of parameters a
22e50 6e 64 20 70 72 65 66 65 72 72 65 64 20 65 6e 63 nd preferred enc
22e60 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 oding..**.** An
22e70 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
22e80 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ned function is
22e90 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c permitted to cal
22ea0 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 l other.** SQLit
22eb0 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 e interfaces. H
22ec0 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c owever, such cal
22ed0 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 ls must not.** c
22ee0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 lose the databas
22ef0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 e connection nor
22f00 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 finalize or res
22f10 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a et the prepared.
22f20 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 ** statement in
22f30 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 which the functi
22f40 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a on is running..*
22f50 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
22f60 73 3a 0a 2a 2a 20 5b 48 31 36 31 30 33 5d 20 5b s:.** [H16103] [
22f70 48 31 36 31 30 36 5d 20 5b 48 31 36 31 30 39 5d H16106] [H16109]
22f80 20 5b 48 31 36 31 31 32 5d 20 5b 48 31 36 31 31 [H16112] [H1611
22f90 38 5d 20 5b 48 31 36 31 32 31 5d 20 5b 48 31 36 8] [H16121] [H16
22fa0 31 32 34 5d 20 5b 48 31 36 31 32 37 5d 0a 2a 2a 124] [H16127].**
22fb0 20 5b 48 31 36 31 33 30 5d 20 5b 48 31 36 31 33 [H16130] [H1613
22fc0 33 5d 20 5b 48 31 36 31 33 36 5d 20 5b 48 31 36 3] [H16136] [H16
22fd0 31 33 39 5d 20 5b 48 31 36 31 34 32 5d 0a 2a 2f 139] [H16142].*/
22fe0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
22ff0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 ate_function(.
23000 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
23010 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 onst char *zFunc
23020 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 tionName,. int
23030 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 nArg,. int eTex
23040 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 tRep,. void *pA
23050 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 pp,. void (*xFu
23060 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
23070 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
23080 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
23090 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
230a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
230b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
230c0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
230d0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
230e0 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 xt*).);.int sqli
230f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
23100 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 ion16(. sqlite3
23110 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f *db,. const vo
23120 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d id *zFunctionNam
23130 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 e,. int nArg,.
23140 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 int eTextRep,.
23150 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 void *pApp,. v
23160 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c oid (*xFunc)(sql
23170 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
23180 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
23190 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 *),. void (*xSt
231a0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ep)(sqlite3_cont
231b0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
231c0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
231d0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 d (*xFinal)(sqli
231e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b te3_context*).);
231f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
23200 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 : Text Encodings
23210 20 7b 48 31 30 32 36 37 7d 20 3c 53 35 30 32 30 {H10267} <S5020
23220 30 3e 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 0> <H16100>.**.*
23230 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
23240 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 define integer
23250 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 codes that repre
23260 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 sent the various
23270 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e .** text encodin
23280 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 gs supported by
23290 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 SQLite..*/.#defi
232a0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 ne SQLITE_UTF8
232b0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 1.#defi
232c0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c ne SQLITE_UTF16L
232d0 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 E 2.#defi
232e0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 ne SQLITE_UTF16B
232f0 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 E 3.#defi
23300 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 ne SQLITE_UTF16
23310 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 4 /*
23320 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 Use native byte
23330 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e order */.#defin
23340 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 e SQLITE_ANY
23350 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 5 /*
23360 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
23370 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a unction only */.
23380 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
23390 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 TF16_ALIGNED 8
233a0 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 /* sqlite3_cr
233b0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f eate_collation o
233c0 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 nly */../*.** CA
233d0 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 PI3REF: Deprecat
233e0 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 ed Functions.**
233f0 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a DEPRECATED.**.**
23400 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 These functions
23410 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 are [deprecated
23420 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 ]. In order to
23430 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b maintain.** back
23440 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
23450 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 ity with older c
23460 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 ode, these funct
23470 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a ions continue .*
23480 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 * to be supporte
23490 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 d. However, new
234a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 applications sh
234b0 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 ould avoid.** th
234c0 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 e use of these f
234d0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 unctions. To he
234e0 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f lp encourage peo
234f0 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 ple to avoid.**
23500 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 using these func
23510 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f tions, we are no
23520 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 t going to tell
23530 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f you what they do
23540 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c ..*/.#ifndef SQL
23550 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 ITE_OMIT_DEPRECA
23560 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 TED.SQLITE_DEPRE
23570 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
23580 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 3_aggregate_coun
23590 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
235a0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 t*);.SQLITE_DEPR
235b0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
235c0 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 e3_expired(sqlit
235d0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 e3_stmt*);.SQLIT
235e0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
235f0 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 sqlite3_transfe
23600 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 r_bindings(sqlit
23610 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 e3_stmt*, sqlite
23620 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 3_stmt*);.SQLITE
23630 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 _DEPRECATED int
23640 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 sqlite3_global_r
23650 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 ecover(void);.SQ
23660 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
23670 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 void sqlite3_thr
23680 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 ead_cleanup(void
23690 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 );.SQLITE_DEPREC
236a0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 ATED int sqlite3
236b0 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f _memory_alarm(vo
236c0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 id(*)(void*,sqli
236d0 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 te3_int64,int),v
236e0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
236f0 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 64);.#endif../*.
23700 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 ** CAPI3REF: Obt
23710 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 aining SQL Funct
23720 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 ion Parameter Va
23730 6c 75 65 73 20 7b 48 31 35 31 30 30 7d 20 3c 53 lues {H15100} <S
23740 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20200>.**.** The
23750 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c C-language impl
23760 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 ementation of SQ
23770 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 L functions and
23780 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a aggregates uses.
23790 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 ** this set of i
237a0 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 nterface routine
237b0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 s to access the
237c0 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 parameter values
237d0 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 on.** the funct
237e0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
237f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e ..**.** The xFun
23800 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 c (for scalar fu
23810 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 nctions) or xSte
23820 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 p (for aggregate
23830 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a s) parameters.**
23840 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 to [sqlite3_cre
23850 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 ate_function()]
23860 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 and [sqlite3_cre
23870 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
23880 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c ].** define call
23890 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 backs that imple
238a0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e ment the SQL fun
238b0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 ctions and aggre
238c0 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 gates..** The 4t
238d0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
238e0 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 hese callbacks i
238f0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
23900 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 inters to.** [pr
23910 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
23920 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 value] objects.
23930 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 There is one [s
23940 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
23950 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 ject for.** each
23960 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
23970 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 e SQL function.
23980 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
23990 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 are used to.** e
239a0 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 xtract values fr
239b0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f om the [sqlite3_
239c0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a value] objects..
239d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
239e0 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 ines work only w
239f0 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 ith [protected s
23a00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
23a10 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 jects..** Any at
23a20 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 tempt to use the
23a30 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 se routines on a
23a40 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 n [unprotected s
23a50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
23a60 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 object results
23a70 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 in undefined beh
23a80 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 avior..**.** The
23a90 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b se routines work
23aa0 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 just like the c
23ab0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f orresponding [co
23ac0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 lumn access func
23ad0 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 tions].** except
23ae0 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 that these rou
23af0 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e tines take a sin
23b00 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 gle [protected s
23b10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
23b20 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 ject.** pointer
23b30 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 instead of a [sq
23b40 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 lite3_stmt*] poi
23b50 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 nter and an inte
23b60 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 ger column numbe
23b70 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c r..**.** The sql
23b80 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
23b90 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 6() interface ex
23ba0 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 tracts a UTF-16
23bb0 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 string.** in the
23bc0 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 native byte-ord
23bd0 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d er of the host m
23be0 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 achine. The.**
23bf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
23c00 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c xt16be() and sql
23c10 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
23c20 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 6le() interfaces
23c30 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d .** extract UTF-
23c40 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 16 strings as bi
23c50 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 g-endian and lit
23c60 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 tle-endian respe
23c70 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 ctively..**.** T
23c80 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
23c90 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 _numeric_type()
23ca0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
23cb0 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e ts to apply.** n
23cc0 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 umeric affinity
23cd0 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 to the value. T
23ce0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 his means that a
23cf0 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 n attempt is.**
23d00 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 made to convert
23d10 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 the value to an
23d20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 integer or float
23d30 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a ing point. If.*
23d40 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 * such a convers
23d50 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 ion is possible
23d60 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 without loss of
23d70 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 information (in
23d80 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 other.** words,
23d90 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 if the value is
23da0 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f a string that lo
23db0 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 oks like a numbe
23dc0 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 r).** then the c
23dd0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 onversion is per
23de0 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 formed. Otherwi
23df0 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e se no conversion
23e00 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 occurs..** The
23e10 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 [SQLITE_INTEGER
23e20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 | datatype] afte
23e30 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 r conversion is
23e40 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
23e50 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 Please pay parti
23e60 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 cular attention
23e70 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 to the fact that
23e80 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 the pointer ret
23e90 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 urned.** from [s
23ea0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f qlite3_value_blo
23eb0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 b()], [sqlite3_v
23ec0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 alue_text()], or
23ed0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c .** [sqlite3_val
23ee0 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e ue_text16()] can
23ef0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 be invalidated
23f00 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 by a subsequent
23f10 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
23f20 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
23f30 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
23f40 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b ue_bytes16()], [
23f50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
23f60 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 xt()],.** or [sq
23f70 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
23f80 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 16()]..**.** The
23f90 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 se routines must
23fa0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
23fb0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
23fc0 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 as.** the SQL fu
23fd0 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 nction that supp
23fe0 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 lied the [sqlite
23ff0 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 3_value*] parame
24000 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 ters..**.** Requ
24010 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
24020 35 31 30 33 5d 20 5b 48 31 35 31 30 36 5d 20 5b 5103] [H15106] [
24030 48 31 35 31 30 39 5d 20 5b 48 31 35 31 31 32 5d H15109] [H15112]
24040 20 5b 48 31 35 31 31 35 5d 20 5b 48 31 35 31 31 [H15115] [H1511
24050 38 5d 20 5b 48 31 35 31 32 31 5d 20 5b 48 31 35 8] [H15121] [H15
24060 31 32 34 5d 0a 2a 2a 20 5b 48 31 35 31 32 37 5d 124].** [H15127]
24070 20 5b 48 31 35 31 33 30 5d 20 5b 48 31 35 31 33 [H15130] [H1513
24080 33 5d 20 5b 48 31 35 31 33 36 5d 0a 2a 2f 0a 63 3] [H15136].*/.c
24090 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
240a0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 e3_value_blob(sq
240b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
240c0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
240d0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 _bytes(sqlite3_v
240e0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 alue*);.int sqli
240f0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 te3_value_bytes1
24100 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 6(sqlite3_value*
24110 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 );.double sqlite
24120 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 3_value_double(s
24130 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
24140 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
24150 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 e_int(sqlite3_va
24160 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 lue*);.sqlite3_i
24170 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c nt64 sqlite3_val
24180 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 ue_int64(sqlite3
24190 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 _value*);.const
241a0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 unsigned char *s
241b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
241c0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t(sqlite3_value*
241d0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
241e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
241f0 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 t16(sqlite3_valu
24200 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 e*);.const void
24210 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
24220 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f ext16le(sqlite3_
24230 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 value*);.const v
24240 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c oid *sqlite3_val
24250 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 ue_text16be(sqli
24260 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
24270 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
24280 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ype(sqlite3_valu
24290 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
242a0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 _value_numeric_t
242b0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ype(sqlite3_valu
242c0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 e*);../*.** CAPI
242d0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 3REF: Obtain Agg
242e0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 regate Function
242f0 43 6f 6e 74 65 78 74 20 7b 48 31 36 32 31 30 7d Context {H16210}
24300 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20200>.**.**
24310 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 The implementati
24320 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 on of aggregate
24330 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 SQL functions us
24340 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 e this routine t
24350 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 o allocate.** a
24360 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 74 structure for st
24370 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 oring their stat
24380 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 e..**.** The fir
24390 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 st time the sqli
243a0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
243b0 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20 ntext() routine
243c0 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a is called for a.
243d0 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 ** particular ag
243e0 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20 gregate, SQLite
243f0 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73 allocates nBytes
24400 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f of memory, zero
24410 65 73 20 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d es out that.** m
24420 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 emory, and retur
24430 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
24440 69 74 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e it. On second an
24450 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c d subsequent cal
24460 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ls to.** sqlite3
24470 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
24480 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d xt() for the sam
24490 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 e aggregate func
244a0 74 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 tion index,.** t
244b0 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 he same buffer i
244c0 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65 20 s returned. The
244d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
244e0 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 f the aggregate
244f0 63 61 6e 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 can use.** the r
24500 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 eturned buffer t
24510 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 o accumulate dat
24520 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 a..**.** SQLite
24530 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 automatically fr
24540 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 ees the allocate
24550 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 74 68 d buffer when th
24560 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 e aggregate.** q
24570 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a uery concludes..
24580 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
24590 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 parameter should
245a0 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 be a copy of th
245b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f e.** [sqlite3_co
245c0 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 ntext | SQL func
245d0 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 tion context] th
245e0 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 at is the first
245f0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 parameter.** to
24600 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 the callback rou
24610 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d tine that implem
24620 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 ents the aggrega
24630 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a te function..**.
24640 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
24650 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
24660 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
24670 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 ead in which.**
24680 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 the aggregate SQ
24690 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 L function is ru
246a0 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 nning..**.** Req
246b0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
246c0 31 36 32 31 31 5d 20 5b 48 31 36 32 31 33 5d 20 16211] [H16213]
246d0 5b 48 31 36 32 31 35 5d 20 5b 48 31 36 32 31 37 [H16215] [H16217
246e0 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ].*/.void *sqlit
246f0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
24700 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e text(sqlite3_con
24710 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 text*, int nByte
24720 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 s);../*.** CAPI3
24730 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 REF: User Data F
24740 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 or Functions {H1
24750 36 32 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 6240} <S20200>.*
24760 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
24770 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 _user_data() int
24780 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
24790 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
247a0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 pointer that was
247b0 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 the pUserData p
247c0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 arameter (the 5t
247d0 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 h parameter).**
247e0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
247f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
24800 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 )].** and [sqlit
24810 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
24820 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 on16()] routines
24830 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 that originally
24840 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 .** registered t
24850 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
24860 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
24870 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 {END}.**.** Thi
24880 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 s routine must b
24890 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
248a0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e e same thread in
248b0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 which.** the ap
248c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
248d0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 d function is ru
248e0 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 nning..**.** Req
248f0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
24900 31 36 32 34 33 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 16243].*/.void *
24910 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
24920 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
24930 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
24940 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 3REF: Database C
24950 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 onnection For Fu
24960 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d nctions {H16250}
24970 20 3c 53 36 30 36 30 30 3e 3c 53 32 30 32 30 30 <S60600><S20200
24980 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
24990 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 te3_context_db_h
249a0 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 andle() interfac
249b0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 e returns a copy
249c0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 of.** the point
249d0 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 er to the [datab
249e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
249f0 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 (the 1st paramet
24a00 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 er).** of the [s
24a10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
24a20 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 nction()].** and
24a30 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
24a40 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 _function16()] r
24a50 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 outines that ori
24a60 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 ginally.** regis
24a70 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 tered the applic
24a80 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 ation defined fu
24a90 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 nction..**.** Re
24aa0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
24ab0 48 31 36 32 35 33 5d 0a 2a 2f 0a 73 71 6c 69 74 H16253].*/.sqlit
24ac0 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 e3 *sqlite3_cont
24ad0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 ext_db_handle(sq
24ae0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
24af0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
24b00 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c : Function Auxil
24b10 69 61 72 79 20 44 61 74 61 20 7b 48 31 36 32 37 iary Data {H1627
24b20 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 0} <S20200>.**.*
24b30 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 * The following
24b40 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 two functions ma
24b50 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 y be used by sca
24b60 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e lar SQL function
24b70 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 s to.** associat
24b80 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 e metadata with
24b90 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e argument values.
24ba0 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c If the same val
24bb0 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a ue is passed to.
24bc0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f ** multiple invo
24bd0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 cations of the s
24be0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ame SQL function
24bf0 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 during query ex
24c00 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a ecution, under.*
24c10 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 * some circumsta
24c20 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 nces the associa
24c30 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 ted metadata may
24c40 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 be preserved. T
24c50 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 his may.** be us
24c60 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c ed, for example,
24c70 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 to add a regula
24c80 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 r-expression mat
24c90 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 ching scalar.**
24ca0 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f function. The co
24cb0 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f mpiled version o
24cc0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 f the regular ex
24cd0 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 pression is stor
24ce0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 ed as.** metadat
24cf0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 a associated wit
24d00 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 h the SQL value
24d10 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 passed as the re
24d20 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e gular expression
24d30 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 .** pattern. Th
24d40 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c e compiled regul
24d50 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 ar expression ca
24d60 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d n be reused on m
24d70 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 ultiple.** invoc
24d80 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
24d90 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 me function so t
24da0 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c hat the original
24db0 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a pattern string.
24dc0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 ** does not need
24dd0 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 to be recompile
24de0 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 d on each invoca
24df0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tion..**.** The
24e00 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
24e10 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
24e20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
24e30 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 r to the metadat
24e40 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 a.** associated
24e50 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 by the sqlite3_s
24e60 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e et_auxdata() fun
24e70 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e ction with the N
24e80 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 th argument.** v
24e90 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c alue to the appl
24ea0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
24eb0 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 function. If no
24ec0 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 metadata has bee
24ed0 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 n ever.** been s
24ee0 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 et for the Nth a
24ef0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 rgument of the f
24f00 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 unction, or if t
24f10 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
24f20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 .** function par
24f30 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 ameter has chang
24f40 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 ed since the met
24f50 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a a-data was set,.
24f60 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ** then sqlite3_
24f70 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 get_auxdata() re
24f80 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
24f90 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nter..**.** The
24fa0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
24fb0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
24fc0 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 saves the metada
24fd0 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f ta.** pointed to
24fe0 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 by its 3rd para
24ff0 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 meter as the met
25000 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d adata for the N-
25010 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f th.** argument o
25020 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
25030 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
25040 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a on. Subsequent.
25050 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ** calls to sqli
25060 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
25070 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 ) might return t
25080 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 his data, if it
25090 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 has.** not been
250a0 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 destroyed..** If
250b0 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c it is not NULL,
250c0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 SQLite will inv
250d0 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 oke the destruct
250e0 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 or.** function g
250f0 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 iven by the 4th
25100 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
25110 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
25120 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 () on.** the met
25130 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 adata when the c
25140 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e orresponding fun
25150 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 ction parameter
25160 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 changes.** or wh
25170 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 en the SQL state
25180 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 ment completes,
25190 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 whichever comes
251a0 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c first..**.** SQL
251b0 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 ite is free to c
251c0 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 all the destruct
251d0 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 or and drop meta
251e0 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 data on any.** p
251f0 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 arameter of any
25200 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 function at any
25210 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 time. The only
25220 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 guarantee is tha
25230 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 t.** the destruc
25240 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c tor will be call
25250 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 ed before the me
25260 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 tadata is droppe
25270 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 d..**.** In prac
25280 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 tice, metadata i
25290 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 s preserved betw
252a0 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c een function cal
252b0 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 ls for.** expres
252c0 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 sions that are c
252d0 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 onstant at compi
252e0 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e le time. This in
252f0 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a cludes literal.*
25300 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c * values and SQL
25310 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a variables..**.*
25320 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
25330 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
25340 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
25350 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a read in which.**
25360 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
25370 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a n is running..**
25380 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
25390 3a 0a 2a 2a 20 5b 48 31 36 32 37 32 5d 20 5b 48 :.** [H16272] [H
253a0 31 36 32 37 34 5d 20 5b 48 31 36 32 37 36 5d 20 16274] [H16276]
253b0 5b 48 31 36 32 37 37 5d 20 5b 48 31 36 32 37 38 [H16277] [H16278
253c0 5d 20 5b 48 31 36 32 37 39 5d 0a 2a 2f 0a 76 6f ] [H16279].*/.vo
253d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f id *sqlite3_get_
253e0 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f auxdata(sqlite3_
253f0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 context*, int N)
25400 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 ;.void sqlite3_s
25410 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 et_auxdata(sqlit
25420 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
25430 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 N, void*, void
25440 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f (*)(void*));.../
25450 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
25460 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e onstants Definin
25470 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 g Special Destru
25480 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20 7b 48 ctor Behavior {H
25490 31 30 32 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a 10280} <S30100>.
254a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 **.** These are
254b0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 special values f
254c0 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f or the destructo
254d0 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 r that is passed
254e0 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 in as the.** fi
254f0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 nal argument to
25500 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 routines like [s
25510 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
25520 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 ob()]. If the d
25530 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 estructor.** arg
25540 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f ument is SQLITE_
25550 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 STATIC, it means
25560 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e that the conten
25570 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e t pointer is con
25580 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c stant.** and wil
25590 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 l never change.
255a0 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 It does not nee
255b0 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 d to be destroye
255c0 64 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 d. The.** SQLIT
255d0 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 E_TRANSIENT valu
255e0 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 e means that the
255f0 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 content will li
25600 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a kely change in.*
25610 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 * the near futur
25620 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 e and that SQLit
25630 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 e should make it
25640 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f s own private co
25650 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e py of.** the con
25660 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 tent before retu
25670 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 rning..**.** The
25680 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 typedef is nece
25690 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 ssary to work ar
256a0 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e ound problems in
256b0 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 certain.** C++
256c0 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 compilers. See
256d0 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f ticket #2191..*/
256e0 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a .typedef void (*
256f0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
25700 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b or_type)(void*);
25710 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
25720 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 STATIC ((sq
25730 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 lite3_destructor
25740 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 _type)0).#define
25750 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e SQLITE_TRANSIEN
25760 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 T ((sqlite3_de
25770 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 structor_type)-1
25780 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 )../*.** CAPI3RE
25790 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 F: Setting The R
257a0 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 esult Of An SQL
257b0 46 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34 30 30 Function {H16400
257c0 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a } <S20200>.**.**
257d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
257e0 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 are used by the
257f0 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 xFunc or xFinal
25800 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a callbacks that.*
25810 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 * implement SQL
25820 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 functions and ag
25830 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a gregates. See.*
25840 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 * [sqlite3_creat
25850 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e e_function()] an
25860 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
25870 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a e_function16()].
25880 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 ** for additiona
25890 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
258a0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
258b0 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d ions work very m
258c0 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 uch like the [pa
258d0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d rameter binding]
258e0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 family of.** fu
258f0 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 nctions used to
25900 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 bind values to h
25910 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 ost parameters i
25920 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 n prepared state
25930 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 ments..** Refer
25940 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 to the [SQL para
25950 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 meter] documenta
25960 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f tion for additio
25970 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
25980 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
25990 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 e3_result_blob()
259a0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
259b0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a the result from.
259c0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f ** an applicatio
259d0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
259e0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f on to be the BLO
259f0 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 B whose content
25a00 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f is pointed.** to
25a10 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 by the second p
25a20 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 arameter and whi
25a30 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f ch is N bytes lo
25a40 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 ng where N is th
25a50 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d e.** third param
25a60 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eter..**.** The
25a70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a sqlite3_result_z
25a80 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 eroblob() interf
25a90 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 aces set the res
25aa0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 ult of.** the ap
25ab0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
25ac0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
25ad0 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 a BLOB containi
25ae0 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 ng all zero.** b
25af0 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 ytes and N bytes
25b00 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 in size, where
25b10 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f N is the value o
25b20 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 f the 2nd parame
25b30 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ter..**.** The s
25b40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f qlite3_result_do
25b50 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 uble() interface
25b60 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 sets the result
25b70 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c from.** an appl
25b80 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
25b90 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
25ba0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
25bb0 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a value specified.
25bc0 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 ** by its 2nd ar
25bd0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 gument..**.** Th
25be0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
25bf0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c _error() and sql
25c00 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
25c10 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a r16() functions.
25c20 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 ** cause the imp
25c30 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e lemented SQL fun
25c40 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 ction to throw a
25c50 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 n exception..**
25c60 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 SQLite uses the
25c70 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 string pointed t
25c80 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 o by the.** 2nd
25c90 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c parameter of sql
25ca0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
25cb0 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 r() or sqlite3_r
25cc0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a esult_error16().
25cd0 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f ** as the text o
25ce0 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 f an error messa
25cf0 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65 ge. SQLite inte
25d00 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 rprets the error
25d10 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 .** message stri
25d20 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ng from sqlite3_
25d30 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 result_error() a
25d40 73 20 55 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a s UTF-8. SQLite.
25d50 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 ** interprets th
25d60 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 e string from sq
25d70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
25d80 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 or16() as UTF-16
25d90 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 in native.** by
25da0 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68 te order. If th
25db0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
25dc0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 r to sqlite3_res
25dd0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f ult_error().** o
25de0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
25df0 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 _error16() is ne
25e00 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 gative then SQLi
25e10 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 te takes as the
25e20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 error.** message
25e30 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 all text up thr
25e40 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a ough the first z
25e50 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a ero character..*
25e60 2a 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 * If the third p
25e70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
25e80 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
25e90 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 () or.** sqlite3
25ea0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
25eb0 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 ) is non-negativ
25ec0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 e then SQLite ta
25ed0 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a kes that many.**
25ee0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 bytes (not char
25ef0 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 acters) from the
25f00 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 2nd parameter a
25f10 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 s the error mess
25f20 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 age..** The sqli
25f30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
25f40 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 () and sqlite3_r
25f50 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a esult_error16().
25f60 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 ** routines make
25f70 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 a private copy
25f80 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 of the error mes
25f90 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 sage text before
25fa0 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e .** they return.
25fb0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c Hence, the cal
25fc0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 ling function ca
25fd0 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a n deallocate or.
25fe0 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 ** modify the te
25ff0 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 xt after they re
26000 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 turn without har
26010 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 m..** The sqlite
26020 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 3_result_error_c
26030 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 ode() function c
26040 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 hanges the error
26050 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 code.** returne
26060 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 d by SQLite as a
26070 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 result of an er
26080 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f ror in a functio
26090 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a n. By default,.
260a0 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 ** the error cod
260b0 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f e is SQLITE_ERRO
260c0 52 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e 74 R. A subsequent
260d0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
260e0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a _result_error().
260f0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ** or sqlite3_re
26100 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 sult_error16() r
26110 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 esets the error
26120 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 code to SQLITE_E
26130 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 RROR..**.** The
26140 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
26150 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 oobig() interfac
26160 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 e causes SQLite
26170 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f to throw an erro
26180 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 r.** indicating
26190 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 that a string or
261a0 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 BLOB is to long
261b0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a to represent..*
261c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
261d0 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 _result_nomem()
261e0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 interface causes
261f0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 SQLite to throw
26200 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 an error.** ind
26210 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d icating that a m
26220 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
26230 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 failed..**.** T
26240 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
26250 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 t_int() interfac
26260 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 e sets the retur
26270 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 n value.** of th
26280 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
26290 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
262a0 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 o be the 32-bit
262b0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a signed integer.*
262c0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e * value given in
262d0 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e the 2nd argumen
262e0 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 t..** The sqlite
262f0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 3_result_int64()
26300 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
26310 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
26320 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 .** of the appli
26330 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
26340 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 unction to be th
26350 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 e 64-bit signed
26360 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 integer.** value
26370 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e given in the 2n
26380 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a d argument..**.*
26390 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
263a0 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 sult_null() inte
263b0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
263c0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f eturn value.** o
263d0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
263e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
263f0 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a on to be NULL..*
26400 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
26410 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 _result_text(),
26420 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
26430 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 ext16(),.** sqli
26440 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
26450 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 6le(), and sqlit
26460 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
26470 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a be() interfaces.
26480 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 ** set the retur
26490 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 n value of the a
264a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
264b0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
264c0 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 e.** a text stri
264d0 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 ng which is repr
264e0 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 esented as UTF-8
264f0 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 , UTF-16 native
26500 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 byte order,.** U
26510 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 TF-16 little end
26520 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 ian, or UTF-16 b
26530 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 ig endian, respe
26540 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 ctively..** SQLi
26550 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 te takes the tex
26560 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 t result from th
26570 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 e application fr
26580 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 om.** the 2nd pa
26590 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 rameter of the s
265a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
265b0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a xt* interfaces..
265c0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 ** If the 3rd pa
265d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
265e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
265f0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a xt* interfaces.*
26600 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 * is negative, t
26610 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 hen SQLite takes
26620 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f result text fro
26630 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 m the 2nd parame
26640 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 ter.** through t
26650 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 he first zero ch
26660 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 aracter..** If t
26670 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 he 3rd parameter
26680 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
26690 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
266a0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f erfaces.** is no
266b0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e n-negative, then
266c0 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 as many bytes (
266d0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 not characters)
266e0 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 of the text.** p
266f0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 ointed to by the
26700 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 2nd parameter a
26710 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 re taken as the
26720 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
26730 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ned.** function
26740 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 result..** If th
26750 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
26760 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
26770 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
26780 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c rfaces.** or sql
26790 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
267a0 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 is a non-NULL p
267b0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c ointer, then SQL
267c0 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a ite calls that.*
267d0 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 * function as th
267e0 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 e destructor on
267f0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 the text or BLOB
26800 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 result when it
26810 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 has.** finished
26820 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c using that resul
26830 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 t..** If the 4th
26840 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
26850 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
26860 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
26870 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f s or.** sqlite3_
26880 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 result_blob is t
26890 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 he special const
268a0 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 ant SQLITE_STATI
268b0 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a C, then SQLite.*
268c0 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 * assumes that t
268d0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 he text or BLOB
268e0 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e result is in con
268f0 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 stant space and
26900 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 does not.** copy
26910 20 74 68 65 20 69 74 20 6f 72 20 63 61 6c 6c 20 the it or call
26920 61 20 64 65 73 74 72 75 63 74 6f 72 20 77 68 65 a destructor whe
26930 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 n it has finishe
26940 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 d using that res
26950 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 ult..** If the 4
26960 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
26970 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
26980 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
26990 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 ces.** or sqlite
269a0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 3_result_blob is
269b0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e the special con
269c0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 stant SQLITE_TRA
269d0 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 NSIENT.** then S
269e0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f QLite makes a co
269f0 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 py of the result
26a00 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 into space obta
26a10 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f ined from.** fro
26a20 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
26a30 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 c()] before it r
26a40 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 eturns..**.** Th
26a50 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
26a60 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 _value() interfa
26a70 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 ce sets the resu
26a80 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 lt of.** the app
26a90 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
26aa0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
26ab0 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 a copy the.** [u
26ac0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
26ad0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
26ae0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
26af0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e e 2nd parameter.
26b00 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 The.** sqlite3
26b10 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
26b20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 interface makes
26b30 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 a copy of the [s
26b40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
26b50 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 so that the [sq
26b60 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 lite3_value] spe
26b70 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 cified in the pa
26b80 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e rameter may chan
26b90 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c ge or.** be deal
26ba0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 located after sq
26bb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
26bc0 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 ue() returns wit
26bd0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 hout harm..** A
26be0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
26bf0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
26c00 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 may always be u
26c10 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 sed where an.**
26c20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
26c30 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
26c40 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 ct is required,
26c50 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e so either.** kin
26c60 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 d of [sqlite3_va
26c70 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 lue] object can
26c80 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 be used with thi
26c90 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a s interface..**.
26ca0 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 ** If these rout
26cb0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
26cc0 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 from within the
26cd0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
26ce0 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 .** than the one
26cf0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
26d00 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
26d10 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 ned function tha
26d20 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 t received.** th
26d30 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 e [sqlite3_conte
26d40 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 xt] pointer, the
26d50 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
26d60 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 efined..**.** Re
26d70 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
26d80 48 31 36 34 30 33 5d 20 5b 48 31 36 34 30 36 5d H16403] [H16406]
26d90 20 5b 48 31 36 34 30 39 5d 20 5b 48 31 36 34 31 [H16409] [H1641
26da0 32 5d 20 5b 48 31 36 34 31 35 5d 20 5b 48 31 36 2] [H16415] [H16
26db0 34 31 38 5d 20 5b 48 31 36 34 32 31 5d 20 5b 48 418] [H16421] [H
26dc0 31 36 34 32 34 5d 0a 2a 2a 20 5b 48 31 36 34 32 16424].** [H1642
26dd0 37 5d 20 5b 48 31 36 34 33 30 5d 20 5b 48 31 36 7] [H16430] [H16
26de0 34 33 33 5d 20 5b 48 31 36 34 33 36 5d 20 5b 48 433] [H16436] [H
26df0 31 36 34 33 39 5d 20 5b 48 31 36 34 34 32 5d 20 16439] [H16442]
26e00 5b 48 31 36 34 34 35 5d 20 5b 48 31 36 34 34 38 [H16445] [H16448
26e10 5d 0a 2a 2a 20 5b 48 31 36 34 35 31 5d 20 5b 48 ].** [H16451] [H
26e20 31 36 34 35 34 5d 20 5b 48 31 36 34 35 37 5d 20 16454] [H16457]
26e30 5b 48 31 36 34 36 30 5d 20 5b 48 31 36 34 36 33 [H16460] [H16463
26e40 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ].*/.void sqlite
26e50 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 3_result_blob(sq
26e60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
26e70 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
26e80 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
26e90 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
26ea0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 result_double(sq
26eb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
26ec0 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 double);.void sq
26ed0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
26ee0 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 or(sqlite3_conte
26ef0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a xt*, const char*
26f00 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c , int);.void sql
26f10 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
26f20 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 r16(sqlite3_cont
26f30 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ext*, const void
26f40 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 *, int);.void sq
26f50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
26f60 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 or_toobig(sqlite
26f70 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 3_context*);.voi
26f80 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
26f90 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c _error_nomem(sql
26fa0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
26fb0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
26fc0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 ult_error_code(s
26fd0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
26fe0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 int);.void sqli
26ff0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 te3_result_int(s
27000 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
27010 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 int);.void sqli
27020 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 te3_result_int64
27030 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
27040 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
27050 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
27060 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 result_null(sqli
27070 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 te3_context*);.v
27080 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
27090 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f lt_text(sqlite3_
270a0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
270b0 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 char*, int, void
270c0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
270d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
270e0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f _text16(sqlite3_
270f0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
27100 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 void*, int, void
27110 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
27120 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
27130 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 _text16le(sqlite
27140 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
27150 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 t void*, int,voi
27160 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f d(*)(void*));.vo
27170 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
27180 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 t_text16be(sqlit
27190 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
271a0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f st void*, int,vo
271b0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 id(*)(void*));.v
271c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
271d0 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 lt_value(sqlite3
271e0 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 _context*, sqlit
271f0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 e3_value*);.void
27200 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
27210 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 zeroblob(sqlite3
27220 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e _context*, int n
27230 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
27240 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 EF: Define New C
27250 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 ollating Sequenc
27260 65 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 es {H16600} <S20
27270 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 300>.**.** These
27280 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 functions are u
27290 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 sed to add new c
272a0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
272b0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 es to the.** [da
272c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
272d0 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 n] specified as
272e0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
272f0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 nt..**.** The na
27300 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f me of the new co
27310 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
27320 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73 is specified as
27330 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a a UTF-8 string.
27340 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 ** for sqlite3_c
27350 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 reate_collation(
27360 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 ) and sqlite3_cr
27370 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
27380 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2().** and a UTF
27390 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 -16 string for s
273a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
273b0 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 llation16(). In
273c0 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 all cases.** the
273d0 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 name is passed
273e0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 as the second fu
273f0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e nction argument.
27400 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 .**.** The third
27410 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 argument may be
27420 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 one of the cons
27430 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 tants [SQLITE_UT
27440 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f F8],.** [SQLITE_
27450 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c UTF16LE] or [SQL
27460 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e ITE_UTF16BE], in
27470 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 dicating that th
27480 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a e user-supplied.
27490 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 ** routine expec
274a0 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 ts to be passed
274b0 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 pointers to stri
274c0 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e ngs encoded usin
274d0 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d g UTF-8,.** UTF-
274e0 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 16 little-endian
274f0 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d , or UTF-16 big-
27500 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 endian, respecti
27510 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 vely. The.** thi
27520 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 rd argument migh
27530 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 t also be [SQLIT
27540 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d E_UTF16_ALIGNED]
27550 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
27560 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 t.** the routine
27570 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 expects pointer
27580 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 s to 16-bit word
27590 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 aligned strings
275a0 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e .** of UTF-16 in
275b0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
275c0 20 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f order of the ho
275d0 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a st computer..**.
275e0 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** A pointer to
275f0 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 the user supplie
27600 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 d routine must b
27610 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
27620 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e fifth.** argumen
27630 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c t. If it is NUL
27640 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73 L, this is the s
27650 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 ame as deleting
27660 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a the collation.**
27670 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 sequence (so th
27680 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 at SQLite cannot
27690 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 call it anymore
276a0 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 )..** Each time
276b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
276c0 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f supplied functio
276d0 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 n is invoked, it
276e0 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 is passed.** as
276f0 20 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d its first param
27700 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74 eter a copy of t
27710 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 he void* passed
27720 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 as the fourth ar
27730 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c gument.** to sql
27740 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
27750 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 ation() or sqlit
27760 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
27770 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 ion16()..**.** T
27780 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 he remaining arg
27790 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 uments to the ap
277a0 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 plication-suppli
277b0 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 ed routine are t
277c0 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 wo strings,.** e
277d0 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 ach represented
277e0 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 by a (length, da
277f0 74 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 ta) pair and enc
27800 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f oded in the enco
27810 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 ding.** that was
27820 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 passed as the t
27830 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 hird argument wh
27840 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e en the collation
27850 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a sequence was.**
27860 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e registered. {EN
27870 44 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 D} The applicat
27880 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c ion defined coll
27890 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 ation routine sh
278a0 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e ould.** return n
278b0 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 egative, zero or
278c0 20 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 65 positive if the
278d0 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 first string is
278e0 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 less than,.** e
278f0 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 qual to, or grea
27900 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 ter than the sec
27910 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e ond string. i.e.
27920 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 (STRING1 - STRI
27930 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 NG2)..**.** The
27940 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
27950 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f ollation_v2() wo
27960 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 rks like sqlite3
27970 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
27980 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 n().** except th
27990 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 at it takes an e
279a0 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 xtra argument wh
279b0 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63 ich is a destruc
279c0 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 tor for.** the c
279d0 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 ollation. The d
279e0 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c estructor is cal
279f0 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c led when the col
27a00 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 lation is.** des
27a10 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 troyed and is pa
27a20 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 ssed a copy of t
27a30 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
27a40 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 ter void* pointe
27a50 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 r.** of the sqli
27a60 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
27a70 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f tion_v2()..** Co
27a80 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 llations are des
27a90 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79 troyed when they
27aa0 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 are overridden
27ab0 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 by later calls t
27ac0 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 o the.** collati
27ad0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 on creation func
27ae0 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 tions or when th
27af0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
27b00 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 ection] is close
27b10 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 d.** using [sqli
27b20 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a te3_close()]..**
27b30 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
27b40 3a 0a 2a 2a 20 5b 48 31 36 36 30 33 5d 20 5b 48 :.** [H16603] [H
27b50 31 36 36 30 34 5d 20 5b 48 31 36 36 30 36 5d 20 16604] [H16606]
27b60 5b 48 31 36 36 30 39 5d 20 5b 48 31 36 36 31 32 [H16609] [H16612
27b70 5d 20 5b 48 31 36 36 31 35 5d 20 5b 48 31 36 36 ] [H16615] [H166
27b80 31 38 5d 20 5b 48 31 36 36 32 31 5d 0a 2a 2a 20 18] [H16621].**
27b90 5b 48 31 36 36 32 34 5d 20 5b 48 31 36 36 32 37 [H16624] [H16627
27ba0 5d 20 5b 48 31 36 36 33 30 5d 0a 2a 2f 0a 69 6e ] [H16630].*/.in
27bb0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
27bc0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 _collation(. sq
27bd0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 lite3*, . const
27be0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 char *zName, .
27bf0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a int eTextRep, .
27c00 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a void*,. int(*
27c10 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c xCompare)(void*,
27c20 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c int,const void*,
27c30 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 int,const void*)
27c40 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
27c50 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
27c60 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c _v2(. sqlite3*,
27c70 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a . const char *
27c80 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 zName, . int eT
27c90 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a extRep, . void*
27ca0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 ,. int(*xCompar
27cb0 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e e)(void*,int,con
27cc0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e st void*,int,con
27cd0 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 st void*),. voi
27ce0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 d(*xDestroy)(voi
27cf0 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 d*).);.int sqlit
27d00 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
27d10 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 ion16(. sqlite3
27d20 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 *, . const void
27d30 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 *zName,. int e
27d40 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 TextRep, . void
27d50 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 *,. int(*xCompa
27d60 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f re)(void*,int,co
27d70 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f nst void*,int,co
27d80 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f nst void*).);../
27d90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
27da0 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 ollation Needed
27db0 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 Callbacks {H1670
27dc0 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 0} <S20300>.**.*
27dd0 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e * To avoid havin
27de0 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c g to register al
27df0 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 l collation sequ
27e00 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 ences before a d
27e10 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 atabase.** can b
27e20 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 e used, a single
27e30 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
27e40 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 on may be regist
27e50 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a ered with the.**
27e60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
27e70 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c ction] to be cal
27e80 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 led whenever an
27e90 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 undefined collat
27ea0 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 ion.** sequence
27eb0 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a is required..**.
27ec0 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 69 ** If the functi
27ed0 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 on is registered
27ee0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 using the sqlit
27ef0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
27f00 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 ded() API,.** th
27f10 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 en it is passed
27f20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 the names of und
27f30 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e efined collation
27f40 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 sequences as st
27f50 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 rings.** encoded
27f60 20 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36 37 in UTF-8. {H167
27f70 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 63 03} If sqlite3_c
27f80 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 ollation_needed1
27f90 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 6() is used,.**
27fa0 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 the names are pa
27fb0 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 ssed as UTF-16 i
27fc0 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 n machine native
27fd0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 byte order..**
27fe0 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 A call to either
27ff0 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 function replac
28000 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 es any existing
28010 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 callback..**.**
28020 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 When the callbac
28030 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 k is invoked, th
28040 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
28050 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 passed is a cop
28060 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f y.** of the seco
28070 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 nd argument to s
28080 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
28090 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 _needed() or.**
280a0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
280b0 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 n_needed16(). T
280c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
280d0 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 nt is the databa
280e0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
280f0 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 . The third arg
28100 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 ument is one of
28110 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b [SQLITE_UTF8], [
28120 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c SQLITE_UTF16BE],
28130 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 .** or [SQLITE_U
28140 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 TF16LE], indicat
28150 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 ing the most des
28160 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 irable form of t
28170 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 he collation.**
28180 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f sequence functio
28190 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 n required. The
281a0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
281b0 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 r is the name of
281c0 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 the.** required
281d0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
281e0 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 nce..**.** The c
281f0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
28200 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 should register
28210 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c the desired col
28220 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 lation using.**
28230 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
28240 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 collation()], [s
28250 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
28260 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 llation16()], or
28270 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 .** [sqlite3_cre
28280 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
28290 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ()]..**.** Requi
282a0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 rements:.** [H16
282b0 37 30 32 5d 20 5b 48 31 36 37 30 34 5d 20 5b 48 702] [H16704] [H
282c0 31 36 37 30 36 5d 0a 2a 2f 0a 69 6e 74 20 73 71 16706].*/.int sq
282d0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
282e0 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 needed(. sqlite
282f0 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 3*, . void*, .
28300 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 void(*)(void*,s
28310 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 qlite3*,int eTex
28320 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a tRep,const char*
28330 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ).);.int sqlite3
28340 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 _collation_neede
28350 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c d16(. sqlite3*,
28360 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 . void*,. voi
28370 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 d(*)(void*,sqlit
28380 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 e3*,int eTextRep
28390 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b ,const void*).);
283a0 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 ../*.** Specify
283b0 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 the key for an e
283c0 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 ncrypted databas
283d0 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 e. This routine
283e0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 should be.** ca
283f0 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 lled right after
28400 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e sqlite3_open().
28410 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 .**.** The code
28420 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 to implement thi
28430 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 s API is not ava
28440 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 ilable in the pu
28450 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 blic release.**
28460 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e of SQLite..*/.in
28470 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 t sqlite3_key(.
28480 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
28490 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
284a0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 /* Database to b
284b0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 e rekeyed */. c
284c0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c onst void *pKey,
284d0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a int nKey /*
284e0 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a The key */.);..
284f0 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 /*.** Change the
28500 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 key on an open
28510 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 database. If th
28520 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 e current databa
28530 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 se is not.** enc
28540 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 rypted, this rou
28550 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 tine will encryp
28560 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d t it. If pNew==
28570 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 0 or nNew==0, th
28580 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 e.** database is
28590 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a decrypted..**.*
285a0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d * The code to im
285b0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 plement this API
285c0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c is not availabl
285d0 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 e in the public
285e0 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 release.** of SQ
285f0 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c Lite..*/.int sql
28600 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 ite3_rekey(. sq
28610 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
28620 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
28630 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 Database to be r
28640 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 ekeyed */. cons
28650 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e t void *pKey, in
28660 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 t nKey /* Th
28670 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a e new key */.);.
28680 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
28690 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 Suspend Executi
286a0 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 on For A Short T
286b0 69 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c 53 34 ime {H10530} <S4
286c0 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0410>.**.** The
286d0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 sqlite3_sleep()
286e0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 function causes
286f0 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 the current thre
28700 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 ad to suspend ex
28710 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 ecution.** for a
28720 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 t least a number
28730 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 of milliseconds
28740 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 specified in it
28750 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a s parameter..**.
28760 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 ** If the operat
28770 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 ing system does
28780 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 not support slee
28790 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a p requests with.
287a0 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 ** millisecond t
287b0 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 ime resolution,
287c0 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 then the time wi
287d0 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 ll be rounded up
287e0 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 to.** the neare
287f0 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e st second. The n
28800 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 umber of millise
28810 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 conds of sleep a
28820 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 ctually.** reque
28830 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 sted from the op
28840 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 erating system i
28850 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
28860 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 * SQLite impleme
28870 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 nts this interfa
28880 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 ce by calling th
28890 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 e xSleep().** me
288a0 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 thod of the defa
288b0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
288c0 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 ] object..**.**
288d0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 Requirements: [H
288e0 31 30 35 33 33 5d 20 5b 48 31 30 35 33 36 5d 0a 10533] [H10536].
288f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 */.int sqlite3_s
28900 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a leep(int);../*.*
28910 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 * CAPI3REF: Name
28920 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 Of The Folder H
28930 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 olding Temporary
28940 20 46 69 6c 65 73 20 7b 48 31 30 33 31 30 7d 20 Files {H10310}
28950 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 <S20000>.**.** I
28960 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 f this global va
28970 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 riable is made t
28980 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 o point to a str
28990 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 ing which is.**
289a0 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f the name of a fo
289b0 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 lder (a.k.a. dir
289c0 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c ectory), then al
289d0 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 l temporary file
289e0 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 s.** created by
289f0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70 SQLite will be p
28a00 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 laced in that di
28a10 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69 rectory. If thi
28a20 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 s variable.** is
28a30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
28a40 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 then SQLite per
28a50 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 forms a search f
28a60 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 or an appropriat
28a70 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 e.** temporary f
28a80 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a ile directory..*
28a90 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 *.** It is not s
28aa0 61 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 afe to modify th
28ab0 69 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63 65 is variable once
28ac0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
28ad0 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 68 61 73 20 nection].** has
28ae0 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74 been opened. It
28af0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 is intended tha
28b00 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 t this variable
28b10 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 be set once.** a
28b20 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 s part of proces
28b30 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e s initialization
28b40 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 and before any
28b50 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
28b60 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 .** routines hav
28b70 65 20 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20 e been call and
28b80 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 remain unchanged
28b90 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a thereafter..*/.
28ba0 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 SQLITE_EXTERN ch
28bb0 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 ar *sqlite3_temp
28bc0 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a _directory;../*.
28bd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 ** CAPI3REF: Tes
28be0 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 t For Auto-Commi
28bf0 74 20 4d 6f 64 65 20 7b 48 31 32 39 33 30 7d 20 t Mode {H12930}
28c00 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 <S60200>.** KEYW
28c10 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 ORDS: {autocommi
28c20 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 t mode}.**.** Th
28c30 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 e sqlite3_get_au
28c40 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 tocommit() inter
28c50 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e face returns non
28c60 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f -zero or.** zero
28c70 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 if the given da
28c80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
28c90 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 n is or is not i
28ca0 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 n autocommit mod
28cb0 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 e,.** respective
28cc0 6c 79 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 ly. Autocommit
28cd0 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 mode is on by de
28ce0 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f fault..** Autoco
28cf0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 mmit mode is dis
28d00 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 abled by a [BEGI
28d10 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a N] statement..**
28d20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 Autocommit mode
28d30 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 is re-enabled b
28d40 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 y a [COMMIT] or
28d50 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a [ROLLBACK]..**.*
28d60 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e * If certain kin
28d70 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 ds of errors occ
28d80 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e ur on a statemen
28d90 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 t within a multi
28da0 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 -statement.** tr
28db0 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 ansaction (error
28dc0 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c s including [SQL
28dd0 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 ITE_FULL], [SQLI
28de0 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 TE_IOERR],.** [S
28df0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 QLITE_NOMEM], [S
28e00 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 QLITE_BUSY], and
28e10 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 [SQLITE_INTERRU
28e20 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a PT]) then the.**
28e30 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 transaction mig
28e40 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 ht be rolled bac
28e50 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e k automatically.
28e60 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 The only way t
28e70 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 o.** find out wh
28e80 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 ether SQLite aut
28e90 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 omatically rolle
28ea0 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 d back the trans
28eb0 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 action after.**
28ec0 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 an error is to u
28ed0 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e se this function
28ee0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 ..**.** If anoth
28ef0 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 er thread change
28f00 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 s the autocommit
28f10 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 status of the d
28f20 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
28f30 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 ction while this
28f40 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e routine is runn
28f50 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 ing, then the re
28f60 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 turn value.** is
28f70 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
28f80 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 * Requirements:
28f90 5b 48 31 32 39 33 31 5d 20 5b 48 31 32 39 33 32 [H12931] [H12932
28fa0 5d 20 5b 48 31 32 39 33 33 5d 20 5b 48 31 32 39 ] [H12933] [H129
28fb0 33 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 34].*/.int sqlit
28fc0 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 e3_get_autocommi
28fd0 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a t(sqlite3*);../*
28fe0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 .** CAPI3REF: Fi
28ff0 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20 nd The Database
29000 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 Handle Of A Prep
29010 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b ared Statement {
29020 48 31 33 31 32 30 7d 20 3c 53 36 30 36 30 30 3e H13120} <S60600>
29030 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
29040 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 e3_db_handle int
29050 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
29060 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
29070 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a nection] handle.
29080 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 ** to which a [p
29090 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
290a0 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 54 68 65 t] belongs. The
290b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
290c0 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e ction].** return
290d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 ed by sqlite3_db
290e0 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 _handle is the s
290f0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f ame [database co
29100 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 77 nnection] that w
29110 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
29120 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 ument.** to the
29130 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
29140 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 _v2()] call (or
29150 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 its variants) th
29160 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a at was used to.*
29170 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 * create the sta
29180 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 tement in the fi
29190 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a rst place..**.**
291a0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b Requirements: [
291b0 48 31 33 31 32 33 5d 0a 2a 2f 0a 73 71 6c 69 74 H13123].*/.sqlit
291c0 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 e3 *sqlite3_db_h
291d0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 andle(sqlite3_st
291e0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
291f0 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 I3REF: Find the
29200 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 next prepared st
29210 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 34 30 7d atement {H13140}
29220 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S60600>.**.**
29230 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 This interface r
29240 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
29250 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 to the next [pr
29260 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
29270 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 ] after.** pStmt
29280 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
29290 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
292a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 onnection] pDb.
292b0 20 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c If pStmt is NUL
292c0 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 L.** then this i
292d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
292e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
292f0 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 e first prepared
29300 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 statement.** as
29310 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
29320 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
29330 63 74 69 6f 6e 20 70 44 62 2e 20 20 49 66 20 6e ction pDb. If n
29340 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 o prepared state
29350 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 ment.** satisfie
29360 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 s the conditions
29370 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 of this routine
29380 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c , it returns NUL
29390 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 L..**.** The [da
293a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
293b0 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 n] pointer D in
293c0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 a call to.** [sq
293d0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 lite3_next_stmt(
293e0 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 D,S)] must refer
293f0 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 to an open data
29400 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
29410 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 on and in partic
29420 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 ular must not be
29430 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
29440 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
29450 6e 74 73 3a 20 5b 48 31 33 31 34 33 5d 20 5b 48 nts: [H13143] [H
29460 31 33 31 34 36 5d 20 5b 48 31 33 31 34 39 5d 20 13146] [H13149]
29470 5b 48 31 33 31 35 32 5d 0a 2a 2f 0a 73 71 6c 69 [H13152].*/.sqli
29480 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 te3_stmt *sqlite
29490 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 3_next_stmt(sqli
294a0 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 te3 *pDb, sqlite
294b0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
294c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
294d0 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c Commit And Roll
294e0 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f back Notificatio
294f0 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 n Callbacks {H12
29500 39 35 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 950} <S60400>.**
29510 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
29520 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e commit_hook() in
29530 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 terface register
29540 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 s a callback.**
29550 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 function to be i
29560 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 nvoked whenever
29570 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
29580 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 committed..** A
29590 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 ny callback set
295a0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 by a previous ca
295b0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ll to sqlite3_co
295c0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 mmit_hook().** f
295d0 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 or the same data
295e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
295f0 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a is overridden..*
29600 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f * The sqlite3_ro
29610 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e llback_hook() in
29620 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 terface register
29630 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 s a callback.**
29640 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 function to be i
29650 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 nvoked whenever
29660 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
29670 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 committed..** A
29680 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 ny callback set
29690 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 by a previous ca
296a0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ll to sqlite3_co
296b0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 mmit_hook().** f
296c0 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 or the same data
296d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
296e0 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a is overridden..*
296f0 2a 20 54 68 65 20 70 41 72 67 20 61 72 67 75 6d * The pArg argum
29700 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 ent is passed th
29710 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c rough to the cal
29720 6c 62 61 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 lback..** If the
29730 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 callback on a c
29740 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 ommit hook funct
29750 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ion returns non-
29760 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 zero,.** then th
29770 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 e commit is conv
29780 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c erted into a rol
29790 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 lback..**.** If
297a0 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e another function
297b0 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 was previously
297c0 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a registered, its.
297d0 2a 2a 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 ** pArg value is
297e0 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 returned. Othe
297f0 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 rwise NULL is re
29800 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 turned..**.** Th
29810 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 e callback imple
29820 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e mentation must n
29830 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 ot do anything t
29840 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a hat will modify.
29850 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
29860 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
29870 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c invoked the call
29880 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f back. Any actio
29890 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 ns.** to modify
298a0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
298b0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 nection must be
298c0 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 deferred until a
298d0 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 fter the.** comp
298e0 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 letion of the [s
298f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 qlite3_step()] c
29900 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
29910 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a ed the commit.**
29920 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f or rollback hoo
29930 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 k in the first p
29940 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 lace..** Note th
29950 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
29960 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
29970 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
29980 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
29990 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
299a0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
299b0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
299c0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
299d0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 agraph..**.** Re
299e0 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c gistering a NULL
299f0 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c function disabl
29a00 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e es the callback.
29a10 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 .**.** For the p
29a20 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 urposes of this
29a30 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 API, a transacti
29a40 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 on is said to ha
29a50 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 ve been.** rolle
29a60 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 d back if an exp
29a70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 licit "ROLLBACK"
29a80 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 statement is ex
29a90 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e ecuted, or.** an
29aa0 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 error or constr
29ab0 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 aint causes an i
29ac0 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b mplicit rollback
29ad0 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 to occur..** Th
29ae0 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 e rollback callb
29af0 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b ack is not invok
29b00 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 ed if a transact
29b10 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 ion is.** automa
29b20 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 tically rolled b
29b30 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 ack because the
29b40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
29b50 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a ion is closed..*
29b60 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 * The rollback c
29b70 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 allback is not i
29b80 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e nvoked if a tran
29b90 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f saction is.** ro
29ba0 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 lled back becaus
29bb0 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 e a commit callb
29bc0 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e ack returned non
29bd0 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e -zero..** <todo>
29be0 20 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c Check on this <
29bf0 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 52 65 71 /todo>.**.** Req
29c00 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
29c10 31 32 39 35 31 5d 20 5b 48 31 32 39 35 32 5d 20 12951] [H12952]
29c20 5b 48 31 32 39 35 33 5d 20 5b 48 31 32 39 35 34 [H12953] [H12954
29c30 5d 20 5b 48 31 32 39 35 35 5d 0a 2a 2a 20 5b 48 ] [H12955].** [H
29c40 31 32 39 36 31 5d 20 5b 48 31 32 39 36 32 5d 20 12961] [H12962]
29c50 5b 48 31 32 39 36 33 5d 20 5b 48 31 32 39 36 34 [H12963] [H12964
29c60 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ].*/.void *sqlit
29c70 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 e3_commit_hook(s
29c80 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 qlite3*, int(*)(
29c90 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a void*), void*);.
29ca0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f void *sqlite3_ro
29cb0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 llback_hook(sqli
29cc0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f te3*, void(*)(vo
29cd0 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a id *), void*);..
29ce0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
29cf0 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 Data Change Noti
29d00 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 fication Callbac
29d10 6b 73 20 7b 48 31 32 39 37 30 7d 20 3c 53 36 30 ks {H12970} <S60
29d20 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 400>.**.** The s
29d30 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f qlite3_update_ho
29d40 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ok() interface r
29d50 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 egisters a callb
29d60 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ack function.**
29d70 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 with the [databa
29d80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
29d90 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 dentified by the
29da0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a first argument.
29db0 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 ** to be invoked
29dc0 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 whenever a row
29dd0 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 is updated, inse
29de0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e rted or deleted.
29df0 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b .** Any callback
29e00 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f set by a previo
29e10 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 us call to this
29e20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 function.** for
29e30 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
29e40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
29e50 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a overridden..**.*
29e60 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 * The second arg
29e70 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
29e80 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 er to the functi
29e90 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 on to invoke whe
29ea0 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 n a.** row is up
29eb0 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 dated, inserted
29ec0 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 54 or deleted..** T
29ed0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
29ee0 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 t to the callbac
29ef0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 k is a copy of t
29f00 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
29f10 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f t.** to sqlite3_
29f20 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a update_hook()..*
29f30 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c * The second cal
29f40 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 lback argument i
29f50 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 s one of [SQLITE
29f60 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 _INSERT], [SQLIT
29f70 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 E_DELETE],.** or
29f80 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d [SQLITE_UPDATE]
29f90 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 , depending on t
29fa0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 he operation tha
29fb0 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c t caused the cal
29fc0 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 lback.** to be i
29fd0 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74 nvoked..** The t
29fe0 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 hird and fourth
29ff0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 arguments to the
2a000 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 callback contai
2a010 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 n pointers to th
2a020 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e e.** database an
2a030 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e d table name con
2a040 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 taining the affe
2a050 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 cted row..** The
2a060 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 final callback
2a070 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
2a080 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 [rowid] of the
2a090 72 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 63 row..** In the c
2a0a0 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 ase of an update
2a0b0 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b 72 , this is the [r
2a0c0 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 20 owid] after the
2a0d0 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 update takes pla
2a0e0 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 ce..**.** The up
2a0f0 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 date hook is not
2a100 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e invoked when in
2a110 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 ternal system ta
2a120 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 bles are.** modi
2a130 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 fied (i.e. sqlit
2a140 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c e_master and sql
2a150 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a ite_sequence)..*
2a160 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 *.** The update
2a170 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 hook implementat
2a180 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ion must not do
2a190 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
2a1a0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
2a1b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
2a1c0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
2a1d0 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f d the update hoo
2a1e0 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a k. Any actions.
2a1f0 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 ** to modify the
2a200 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
2a210 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 tion must be def
2a220 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 erred until afte
2a230 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 r the.** complet
2a240 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 ion of the [sqli
2a250 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c te3_step()] call
2a260 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 that triggered
2a270 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e the update hook.
2a280 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 .** Note that [s
2a290 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2a2a0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
2a2b0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 3_step()] both m
2a2c0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 odify their.** d
2a2d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2a2e0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
2a2f0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
2a300 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
2a310 68 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 h..**.** If anot
2a320 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 her function was
2a330 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 previously regi
2a340 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 stered, its pArg
2a350 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 value.** is ret
2a360 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 urned. Otherwis
2a370 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e e NULL is return
2a380 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ed..**.** Requir
2a390 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 ements:.** [H129
2a3a0 37 31 5d 20 5b 48 31 32 39 37 33 5d 20 5b 48 31 71] [H12973] [H1
2a3b0 32 39 37 35 5d 20 5b 48 31 32 39 37 37 5d 20 5b 2975] [H12977] [
2a3c0 48 31 32 39 37 39 5d 20 5b 48 31 32 39 38 31 5d H12979] [H12981]
2a3d0 20 5b 48 31 32 39 38 33 5d 20 5b 48 31 32 39 38 [H12983] [H1298
2a3e0 36 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 6].*/.void *sqli
2a3f0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 te3_update_hook(
2a400 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
2a410 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 void(*)(void *,i
2a420 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a nt ,char const *
2a430 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 ,char const *,sq
2a440 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 lite3_int64),.
2a450 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*.);../*.**
2a460 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 CAPI3REF: Enable
2a470 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 Or Disable Shar
2a480 65 64 20 50 61 67 65 72 20 43 61 63 68 65 20 7b ed Pager Cache {
2a490 48 31 30 33 33 30 7d 20 3c 53 33 30 39 30 30 3e H10330} <S30900>
2a4a0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 .** KEYWORDS: {s
2a4b0 68 61 72 65 64 20 63 61 63 68 65 7d 20 7b 73 68 hared cache} {sh
2a4c0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 7d ared cache mode}
2a4d0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
2a4e0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 ine enables or d
2a4f0 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 isables the shar
2a500 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 ing of the datab
2a510 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 ase cache.** and
2a520 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 schema data str
2a530 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 uctures between
2a540 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2a550 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f tion | connectio
2a560 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 ns].** to the sa
2a570 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61 me database. Sha
2a580 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 ring is enabled
2a590 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 if the argument
2a5a0 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 is true.** and d
2a5b0 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 isabled if the a
2a5c0 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 rgument is false
2a5d0 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68 ..**.** Cache sh
2a5e0 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 aring is enabled
2a5f0 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f and disabled fo
2a600 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 r an entire proc
2a610 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 ess..** This is
2a620 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 a change as of S
2a630 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
2a640 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 5.0. In prior ve
2a650 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
2a660 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 ,.** sharing was
2a670 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 enabled or disa
2a680 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 bled for each th
2a690 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e read separately.
2a6a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 .**.** The cache
2a6b0 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 sharing mode se
2a6c0 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 t by this interf
2a6d0 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 ace effects all
2a6e0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 subsequent.** ca
2a6f0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
2a700 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
2a710 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 3_open_v2()], an
2a720 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 d [sqlite3_open1
2a730 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 6()]..** Existin
2a740 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 g database conne
2a750 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 ctions continue
2a760 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 use the sharing
2a770 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 mode.** that was
2a780 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 in effect at th
2a790 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 e time they were
2a7a0 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 opened..**.** V
2a7b0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 irtual tables ca
2a7c0 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69 74 nnot be used wit
2a7d0 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68 65 h a shared cache
2a7e0 2e 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a . When shared.*
2a7f0 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c * cache is enabl
2a800 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ed, the [sqlite3
2a810 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 _create_module()
2a820 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 ] API used to re
2a830 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 gister.** virtua
2a840 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c l tables will al
2a850 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 ways return an e
2a860 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 rror..**.** This
2a870 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
2a880 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 [SQLITE_OK] if
2a890 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73 shared cache was
2a8a0 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 enabled or disa
2a8b0 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 bled.** successf
2a8c0 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 ully. An [error
2a8d0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
2a8e0 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a ed otherwise..**
2a8f0 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65 .** Shared cache
2a900 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 is disabled by
2a910 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 default. But thi
2a920 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 s might change i
2a930 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 n.** future rele
2a940 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 ases of SQLite.
2a950 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 Applications th
2a960 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 at care about sh
2a970 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 ared.** cache se
2a980 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 tting should set
2a990 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a it explicitly..
2a9a0 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 **.** See Also:
2a9b0 20 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d [SQLite Shared-
2a9c0 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a Cache Mode].**.*
2a9d0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 * Requirements:
2a9e0 5b 48 31 30 33 33 31 5d 20 5b 48 31 30 33 33 36 [H10331] [H10336
2a9f0 5d 20 5b 48 31 30 33 33 37 5d 20 5b 48 31 30 33 ] [H10337] [H103
2aa00 33 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 39].*/.int sqlit
2aa10 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 e3_enable_shared
2aa20 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a _cache(int);../*
2aa30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 .** CAPI3REF: At
2aa40 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 tempt To Free He
2aa50 61 70 20 4d 65 6d 6f 72 79 20 7b 48 31 37 33 34 ap Memory {H1734
2aa60 30 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 0} <S30220>.**.*
2aa70 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
2aa80 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 lease_memory() i
2aa90 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 nterface attempt
2aaa0 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 s to free N byte
2aab0 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d s.** of heap mem
2aac0 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 ory by deallocat
2aad0 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 ing non-essentia
2aae0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
2aaf0 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 ions.** held by
2ab00 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 the database lib
2ab10 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d rary. {END} Mem
2ab20 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 ory used to cach
2ab30 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 e database.** pa
2ab40 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 ges to improve p
2ab50 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e erformance is an
2ab60 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d example of non-
2ab70 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 essential memory
2ab80 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c ..** sqlite3_rel
2ab90 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 ease_memory() re
2aba0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
2abb0 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c of bytes actual
2abc0 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 ly freed,.** whi
2abd0 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 ch might be more
2abe0 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 or less than th
2abf0 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 e amount request
2ac00 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ed..**.** Requir
2ac10 65 6d 65 6e 74 73 3a 20 5b 48 31 37 33 34 31 5d ements: [H17341]
2ac20 20 5b 48 31 37 33 34 32 5d 0a 2a 2f 0a 69 6e 74 [H17342].*/.int
2ac30 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 sqlite3_release
2ac40 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f _memory(int);../
2ac50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
2ac60 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e mpose A Limit On
2ac70 20 48 65 61 70 20 53 69 7a 65 20 7b 48 31 37 33 Heap Size {H173
2ac80 35 30 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 50} <S30220>.**.
2ac90 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 ** The sqlite3_s
2aca0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 oft_heap_limit()
2acb0 20 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63 65 interface place
2acc0 73 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 s a "soft" limit
2acd0 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e .** on the amoun
2ace0 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 t of heap memory
2acf0 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c that may be all
2ad00 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 ocated by SQLite
2ad10 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 ..** If an inter
2ad20 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 nal allocation i
2ad30 73 20 72 65 71 75 65 73 74 65 64 20 74 68 61 74 s requested that
2ad40 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 would exceed th
2ad50 65 0a 2a 2a 20 73 6f 66 74 20 68 65 61 70 20 6c e.** soft heap l
2ad60 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 imit, [sqlite3_r
2ad70 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d elease_memory()]
2ad80 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 is invoked one
2ad90 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 69 6d 65 73 or.** more times
2ada0 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65 to free up some
2adb0 20 73 70 61 63 65 20 62 65 66 6f 72 65 20 74 68 space before th
2adc0 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 e allocation is
2add0 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a performed..**.**
2ade0 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61 The limit is ca
2adf0 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63 lled "soft", bec
2ae00 61 75 73 65 20 69 66 20 5b 73 71 6c 69 74 65 33 ause if [sqlite3
2ae10 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 _release_memory(
2ae20 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 20 66 72 65 )].** cannot fre
2ae30 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d e sufficient mem
2ae40 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74 ory to prevent t
2ae50 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 he limit from be
2ae60 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a ing exceeded,.**
2ae70 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 the memory is a
2ae80 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20 llocated anyway
2ae90 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 and the current
2aea0 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 operation procee
2aeb0 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 ds..**.** A nega
2aec0 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c tive or zero val
2aed0 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 ue for N means t
2aee0 68 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 hat there is no
2aef0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 soft heap limit
2af00 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
2af10 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 release_memory()
2af20 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 ] will only be c
2af30 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 alled when memor
2af40 79 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a y is exhausted..
2af50 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 ** The default v
2af60 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 alue for the sof
2af70 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 t heap limit is
2af80 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 zero..**.** SQLi
2af90 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20 te makes a best
2afa0 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 effort to honor
2afb0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 the soft heap li
2afc0 6d 69 74 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74 mit..** But if t
2afd0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d he soft heap lim
2afe0 69 74 20 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e it cannot be hon
2aff0 6f 72 65 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 ored, execution
2b000 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 will.** continue
2b010 20 77 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f without error o
2b020 72 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20 r notification.
2b030 20 54 68 69 73 20 69 73 20 77 68 79 20 74 68 65 This is why the
2b040 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c limit is.** cal
2b050 6c 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d led a "soft" lim
2b060 69 74 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 it. It is advis
2b070 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ory only..**.**
2b080 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 Prior to SQLite
2b090 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 version 3.5.0, t
2b0a0 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 his routine only
2b0b0 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 constrained the
2b0c0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
2b0d0 61 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 ated by a single
2b0e0 20 74 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 thread - the sa
2b0f0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 me thread in whi
2b100 63 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a ch this routine.
2b110 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e ** runs. Beginn
2b120 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 ing with SQLite
2b130 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 version 3.5.0, t
2b140 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d he soft heap lim
2b150 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 it is.** applied
2b160 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e to all threads.
2b170 20 54 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 The value speci
2b180 66 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 fied for the sof
2b190 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 t heap limit.**
2b1a0 69 73 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e is an upper boun
2b1b0 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d d on the total m
2b1c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
2b1d0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 for all threads
2b1e0 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 . In.** version
2b1f0 33 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 3.5.0 there is n
2b200 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 o mechanism for
2b210 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 limiting the hea
2b220 70 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 p usage for.** i
2b230 6e 64 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 ndividual thread
2b240 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 s..**.** Require
2b250 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 33 35 ments:.** [H1635
2b260 31 5d 20 5b 48 31 36 33 35 32 5d 20 5b 48 31 36 1] [H16352] [H16
2b270 33 35 33 5d 20 5b 48 31 36 33 35 34 5d 20 5b 48 353] [H16354] [H
2b280 31 36 33 35 35 5d 20 5b 48 31 36 33 35 38 5d 0a 16355] [H16358].
2b290 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f */.void sqlite3_
2b2a0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 soft_heap_limit(
2b2b0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
2b2c0 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d I3REF: Extract M
2b2d0 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 etadata About A
2b2e0 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c Column Of A Tabl
2b2f0 65 20 7b 48 31 32 38 35 30 7d 20 3c 53 36 30 33 e {H12850} <S603
2b300 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 00>.**.** This r
2b310 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d outine returns m
2b320 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 etadata about a
2b330 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 specific column
2b340 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a of a specific.**
2b350 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 database table
2b360 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 accessible using
2b370 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
2b380 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c onnection] handl
2b390 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 e.** passed as t
2b3a0 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f he first functio
2b3b0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a n argument..**.*
2b3c0 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 * The column is
2b3d0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 identified by th
2b3e0 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 e second, third
2b3f0 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d and fourth param
2b400 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 eters to.** this
2b410 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 function. The s
2b420 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
2b430 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 is either the na
2b440 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 me of the databa
2b450 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 se.** (i.e. "mai
2b460 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e n", "temp" or an
2b470 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 attached databa
2b480 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 se) containing t
2b490 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 he specified.**
2b4a0 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 table or NULL. I
2b4b0 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 f it is NULL, th
2b4c0 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 en all attached
2b4d0 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65 databases are se
2b4e0 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 arched.** for th
2b4f0 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 e table using th
2b500 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d e same algorithm
2b510 20 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74 used by the dat
2b520 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a abase engine to.
2b530 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 ** resolve unqua
2b540 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 lified table ref
2b550 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 erences..**.** T
2b560 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 he third and fou
2b570 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 rth parameters t
2b580 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 o this function
2b590 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e are the table an
2b5a0 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 d column.** name
2b5b0 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 of the desired
2b5c0 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 column, respecti
2b5d0 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 vely. Neither of
2b5e0 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 these parameter
2b5f0 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c s.** may be NULL
2b600 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 64 61 74 61 ..**.** Metadata
2b610 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 is returned by
2b620 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d writing to the m
2b630 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 emory locations
2b640 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35 74 passed as the 5t
2b650 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75 h.** and subsequ
2b660 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 ent parameters t
2b670 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e o this function.
2b680 20 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61 72 Any of these ar
2b690 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a guments may be.*
2b6a0 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 * NULL, in which
2b6b0 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 case the corres
2b6c0 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 ponding element
2b6d0 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 20 6f of metadata is o
2b6e0 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 mitted..**.** <b
2b6f0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 lockquote>.** <t
2b700 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e able border="1">
2b710 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 .** <tr><th> Par
2b720 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 ameter <th> Outp
2b730 75 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 ut<br>Type <th>
2b740 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a Description.**.
2b750 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 ** <tr><td> 5th
2b760 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a <td> const char*
2b770 20 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a <td> Data type.
2b780 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 ** <tr><td> 6th
2b790 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a <td> const char*
2b7a0 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 <td> Name of de
2b7b0 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 fault collation
2b7c0 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e sequence.** <tr>
2b7d0 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e <td> 7th <td> in
2b7e0 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 t <td> T
2b7f0 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 rue if column ha
2b800 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e s a NOT NULL con
2b810 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c straint.** <tr><
2b820 74 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 td> 8th <td> int
2b830 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 <td> Tr
2b840 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 ue if column is
2b850 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d part of the PRIM
2b860 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c ARY KEY.** <tr><
2b870 74 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 td> 9th <td> int
2b880 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 <td> Tr
2b890 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 ue if column is
2b8a0 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a [AUTOINCREMENT].
2b8b0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c ** </table>.** <
2b8c0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
2b8d0 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f ** The memory po
2b8e0 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 inted to by the
2b8f0 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 character pointe
2b900 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 rs returned for
2b910 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 the.** declarati
2b920 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c on type and coll
2b930 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 ation sequence i
2b940 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 s valid only unt
2b950 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 il the next.** c
2b960 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 all to any SQLit
2b970 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a e API function..
2b980 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 **.** If the spe
2b990 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 cified table is
2b9a0 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c actually a view,
2b9b0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d an [error code]
2b9c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
2b9d0 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 .** If the speci
2b9e0 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 fied column is "
2b9f0 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 rowid", "oid" or
2ba00 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 "_rowid_" and a
2ba10 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 n.** [INTEGER PR
2ba20 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d IMARY KEY] colum
2ba30 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 n has been expli
2ba40 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 citly declared,
2ba50 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a then the output.
2ba60 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 ** parameters ar
2ba70 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 e set for the ex
2ba80 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 plicitly declare
2ba90 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 d column. If the
2baa0 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c re is no.** expl
2bab0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 icitly declared
2bac0 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 [INTEGER PRIMARY
2bad0 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 KEY] column, th
2bae0 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a en the output.**
2baf0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 parameters are
2bb00 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a set as follows:.
2bb10 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 **.** <pre>.**
2bb20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 data type: "I
2bb30 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 NTEGER".** c
2bb40 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
2bb50 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 e: "BINARY".**
2bb60 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a not null: 0.*
2bb70 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 * primary ke
2bb80 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f y: 1.** auto
2bb90 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a increment: 0.**
2bba0 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 </pre>.**.** Th
2bbb0 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 is function may
2bbc0 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 load one or more
2bbd0 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 schemas from da
2bbe0 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 tabase files. If
2bbf0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 an.** error occ
2bc00 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 urs during this
2bc10 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 process, or if t
2bc20 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 he requested tab
2bc30 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 le or column.**
2bc40 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c cannot be found,
2bc50 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d an [error code]
2bc60 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 is returned and
2bc70 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
2bc80 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 e left.** in the
2bc90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2bca0 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 ction] (to be re
2bcb0 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 trieved using sq
2bcc0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e lite3_errmsg()).
2bcd0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 .**.** This API
2bce0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c is only availabl
2bcf0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 e if the library
2bd00 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 was compiled wi
2bd10 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 th the.** [SQLIT
2bd20 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f E_ENABLE_COLUMN_
2bd30 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 METADATA] C-prep
2bd40 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 rocessor symbol
2bd50 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 defined..*/.int
2bd60 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f sqlite3_table_co
2bd70 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 lumn_metadata(.
2bd80 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
2bd90 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
2bda0 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c Connection handl
2bdb0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
2bdc0 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 r *zDbName,
2bdd0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e /* Database n
2bde0 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 ame or NULL */.
2bdf0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 const char *zTa
2be00 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 bleName, /*
2be10 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 Table name */.
2be20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c const char *zCol
2be30 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 umnName, /* C
2be40 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 olumn name */.
2be50 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 char const **pzD
2be60 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f ataType, /* O
2be70 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 UTPUT: Declared
2be80 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 data type */. c
2be90 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f har const **pzCo
2bea0 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 llSeq, /* OU
2beb0 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 TPUT: Collation
2bec0 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f sequence name */
2bed0 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c . int *pNotNull
2bee0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
2bef0 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 * OUTPUT: True i
2bf00 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 f NOT NULL const
2bf10 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a raint exists */.
2bf20 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b int *pPrimaryK
2bf30 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a ey, /*
2bf40 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 OUTPUT: True if
2bf50 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 column part of
2bf60 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 PK */. int *pAu
2bf70 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 toinc
2bf80 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 /* OUTPUT: T
2bf90 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 rue if column is
2bfa0 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 auto-increment
2bfb0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
2bfc0 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 I3REF: Load An E
2bfd0 78 74 65 6e 73 69 6f 6e 20 7b 48 31 32 36 30 30 xtension {H12600
2bfe0 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a } <S20500>.**.**
2bff0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
2c000 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65 20 loads an SQLite
2c010 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 extension librar
2c020 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64 y from the named
2c030 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 file..**.** {H1
2c040 32 36 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65 2601} The sqlite
2c050 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 3_load_extension
2c060 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 () interface att
2c070 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e empts to load an
2c080 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c .** SQL
2c090 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 ite extension li
2c0a0 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 brary contained
2c0b0 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c in the file zFil
2c0c0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 32 e..**.** {H12602
2c0d0 7d 20 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e } The entry poin
2c0e0 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a t is zProc..**.*
2c0f0 2a 20 7b 48 31 32 36 30 33 7d 20 7a 50 72 6f 63 * {H12603} zProc
2c100 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68 may be 0, in wh
2c110 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d ich case the nam
2c120 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 e of the entry p
2c130 6f 69 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 oint.**
2c140 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 defaults to "sq
2c150 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f lite3_extension_
2c160 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 init"..**.** {H1
2c170 32 36 30 34 7d 20 54 68 65 20 73 71 6c 69 74 65 2604} The sqlite
2c180 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 3_load_extension
2c190 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 () interface sha
2c1a0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 ll return.**
2c1b0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b [SQLITE_OK
2c1c0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 ] on success and
2c1d0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
2c1e0 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 if something goe
2c1f0 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b s wrong..**.** {
2c200 48 31 32 36 30 35 7d 20 49 66 20 61 6e 20 65 72 H12605} If an er
2c210 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 ror occurs and p
2c220 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 zErrMsg is not 0
2c230 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 , then the.**
2c240 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
2c250 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
2c260 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c ] interface shal
2c270 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 l attempt to.**
2c280 20 20 20 20 20 20 20 20 20 66 69 6c 6c 20 2a 70 fill *p
2c290 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 zErrMsg with err
2c2a0 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 or message text
2c2b0 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 stored in memory
2c2c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 .** obt
2c2d0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
2c2e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 7b te3_malloc()]. {
2c2f0 45 4e 44 7d 20 20 54 68 65 20 63 61 6c 6c 69 6e END} The callin
2c300 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 g function.**
2c310 20 20 20 20 20 20 20 73 68 6f 75 6c 64 20 66 72 should fr
2c320 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 ee this memory b
2c330 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 y calling [sqlit
2c340 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a e3_free()]..**.*
2c350 2a 20 7b 48 31 32 36 30 36 7d 20 45 78 74 65 6e * {H12606} Exten
2c360 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 sion loading mus
2c370 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 t be enabled usi
2c380 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ng.** [
2c390 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c sqlite3_enable_l
2c3a0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d oad_extension()]
2c3b0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e prior to callin
2c3c0 67 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 20 g this API,.**
2c3d0 20 20 20 20 20 20 20 20 6f 74 68 65 72 77 69 73 otherwis
2c3e0 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 e an error will
2c3f0 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a be returned..*/.
2c400 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 int sqlite3_load
2c410 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 _extension(. sq
2c420 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
2c430 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 /* Load the
2c440 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 extension into t
2c450 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e his database con
2c460 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e nection */. con
2c470 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 st char *zFile,
2c480 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 /* Name of th
2c490 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 e shared library
2c4a0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 containing exte
2c4b0 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 nsion */. const
2c4c0 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 char *zProc,
2c4d0 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e /* Entry point.
2c4e0 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a Derived from z
2c4f0 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 File if 0 */. c
2c500 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 har **pzErrMsg
2c510 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f /* Put erro
2c520 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 r message here i
2c530 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f f not 0 */.);../
2c540 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 *.** CAPI3REF: E
2c550 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 nable Or Disable
2c560 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 Extension Loadi
2c570 6e 67 20 7b 48 31 32 36 32 30 7d 20 3c 53 32 30 ng {H12620} <S20
2c580 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 500>.**.** So as
2c590 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 not to open sec
2c5a0 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f urity holes in o
2c5b0 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e lder application
2c5c0 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e s that are.** un
2c5d0 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c prepared to deal
2c5e0 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 with extension
2c5f0 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 loading, and as
2c600 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 a means of disab
2c610 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f ling.** extensio
2c620 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 n loading while
2c630 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d evaluating user-
2c640 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 entered SQL, the
2c650 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a following API.*
2c660 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f * is provided to
2c670 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 turn the [sqlit
2c680 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f e3_load_extensio
2c690 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f n()] mechanism o
2c6a0 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a n and off..**.**
2c6b0 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 Extension loadi
2c6c0 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 ng is off by def
2c6d0 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 ault. See ticket
2c6e0 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48 #1863..**.** {H
2c6f0 31 32 36 32 31 7d 20 43 61 6c 6c 20 74 68 65 20 12621} Call the
2c700 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c sqlite3_enable_l
2c710 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 oad_extension()
2c720 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f routine with ono
2c730 66 66 3d 3d 31 0a 2a 2a 20 20 20 20 20 20 20 20 ff==1.**
2c740 20 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 to turn extens
2c750 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 ion loading on a
2c760 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 nd call it with
2c770 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e onoff==0 to turn
2c780 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74 20 .** it
2c790 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a back off again..
2c7a0 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 32 7d 20 45 **.** {H12622} E
2c7b0 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 xtension loading
2c7c0 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 is off by defau
2c7d0 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 lt..*/.int sqlit
2c7e0 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 e3_enable_load_e
2c7f0 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 xtension(sqlite3
2c800 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 *db, int onoff)
2c810 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2c820 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 F: Automatically
2c830 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 Load An Extensi
2c840 6f 6e 73 20 7b 48 31 32 36 34 30 7d 20 3c 53 32 ons {H12640} <S2
2c850 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0500>.**.** This
2c860 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f API can be invo
2c870 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 ked at program s
2c880 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 tartup in order
2c890 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f to register.** o
2c8a0 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 ne or more stati
2c8b0 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 cally linked ext
2c8c0 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c ensions that wil
2c8d0 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a l be available.*
2c8e0 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61 * to all new [da
2c8f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2c900 6e 73 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a ns]. {END}.**.**
2c910 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 This routine st
2c920 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 ores a pointer t
2c930 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 o the extension
2c940 69 6e 20 61 6e 20 61 72 72 61 79 20 74 68 61 74 in an array that
2c950 20 69 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 is.** obtained
2c960 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
2c970 6c 6c 6f 63 28 29 5d 2e 20 20 49 66 20 79 6f 75 lloc()]. If you
2c980 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 run a memory le
2c990 61 6b 20 63 68 65 63 6b 65 72 0a 2a 2a 20 6f 6e ak checker.** on
2c9a0 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e your program an
2c9b0 64 20 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c d it reports a l
2c9c0 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74 eak because of t
2c9d0 68 69 73 20 61 72 72 61 79 2c 20 69 6e 76 6f 6b his array, invok
2c9e0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 e.** [sqlite3_re
2c9f0 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 set_auto_extensi
2ca00 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 73 on()] prior to s
2ca10 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 65 65 20 hutdown to free
2ca20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a the memory..**.*
2ca30 2a 20 7b 48 31 32 36 34 31 7d 20 54 68 69 73 20 * {H12641} This
2ca40 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 function registe
2ca50 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 rs an extension
2ca60 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 entry point that
2ca70 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 is.**
2ca80 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e automatically in
2ca90 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 voked whenever a
2caa0 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 new [database c
2cab0 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 onnection].**
2cac0 20 20 20 20 20 20 20 69 73 20 6f 70 65 6e 65 64 is opened
2cad0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
2cae0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
2caf0 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 3_open16()],.**
2cb00 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c or [sql
2cb10 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e ite3_open_v2()].
2cb20 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 32 7d 20 .**.** {H12642}
2cb30 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73 Duplicate extens
2cb40 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65 ions are detecte
2cb50 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 d so calling thi
2cb60 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20 s routine.**
2cb70 20 20 20 20 20 20 6d 75 6c 74 69 70 6c 65 20 74 multiple t
2cb80 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 imes with the sa
2cb90 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 me extension is
2cba0 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 harmless..**.**
2cbb0 7b 48 31 32 36 34 33 7d 20 54 68 69 73 20 72 6f {H12643} This ro
2cbc0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 utine stores a p
2cbd0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 ointer to the ex
2cbe0 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 tension in an ar
2cbf0 72 61 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ray.**
2cc00 74 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 that is obtained
2cc10 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
2cc20 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 alloc()]..**.**
2cc30 7b 48 31 32 36 34 34 7d 20 41 75 74 6f 6d 61 74 {H12644} Automat
2cc40 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 ic extensions ap
2cc50 70 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 ply across all t
2cc60 68 72 65 61 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 hreads..*/.int s
2cc70 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 qlite3_auto_exte
2cc80 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e nsion(void (*xEn
2cc90 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 tryPoint)(void))
2cca0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2ccb0 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 F: Reset Automat
2ccc0 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 ic Extension Loa
2ccd0 64 69 6e 67 20 7b 48 31 32 36 36 30 7d 20 3c 53 ding {H12660} <S
2cce0 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 20500>.**.** Thi
2ccf0 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 s function disab
2cd00 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 les all previous
2cd10 6c 79 20 72 65 67 69 73 74 65 72 65 64 20 61 75 ly registered au
2cd20 74 6f 6d 61 74 69 63 0a 2a 2a 20 65 78 74 65 6e tomatic.** exten
2cd30 73 69 6f 6e 73 2e 20 7b 45 4e 44 7d 20 20 49 74 sions. {END} It
2cd40 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 undoes the effe
2cd50 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a ct of all prior.
2cd60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f ** [sqlite3_auto
2cd70 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61 _extension()] ca
2cd80 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 lls..**.** {H126
2cd90 36 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 61} This functio
2cda0 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 n disables all p
2cdb0 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 reviously regist
2cdc0 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 ered.**
2cdd0 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e automatic exten
2cde0 73 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 sions..**.** {H1
2cdf0 32 36 36 32 7d 20 54 68 69 73 20 66 75 6e 63 74 2662} This funct
2ce00 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 75 74 ion disables aut
2ce10 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e omatic extension
2ce20 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 s in all threads
2ce30 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ..*/.void sqlite
2ce40 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 3_reset_auto_ext
2ce50 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f ension(void);../
2ce60 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d *.****** EXPERIM
2ce70 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 ENTAL - subject
2ce80 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
2ce90 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a t notice *******
2cea0 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 *******.**.** Th
2ceb0 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 e interface to t
2cec0 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 he virtual-table
2ced0 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 mechanism is cu
2cee0 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 rrently consider
2cef0 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 ed.** to be expe
2cf00 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 rimental. The i
2cf10 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 nterface might c
2cf20 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 hange in incompa
2cf30 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 tible ways..** I
2cf40 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 f this is a prob
2cf50 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 lem for you, do
2cf60 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 not use the inte
2cf70 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 rface at this ti
2cf80 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 me..**.** When t
2cf90 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 he virtual-table
2cfa0 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 mechanism stabi
2cfb0 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 lizes, we will d
2cfc0 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e eclare the.** in
2cfd0 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 terface fixed, s
2cfe0 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 upport it indefi
2cff0 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f nitely, and remo
2d000 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e ve this comment.
2d010 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 .*/../*.** Struc
2d020 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 tures used by th
2d030 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 e virtual table
2d040 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 interface.*/.typ
2d050 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
2d060 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 te3_vtab sqlite3
2d070 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 _vtab;.typedef s
2d080 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e truct sqlite3_in
2d090 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 dex_info sqlite3
2d0a0 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 _index_info;.typ
2d0b0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
2d0c0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 te3_vtab_cursor
2d0d0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
2d0e0 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 sor;.typedef str
2d0f0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 uct sqlite3_modu
2d100 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c le sqlite3_modul
2d110 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 e;../*.** CAPI3R
2d120 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c EF: Virtual Tabl
2d130 65 20 4f 62 6a 65 63 74 20 7b 48 31 38 30 30 30 e Object {H18000
2d140 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 } <S20400>.** KE
2d150 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f YWORDS: sqlite3_
2d160 6d 6f 64 75 6c 65 0a 2a 2a 20 45 58 50 45 52 49 module.** EXPERI
2d170 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 20 6d MENTAL.**.** A m
2d180 6f 64 75 6c 65 20 69 73 20 61 20 63 6c 61 73 73 odule is a class
2d190 20 6f 66 20 76 69 72 74 75 61 6c 20 74 61 62 6c of virtual tabl
2d1a0 65 73 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 es. Each module
2d1b0 20 69 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 is defined.** b
2d1c0 79 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 y an instance of
2d1d0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 the following s
2d1e0 74 72 75 63 74 75 72 65 2e 20 20 54 68 69 73 20 tructure. This
2d1f0 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 structure consis
2d200 74 73 0a 2a 2a 20 6d 6f 73 74 6c 79 20 6f 66 20 ts.** mostly of
2d210 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 methods for the
2d220 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 module..**.** Th
2d230 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 is interface is
2d240 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 experimental and
2d250 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 is subject to c
2d260 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f hange or.** remo
2d270 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 val in future re
2d280 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
2d290 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 ..*/.struct sqli
2d2a0 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 te3_module {. i
2d2b0 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 nt iVersion;. i
2d2c0 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 nt (*xCreate)(sq
2d2d0 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 lite3*, void *pA
2d2e0 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 ux,.
2d2f0 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e int argc, con
2d300 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 st char *const*a
2d310 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 rgv,.
2d320 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 sqlite3_vtab
2d330 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a **ppVTab, char*
2d340 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e *);. int (*xCon
2d350 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 nect)(sqlite3*,
2d360 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 void *pAux,.
2d370 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 int a
2d380 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 rgc, const char
2d390 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 *const*argv,.
2d3a0 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 sqli
2d3b0 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 te3_vtab **ppVTa
2d3c0 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e b, char**);. in
2d3d0 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 t (*xBestIndex)(
2d3e0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
2d3f0 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 Tab, sqlite3_ind
2d400 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 ex_info*);. int
2d410 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 (*xDisconnect)(
2d420 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
2d430 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 Tab);. int (*xD
2d440 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f estroy)(sqlite3_
2d450 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
2d460 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c int (*xOpen)(sql
2d470 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
2d480 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 , sqlite3_vtab_c
2d490 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 ursor **ppCursor
2d4a0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 );. int (*xClos
2d4b0 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f e)(sqlite3_vtab_
2d4c0 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 cursor*);. int
2d4d0 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 (*xFilter)(sqlit
2d4e0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c e3_vtab_cursor*,
2d4f0 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e int idxNum, con
2d500 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c st char *idxStr,
2d510 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
2d520 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 int argc, sqlit
2d530 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 e3_value **argv)
2d540 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 ;. int (*xNext)
2d550 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 (sqlite3_vtab_cu
2d560 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a rsor*);. int (*
2d570 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 xEof)(sqlite3_vt
2d580 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 ab_cursor*);. i
2d590 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 nt (*xColumn)(sq
2d5a0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
2d5b0 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 r*, sqlite3_cont
2d5c0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e ext*, int);. in
2d5d0 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 t (*xRowid)(sqli
2d5e0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a te3_vtab_cursor*
2d5f0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
2d600 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 *pRowid);. int
2d610 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 (*xUpdate)(sqlit
2d620 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 e3_vtab *, int,
2d630 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a sqlite3_value **
2d640 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
2d650 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 *);. int (*xBeg
2d660 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 in)(sqlite3_vtab
2d670 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 *pVTab);. int
2d680 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 (*xSync)(sqlite3
2d690 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 _vtab *pVTab);.
2d6a0 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 int (*xCommit)(
2d6b0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
2d6c0 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 Tab);. int (*xR
2d6d0 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 ollback)(sqlite3
2d6e0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 _vtab *pVTab);.
2d6f0 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 int (*xFindFunc
2d700 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 tion)(sqlite3_vt
2d710 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e ab *pVtab, int n
2d720 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 Arg, const char
2d730 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 *zName,.
2d740 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 v
2d750 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 oid (**pxFunc)(s
2d760 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
2d770 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
2d780 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 e**),.
2d790 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 voi
2d7a0 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e d **ppArg);. in
2d7b0 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c t (*xRename)(sql
2d7c0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 ite3_vtab *pVtab
2d7d0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
2d7e0 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ew);.};../*.** C
2d7f0 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c API3REF: Virtual
2d800 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 Table Indexing
2d810 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b 48 31 38 Information {H18
2d820 31 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 100} <S20400>.**
2d830 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 KEYWORDS: sqlit
2d840 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a e3_index_info.**
2d850 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
2d860 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
2d870 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 index_info struc
2d880 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 ture and its sub
2d890 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73 structures is us
2d8a0 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e ed to.** pass in
2d8b0 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 formation into a
2d8c0 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72 nd receive the r
2d8d0 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 78 42 eply from the xB
2d8e0 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d 65 74 68 estIndex.** meth
2d8f0 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 od of an sqlite3
2d900 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 66 69 _module. The fi
2d910 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 elds under **Inp
2d920 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a uts** are the.**
2d930 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74 inputs to xBest
2d940 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65 Index and are re
2d950 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 ad-only. xBestI
2d960 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73 ndex inserts its
2d970 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f .** results into
2d980 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a the **Outputs**
2d990 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 fields..**.** T
2d9a0 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d he aConstraint[]
2d9b0 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 array records W
2d9c0 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 HERE clause cons
2d9d0 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20 66 traints of the f
2d9e0 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e orm:.**.** <pre>
2d9f0 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f column OP expr</
2da00 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 pre>.**.** where
2da10 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 OP is =, <,
2da20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 <=, >, or
2da30 26 67 74 3b 3d 2e 20 20 54 68 65 20 70 61 72 74 >=. The part
2da40 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 icular operator
2da50 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 is.** stored in
2da60 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 aConstraint[].op
2da70 2e 20 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 . The index of
2da80 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 the column is st
2da90 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 ored in.** aCons
2daa0 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e traint[].iColumn
2dab0 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d . aConstraint[]
2dac0 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 .usable is TRUE
2dad0 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f if the.** expr o
2dae0 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 n the right-hand
2daf0 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 side can be eva
2db00 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 luated (and thus
2db10 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a the constraint.
2db20 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e ** is usable) an
2db30 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 d false if it ca
2db40 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nnot..**.** The
2db50 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 optimizer automa
2db60 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 tically inverts
2db70 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 terms of the for
2db80 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d m "expr OP colum
2db90 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 n".** and makes
2dba0 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 other simplifica
2dbb0 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45 tions to the WHE
2dbc0 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 RE clause in an
2dbd0 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 attempt to.** ge
2dbe0 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 t as many WHERE
2dbf0 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 clause terms int
2dc00 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e o the form shown
2dc10 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 above as possib
2dc20 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 le..** The aCons
2dc30 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f traint[] array o
2dc40 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 nly reports WHER
2dc50 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 E clause terms i
2dc60 6e 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a n the correct.**
2dc70 20 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72 form that refer
2dc80 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c to the particul
2dc90 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 ar virtual table
2dca0 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a being queried..
2dcb0 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f **.** Informatio
2dcc0 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 n about the ORDE
2dcd0 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 R BY clause is s
2dce0 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 tored in aOrderB
2dcf0 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 y[]..** Each ter
2dd00 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 m of aOrderBy re
2dd10 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f cords a column o
2dd20 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 f the ORDER BY c
2dd30 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 lause..**.** The
2dd40 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 xBestIndex meth
2dd50 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f od must fill aCo
2dd60 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 nstraintUsage[]
2dd70 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e with information
2dd80 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 .** about what p
2dd90 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 arameters to pas
2dda0 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 s to xFilter. I
2ddb0 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 f argvIndex>0 th
2ddc0 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d en.** the right-
2ddd0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 hand side of the
2dde0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 corresponding a
2ddf0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 Constraint[] is
2de00 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 evaluated.** and
2de10 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 becomes the arg
2de20 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 vIndex-th entry
2de30 69 6e 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f in argv. If aCo
2de40 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e nstraintUsage[].
2de50 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c omit.** is true,
2de60 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 then the constr
2de70 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 aint is assumed
2de80 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 to be fully hand
2de90 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 led by the.** vi
2dea0 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 rtual table and
2deb0 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 is not checked a
2dec0 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a gain by SQLite..
2ded0 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d **.** The idxNum
2dee0 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 and idxPtr valu
2def0 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 es are recorded
2df00 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 and passed into
2df10 78 46 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 xFilter..** sqli
2df20 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 75 73 te3_free() is us
2df30 65 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 ed to free idxPt
2df40 72 20 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49 r if needToFreeI
2df50 64 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a dxPtr is true..*
2df60 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 *.** The orderBy
2df70 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 Consumed means t
2df80 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 hat output from
2df90 78 46 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63 xFilter will occ
2dfa0 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 ur in.** the cor
2dfb0 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 rect order to sa
2dfc0 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 tisfy the ORDER
2dfd0 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 BY clause so tha
2dfe0 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a t no separate.**
2dff0 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 sorting step is
2e000 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a required..**.**
2e010 20 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f The estimatedCo
2e020 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 st value is an e
2e030 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 stimate of the c
2e040 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 ost of doing the
2e050 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c .** particular l
2e060 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 ookup. A full s
2e070 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 can of a table w
2e080 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 ith N entries sh
2e090 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 ould have.** a c
2e0a0 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e ost of N. A bin
2e0b0 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 ary search of a
2e0c0 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 table of N entri
2e0d0 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 es should have a
2e0e0 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 .** cost of appr
2e0f0 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 oximately log(N)
2e100 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
2e110 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69 erface is experi
2e120 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 mental and is su
2e130 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 bject to change
2e140 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e or.** removal in
2e150 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
2e160 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 of SQLite..*/.s
2e170 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e truct sqlite3_in
2e180 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 dex_info {. /*
2e190 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 Inputs */. int
2e1a0 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 nConstraint;
2e1b0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 /* Number
2e1c0 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 of entries in a
2e1d0 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 Constraint */.
2e1e0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
2e1f0 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 ndex_constraint
2e200 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 {. int iColu
2e210 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 mn;
2e220 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 /* Column on le
2e230 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 ft-hand side of
2e240 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 constraint */.
2e250 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 unsigned char
2e260 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 op; /*
2e270 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 Constraint opera
2e280 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 tor */. unsi
2e290 67 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 gned char usable
2e2a0 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 ; /* True if
2e2b0 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 this constraint
2e2c0 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 is usable */.
2e2d0 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 int iTermOffs
2e2e0 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 et; /*
2e2f0 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 Used internally
2e300 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f - xBestIndex sho
2e310 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 uld ignore */.
2e320 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 } *aConstraint;
2e330 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 /* Ta
2e340 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 ble of WHERE cla
2e350 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 use constraints
2e360 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 */. int nOrderB
2e370 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 y;
2e380 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 /* Number of ter
2e390 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 ms in the ORDER
2e3a0 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 BY clause */. s
2e3b0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e truct sqlite3_in
2e3c0 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 dex_orderby {.
2e3d0 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 int iColumn;
2e3e0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
2e3f0 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f Column number */
2e400 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 . unsigned c
2e410 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 har desc;
2e420 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 /* True for DESC
2e430 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 . False for ASC
2e440 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 . */. } *aOrder
2e450 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 By;
2e460 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 /* The ORDER B
2e470 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a Y clause */. /*
2e480 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 Outputs */. st
2e490 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 ruct sqlite3_ind
2e4a0 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 ex_constraint_us
2e4b0 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 age {. int ar
2e4c0 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 gvIndex;
2e4d0 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e /* if >0, con
2e4e0 73 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 straint is part
2e4f0 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 of argv to xFilt
2e500 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e er */. unsign
2e510 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 ed char omit;
2e520 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 /* Do not cod
2e530 65 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 e a test for thi
2e540 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a s constraint */.
2e550 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 } *aConstraint
2e560 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 Usage;. int idx
2e570 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 Num;
2e580 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 /* Number us
2e590 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 ed to identify t
2e5a0 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 he index */. ch
2e5b0 61 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 ar *idxStr;
2e5c0 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 /* Stri
2e5d0 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 ng, possibly obt
2e5e0 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 ained from sqlit
2e5f0 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 e3_malloc */. i
2e600 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 nt needToFreeIdx
2e610 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 Str; /* Fre
2e620 65 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 e idxStr using s
2e630 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 qlite3_free() if
2e640 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f true */. int o
2e650 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 rderByConsumed;
2e660 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 /* True if
2e670 20 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 output is alrea
2e680 64 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 dy ordered */.
2e690 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 double estimated
2e6a0 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 Cost; /* Es
2e6b0 74 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 timated cost of
2e6c0 75 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 using this index
2e6d0 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 */.};.#define S
2e6e0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 QLITE_INDEX_CONS
2e6f0 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 TRAINT_EQ 2.#
2e700 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
2e710 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 DEX_CONSTRAINT_G
2e720 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 T 4.#define S
2e730 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 QLITE_INDEX_CONS
2e740 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 TRAINT_LE 8.#
2e750 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
2e760 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c DEX_CONSTRAINT_L
2e770 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 T 16.#define
2e780 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e SQLITE_INDEX_CON
2e790 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 STRAINT_GE 32
2e7a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2e7b0 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
2e7c0 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a _MATCH 64../*.**
2e7d0 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 CAPI3REF: Regis
2e7e0 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 ter A Virtual Ta
2e7f0 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 ble Implementati
2e800 6f 6e 20 7b 48 31 38 32 30 30 7d 20 3c 53 32 30 on {H18200} <S20
2e810 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 400>.** EXPERIME
2e820 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 NTAL.**.** This
2e830 72 6f 75 74 69 6e 65 20 69 73 20 75 73 65 64 20 routine is used
2e840 74 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 to register a ne
2e850 77 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 77 69 w module name wi
2e860 74 68 20 61 0a 2a 2a 20 5b 64 61 74 61 62 61 73 th a.** [databas
2e870 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 e connection].
2e880 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 Module names mus
2e890 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 t be registered
2e8a0 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69 before.** creati
2e8b0 6e 67 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 ng new virtual t
2e8c0 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d 6f 64 ables on the mod
2e8d0 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 20 75 ule, or before u
2e8e0 73 69 6e 67 0a 2a 2a 20 70 72 65 65 78 69 73 74 sing.** preexist
2e8f0 69 6e 67 20 76 69 72 74 75 61 6c 20 74 61 62 6c ing virtual tabl
2e900 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 es of the module
2e910 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
2e920 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69 erface is experi
2e930 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 mental and is su
2e940 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 bject to change
2e950 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e or.** removal in
2e960 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
2e970 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 of SQLite..*/.S
2e980 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 QLITE_EXPERIMENT
2e990 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 AL int sqlite3_c
2e9a0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 reate_module(.
2e9b0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
2e9c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 /* SQ
2e9d0 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 Lite connection
2e9e0 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 to register modu
2e9f0 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e le with */. con
2ea00 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
2ea10 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 /* Name
2ea20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f of the module */
2ea30 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 . const sqlite3
2ea40 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a _module *, /*
2ea50 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 Methods for the
2ea60 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 module */. voi
2ea70 64 20 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 d *
2ea80 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e /* Clien
2ea90 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 t data for xCrea
2eaa0 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 te/xConnect */.)
2eab0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2eac0 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 56 69 F: Register A Vi
2ead0 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c rtual Table Impl
2eae0 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 31 38 32 ementation {H182
2eaf0 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 10} <S20400>.**
2eb00 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
2eb10 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
2eb20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 is identical to
2eb30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 the [sqlite3_cre
2eb40 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6d 65 ate_module()] me
2eb50 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 65 thod above,.** e
2eb60 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c xcept that it al
2eb70 6c 6f 77 73 20 61 20 64 65 73 74 72 75 63 74 6f lows a destructo
2eb80 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 r function to be
2eb90 20 73 70 65 63 69 66 69 65 64 2e 20 49 74 20 69 specified. It i
2eba0 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 20 65 s.** even more e
2ebb0 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 68 61 6e xperimental than
2ebc0 20 74 68 65 20 72 65 73 74 20 6f 66 20 74 68 65 the rest of the
2ebd0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 virtual tables
2ebe0 41 50 49 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 API..*/.SQLITE_E
2ebf0 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 XPERIMENTAL int
2ec00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d sqlite3_create_m
2ec10 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 odule_v2(. sqli
2ec20 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
2ec30 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 /* SQLite
2ec40 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 connection to r
2ec50 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 egister module w
2ec60 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ith */. const c
2ec70 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 har *zName,
2ec80 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 /* Name of t
2ec90 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 he module */. c
2eca0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 onst sqlite3_mod
2ecb0 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 ule *, /* Met
2ecc0 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 hods for the mod
2ecd0 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c ule */. void *,
2ece0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2ecf0 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 /* Client da
2ed00 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 ta for xCreate/x
2ed10 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 Connect */. voi
2ed20 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 d(*xDestroy)(voi
2ed30 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c d*) /* Modul
2ed40 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e e destructor fun
2ed50 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a ction */.);../*.
2ed60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 ** CAPI3REF: Vir
2ed70 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 tual Table Insta
2ed80 6e 63 65 20 4f 62 6a 65 63 74 20 7b 48 31 38 30 nce Object {H180
2ed90 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 10} <S20400>.**
2eda0 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 KEYWORDS: sqlite
2edb0 33 5f 76 74 61 62 0a 2a 2a 20 45 58 50 45 52 49 3_vtab.** EXPERI
2edc0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 MENTAL.**.** Eve
2edd0 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d ry module implem
2ede0 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 entation uses a
2edf0 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20 subclass of the
2ee00 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 following struct
2ee10 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 ure.** to descri
2ee20 62 65 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 be a particular
2ee30 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
2ee40 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 73 75 module. Each su
2ee50 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 bclass will.** b
2ee60 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 e tailored to th
2ee70 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 e specific needs
2ee80 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 of the module i
2ee90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a mplementation..*
2eea0 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 * The purpose of
2eeb0 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 this superclass
2eec0 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 is to define ce
2eed0 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 rtain fields tha
2eee0 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 t are.** common
2eef0 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d to all module im
2ef00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a plementations..*
2ef10 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 *.** Virtual tab
2ef20 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 les methods can
2ef30 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 set an error mes
2ef40 73 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e sage by assignin
2ef50 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 g a.** string ob
2ef60 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
2ef70 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 ite3_mprintf()]
2ef80 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 to zErrMsg. The
2ef90 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a method should.*
2efa0 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 * take care that
2efb0 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e any prior strin
2efc0 67 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20 g is freed by a
2efd0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
2efe0 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f _free()].** prio
2eff0 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 r to assigning a
2f000 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a new string to z
2f010 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74 ErrMsg. After t
2f020 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
2f030 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 .** is delivered
2f040 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e up to the clien
2f050 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 t application, t
2f060 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 he string will b
2f070 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a e automatically.
2f080 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 ** freed by sqli
2f090 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 te3_free() and t
2f0a0 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 he zErrMsg field
2f0b0 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e will be zeroed.
2f0c0 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 20 73 Note.** that s
2f0d0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 qlite3_mprintf()
2f0e0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66 72 65 and sqlite3_fre
2f0f0 65 28 29 20 61 72 65 20 75 73 65 64 20 6f 6e 20 e() are used on
2f100 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c the zErrMsg fiel
2f110 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72 74 75 d.** since virtu
2f120 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f al tables are co
2f130 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e 74 mmonly implement
2f140 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65 20 65 ed in loadable e
2f150 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63 68 0a xtensions which.
2f160 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 61 ** do not have a
2f170 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74 65 33 ccess to sqlite3
2f180 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73 71 6c MPrintf() or sql
2f190 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2a 0a 2a ite3Free()..**.*
2f1a0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
2f1b0 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c is experimental
2f1c0 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 and is subject
2f1d0 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 to change or.**
2f1e0 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 removal in futur
2f1f0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
2f200 4c 69 74 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 Lite..*/.struct
2f210 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 sqlite3_vtab {.
2f220 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d const sqlite3_m
2f230 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 odule *pModule;
2f240 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 /* The module f
2f250 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 or this virtual
2f260 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e table */. int n
2f270 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 Ref;
2f280 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 /* Us
2f290 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f ed internally */
2f2a0 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 . char *zErrMsg
2f2b0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ;
2f2c0 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 /* Error mess
2f2d0 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 age from sqlite3
2f2e0 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 _mprintf() */.
2f2f0 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 /* Virtual table
2f300 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
2f310 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 will typically
2f320 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 add additional f
2f330 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a ields */.};../*.
2f340 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 ** CAPI3REF: Vir
2f350 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f tual Table Curso
2f360 72 20 4f 62 6a 65 63 74 20 20 7b 48 31 38 30 32 r Object {H1802
2f370 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 0} <S20400>.** K
2f380 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 EYWORDS: sqlite3
2f390 5f 76 74 61 62 5f 63 75 72 73 6f 72 0a 2a 2a 20 _vtab_cursor.**
2f3a0 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
2f3b0 2a 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 ** Every module
2f3c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 implementation u
2f3d0 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f ses a subclass o
2f3e0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
2f3f0 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 structure.** to
2f400 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72 73 describe cursors
2f410 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f that point into
2f420 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 the virtual tab
2f430 6c 65 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a le and are used.
2f440 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 ** to loop throu
2f450 67 68 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 gh the virtual t
2f460 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61 able. Cursors a
2f470 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 re created using
2f480 20 74 68 65 0a 2a 2a 20 78 4f 70 65 6e 20 6d 65 the.** xOpen me
2f490 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 thod of the modu
2f4a0 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 le. Each module
2f4b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
2f4c0 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 will define.** t
2f4d0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 he content of a
2f4e0 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 cursor structure
2f4f0 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e to suit its own
2f500 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 needs..**.** Th
2f510 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 is superclass ex
2f520 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f ists in order to
2f530 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f define fields o
2f540 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 f the cursor tha
2f550 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 t.** are common
2f560 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 to all implement
2f570 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ations..**.** Th
2f580 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 is interface is
2f590 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 experimental and
2f5a0 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 is subject to c
2f5b0 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f hange or.** remo
2f5c0 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 val in future re
2f5d0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
2f5e0 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 ..*/.struct sqli
2f5f0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 te3_vtab_cursor
2f600 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 {. sqlite3_vtab
2f610 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a *pVtab; /*
2f620 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f Virtual table o
2f630 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f f this cursor */
2f640 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 . /* Virtual ta
2f650 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ble implementati
2f660 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c ons will typical
2f670 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 ly add additiona
2f680 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a l fields */.};..
2f690 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2f6a0 44 65 63 6c 61 72 65 20 54 68 65 20 53 63 68 65 Declare The Sche
2f6b0 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61 6c 20 ma Of A Virtual
2f6c0 54 61 62 6c 65 20 7b 48 31 38 32 38 30 7d 20 3c Table {H18280} <
2f6d0 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S20400>.** EXPER
2f6e0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
2f6f0 65 20 78 43 72 65 61 74 65 20 61 6e 64 20 78 43 e xCreate and xC
2f700 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73 20 6f onnect methods o
2f710 66 20 61 20 6d 6f 64 75 6c 65 20 75 73 65 20 74 f a module use t
2f720 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 he following API
2f730 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74 .** to declare t
2f740 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e he format (the n
2f750 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 ames and datatyp
2f760 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e es of the column
2f770 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 s) of.** the vir
2f780 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79 tual tables they
2f790 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a implement..**.*
2f7a0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
2f7b0 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c is experimental
2f7c0 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 and is subject
2f7d0 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 to change or.**
2f7e0 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 removal in futur
2f7f0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
2f800 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f Lite..*/.SQLITE_
2f810 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 EXPERIMENTAL int
2f820 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 sqlite3_declare
2f830 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 _vtab(sqlite3*,
2f840 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 72 65 const char *zCre
2f850 61 74 65 54 61 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a ateTable);../*.*
2f860 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65 72 * CAPI3REF: Over
2f870 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 load A Function
2f880 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 For A Virtual Ta
2f890 62 6c 65 20 7b 48 31 38 33 30 30 7d 20 3c 53 32 ble {H18300} <S2
2f8a0 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 0400>.** EXPERIM
2f8b0 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 56 69 72 74 ENTAL.**.** Virt
2f8c0 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70 ual tables can p
2f8d0 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69 rovide alternati
2f8e0 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ve implementatio
2f8f0 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a ns of functions.
2f900 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 78 46 69 ** using the xFi
2f910 6e 64 46 75 6e 63 74 69 6f 6e 20 6d 65 74 68 6f ndFunction metho
2f920 64 2e 20 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 d. But global v
2f930 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 ersions of those
2f940 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 functions.** mu
2f950 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 st exist in orde
2f960 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 r to be overload
2f970 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 ed..**.** This A
2f980 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 PI makes sure a
2f990 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f global version o
2f9a0 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 f a function wit
2f9b0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a h a particular.*
2f9c0 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 * name and numbe
2f9d0 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 r of parameters
2f9e0 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 exists. If no s
2f9f0 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 uch function exi
2fa00 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 sts.** before th
2fa10 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 is API is called
2fa20 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e , a new function
2fa30 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 is created. Th
2fa40 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2fa50 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 .** of the new f
2fa60 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 unction always c
2fa70 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 auses an excepti
2fa80 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e on to be thrown.
2fa90 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 So.** the new
2faa0 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 function is not
2fab0 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e good for anythin
2fac0 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 g by itself. It
2fad0 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 s only.** purpos
2fae0 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 e is to be a pla
2faf0 63 65 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f ceholder functio
2fb00 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 n that can be ov
2fb10 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 76 erloaded.** by v
2fb20 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 0a 2a irtual tables..*
2fb30 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 73 68 *.** This API sh
2fb40 6f 75 6c 64 20 62 65 20 63 6f 6e 73 69 64 65 72 ould be consider
2fb50 65 64 20 70 61 72 74 20 6f 66 20 74 68 65 20 76 ed part of the v
2fb60 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 irtual table int
2fb70 65 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69 63 68 erface,.** which
2fb80 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c is experimental
2fb90 20 61 6e 64 20 73 75 62 6a 65 63 74 20 74 6f 20 and subject to
2fba0 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 change..*/.SQLIT
2fbb0 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 E_EXPERIMENTAL i
2fbc0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c nt sqlite3_overl
2fbd0 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c oad_function(sql
2fbe0 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 ite3*, const cha
2fbf0 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e r *zFuncName, in
2fc00 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t nArg);../*.**
2fc10 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f The interface to
2fc20 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 the virtual-tab
2fc30 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 le mechanism def
2fc40 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b ined above (back
2fc50 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d up.** to a comm
2fc60 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 ent remarkably s
2fc70 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f imilar to this o
2fc80 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 ne) is currently
2fc90 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 considered.** t
2fca0 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 o be experimenta
2fcb0 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 l. The interfac
2fcc0 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 e might change i
2fcd0 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 n incompatible w
2fce0 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 ays..** If this
2fcf0 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 is a problem for
2fd00 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 you, do not use
2fd10 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 the interface a
2fd20 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a t this time..**.
2fd30 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 ** When the virt
2fd40 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e ual-table mechan
2fd50 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 ism stabilizes,
2fd60 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 we will declare
2fd70 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 the.** interface
2fd80 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 fixed, support
2fd90 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c it indefinitely,
2fda0 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 and remove this
2fdb0 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a comment..**.***
2fdc0 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c *** EXPERIMENTAL
2fdd0 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 - subject to ch
2fde0 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 ange without not
2fdf0 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ice ************
2fe00 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 **.*/../*.** CAP
2fe10 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 I3REF: A Handle
2fe20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 To An Open BLOB
2fe30 7b 48 31 37 38 30 30 7d 20 3c 53 33 30 32 33 30 {H17800} <S30230
2fe40 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b >.** KEYWORDS: {
2fe50 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c BLOB handle} {BL
2fe60 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a OB handles}.**.*
2fe70 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
2fe80 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 this object rep
2fe90 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 resents an open
2fea0 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a BLOB on which.**
2feb0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
2fec0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 pen | incrementa
2fed0 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 l BLOB I/O] can
2fee0 62 65 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a be performed..**
2fef0 20 4f 62 6a 65 63 74 73 20 6f 66 20 74 68 69 73 Objects of this
2ff00 20 74 79 70 65 20 61 72 65 20 63 72 65 61 74 65 type are create
2ff10 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c d by [sqlite3_bl
2ff20 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e ob_open()].** an
2ff30 64 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b d destroyed by [
2ff40 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f sqlite3_blob_clo
2ff50 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 se()]..** The [s
2ff60 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 qlite3_blob_read
2ff70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
2ff80 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 _blob_write()] i
2ff90 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e nterfaces.** can
2ffa0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 61 64 be used to read
2ffb0 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 or write small
2ffc0 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 subsections of t
2ffd0 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 54 68 65 20 he BLOB..** The
2ffe0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 [sqlite3_blob_by
2fff0 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tes()] interface
30000 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a returns the siz
30010 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 69 6e e of the BLOB in
30020 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 bytes..*/.typed
30030 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
30040 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 3_blob sqlite3_b
30050 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 lob;../*.** CAPI
30060 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 3REF: Open A BLO
30070 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 B For Incrementa
30080 6c 20 49 2f 4f 20 7b 48 31 37 38 31 30 7d 20 3c l I/O {H17810} <
30090 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S30230>.**.** Th
300a0 69 73 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70 is interfaces op
300b0 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 ens a [BLOB hand
300c0 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 le | handle] to
300d0 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 the BLOB located
300e0 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c .** in row iRow,
300f0 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c column zColumn,
30100 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e table zTable in
30110 20 64 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a database zDb;.*
30120 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 * in other words
30130 2c 20 74 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 , the same BLOB
30140 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 that would be se
30150 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a lected by:.**.**
30160 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 <pre>.** SE
30170 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f LECT zColumn FRO
30180 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 M zDb.zTable WHE
30190 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f RE [rowid] = iRo
301a0 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e w;.** </pre> {EN
301b0 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 D}.**.** If the
301c0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 flags parameter
301d0 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 is non-zero, the
301e0 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 the BLOB is ope
301f0 6e 65 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 ned for read.**
30200 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73 and write access
30210 2e 20 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c . If it is zero,
30220 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 the BLOB is ope
30230 6e 65 64 20 66 6f 72 20 72 65 61 64 20 61 63 63 ned for read acc
30240 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 ess..**.** Note
30250 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 that the databas
30260 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 e name is not th
30270 65 20 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 e filename that
30280 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 contains.** the
30290 64 61 74 61 62 61 73 65 20 62 75 74 20 72 61 74 database but rat
302a0 68 65 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 her the symbolic
302b0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
302c0 61 62 61 73 65 20 74 68 61 74 0a 2a 2a 20 69 73 abase that.** is
302d0 20 61 73 73 69 67 6e 65 64 20 77 68 65 6e 20 74 assigned when t
302e0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 63 he database is c
302f0 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b onnected using [
30300 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 46 6f 72 20 ATTACH]..** For
30310 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 the main databas
30320 65 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 e file, the data
30330 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 base name is "ma
30340 69 6e 22 2e 0a 2a 2a 20 46 6f 72 20 54 45 4d 50 in"..** For TEMP
30350 20 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 tables, the dat
30360 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 abase name is "t
30370 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 emp"..**.** On s
30380 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f uccess, [SQLITE_
30390 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 OK] is returned
303a0 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f and the new [BLO
303b0 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 B handle] is wri
303c0 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c tten.** to *ppBl
303d0 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e ob. Otherwise an
303e0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 [error code] is
303f0 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e returned and an
30400 79 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e 0a y value written.
30410 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 20 73 68 ** to *ppBlob sh
30420 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 ould not be used
30430 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 0a by the caller..
30440 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
30450 20 73 65 74 73 20 74 68 65 20 5b 64 61 74 61 62 sets the [datab
30460 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
30470 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d error code and m
30480 65 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 essage.** access
30490 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 ible via [sqlite
304a0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 3_errcode()] and
304b0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
304c0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ()]..**.** If th
304d0 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f e row that a BLO
304e0 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 B handle points
304f0 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62 to is modified b
30500 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d y an.** [UPDATE]
30510 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 , [DELETE], or b
30520 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 y [ON CONFLICT]
30530 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 side-effects.**
30540 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 then the BLOB ha
30550 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61 ndle is marked a
30560 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 s "expired"..**
30570 54 68 69 73 20 69 73 20 74 72 75 65 20 69 66 20 This is true if
30580 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 any column of th
30590 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64 e row is changed
305a0 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a , even a column.
305b0 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 ** other than th
305c0 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 e one the BLOB h
305d0 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e andle is open on
305e0 2e 0a 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 5b 73 ..** Calls to [s
305f0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 qlite3_blob_read
30600 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
30610 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 _blob_write()] f
30620 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 20 or.** a expired
30630 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 6c BLOB handle fail
30640 20 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e 20 with an return
30650 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f code of [SQLITE_
30660 41 42 4f 52 54 5d 2e 0a 2a 2a 20 43 68 61 6e 67 ABORT]..** Chang
30670 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 es written into
30680 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 a BLOB prior to
30690 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69 6e the BLOB expirin
306a0 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c g are not.** rol
306b0 6c 62 61 63 6b 20 62 79 20 74 68 65 20 65 78 70 lback by the exp
306c0 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 iration of the B
306d0 4c 4f 42 2e 20 20 53 75 63 68 20 63 68 61 6e 67 LOB. Such chang
306e0 65 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c es will eventual
306f0 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 ly.** commit if
30700 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 the transaction
30710 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d continues to com
30720 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 pletion..**.** R
30730 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
30740 5b 48 31 37 38 31 33 5d 20 5b 48 31 37 38 31 34 [H17813] [H17814
30750 5d 20 5b 48 31 37 38 31 36 5d 20 5b 48 31 37 38 ] [H17816] [H178
30760 31 39 5d 20 5b 48 31 37 38 32 31 5d 20 5b 48 31 19] [H17821] [H1
30770 37 38 32 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 7824].*/.int sql
30780 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a ite3_blob_open(.
30790 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f sqlite3*,. co
307a0 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 nst char *zDb,.
307b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 const char *zTa
307c0 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 ble,. const cha
307d0 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 r *zColumn,. sq
307e0 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 lite3_int64 iRow
307f0 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 ,. int flags,.
30800 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a sqlite3_blob **
30810 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a ppBlob.);../*.**
30820 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 65 CAPI3REF: Close
30830 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 20 7b A BLOB Handle {
30840 48 31 37 38 33 30 7d 20 3c 53 33 30 32 33 30 3e H17830} <S30230>
30850 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 73 20 61 6e .**.** Closes an
30860 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 open [BLOB hand
30870 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 le]..**.** Closi
30880 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 ng a BLOB shall
30890 63 61 75 73 65 20 74 68 65 20 63 75 72 72 65 6e cause the curren
308a0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f t transaction to
308b0 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 commit.** if th
308c0 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 ere are no other
308d0 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 BLOBs, no pendi
308e0 6e 67 20 70 72 65 70 61 72 65 64 20 73 74 61 74 ng prepared stat
308f0 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a ements, and the.
30900 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
30910 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b 61 75 ection is in [au
30920 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a tocommit mode]..
30930 2a 2a 20 49 66 20 61 6e 79 20 77 72 69 74 65 73 ** If any writes
30940 20 77 65 72 65 20 6d 61 64 65 20 74 6f 20 74 68 were made to th
30950 65 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 e BLOB, they mig
30960 68 74 20 62 65 20 68 65 6c 64 20 69 6e 20 63 61 ht be held in ca
30970 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 che.** until the
30980 20 63 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e close operation
30990 20 69 66 20 74 68 65 79 20 77 69 6c 6c 20 66 69 if they will fi
309a0 74 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 43 t. {END}.**.** C
309b0 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 losing the BLOB
309c0 6f 66 74 65 6e 20 66 6f 72 63 65 73 20 74 68 65 often forces the
309d0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 changes.** out
309e0 74 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 to disk and so i
309f0 66 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 f any I/O errors
30a00 20 6f 63 63 75 72 2c 20 74 68 65 79 20 77 69 6c occur, they wil
30a10 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a l likely occur.*
30a20 2a 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 * at the time wh
30a30 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20 63 en the BLOB is c
30a40 6c 6f 73 65 64 2e 20 20 7b 48 31 37 38 33 33 7d losed. {H17833}
30a50 20 41 6e 79 20 65 72 72 6f 72 73 20 74 68 61 74 Any errors that
30a60 20 6f 63 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a occur during.**
30a70 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 72 65 70 closing are rep
30a80 6f 72 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a orted as a non-z
30a90 65 72 6f 20 72 65 74 75 72 6e 20 76 61 6c 75 65 ero return value
30aa0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 42 4c 4f 42 ..**.** The BLOB
30ab0 20 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e is closed uncon
30ac0 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 ditionally. Eve
30ad0 6e 20 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e n if this routin
30ae0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 e returns.** an
30af0 65 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 error code, the
30b00 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c BLOB is still cl
30b10 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 osed..**.** Requ
30b20 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
30b30 37 38 33 33 5d 20 5b 48 31 37 38 33 36 5d 20 5b 7833] [H17836] [
30b40 48 31 37 38 33 39 5d 0a 2a 2f 0a 69 6e 74 20 73 H17839].*/.int s
30b50 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 qlite3_blob_clos
30b60 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a e(sqlite3_blob *
30b70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
30b80 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 53 EF: Return The S
30b90 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 ize Of An Open B
30ba0 4c 4f 42 20 7b 48 31 37 38 34 30 7d 20 3c 53 33 LOB {H17840} <S3
30bb0 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 0230>.**.** Retu
30bc0 72 6e 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20 rns the size in
30bd0 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f bytes of the BLO
30be0 42 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 B accessible via
30bf0 20 74 68 65 20 6f 70 65 6e 0a 2a 2a 20 5b 5d 42 the open.** []B
30c00 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69 LOB handle] in i
30c10 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 ts only argument
30c20 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
30c30 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 34 33 ents:.** [H17843
30c40 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ].*/.int sqlite3
30c50 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 _blob_bytes(sqli
30c60 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a te3_blob *);../*
30c70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
30c80 61 64 20 44 61 74 61 20 46 72 6f 6d 20 41 20 42 ad Data From A B
30c90 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c LOB Incrementall
30ca0 79 20 7b 48 31 37 38 35 30 7d 20 3c 53 33 30 32 y {H17850} <S302
30cb0 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 30>.**.** This f
30cc0 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 unction is used
30cd0 74 6f 20 72 65 61 64 20 64 61 74 61 20 66 72 6f to read data fro
30ce0 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 m an open [BLOB
30cf0 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a handle] into a.*
30d00 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 * caller-supplie
30d10 64 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74 65 d buffer. N byte
30d20 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f s of data are co
30d30 70 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 pied into buffer
30d40 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 6f Z.** from the o
30d50 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 pen BLOB, starti
30d60 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 ng at offset iOf
30d70 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f fset..**.** If o
30d80 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 ffset iOffset is
30d90 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 less than N byt
30da0 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 es from the end
30db0 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 of the BLOB,.**
30dc0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
30dd0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e s returned and n
30de0 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 20 o data is read.
30df0 20 49 66 20 4e 20 6f 72 20 69 4f 66 66 73 65 74 If N or iOffset
30e00 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e is.** less than
30e10 20 7a 65 72 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 zero, [SQLITE_E
30e20 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 RROR] is returne
30e30 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 d and no data is
30e40 20 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 read..**.** An
30e50 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 attempt to read
30e60 66 72 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20 from an expired
30e70 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 [BLOB handle] fa
30e80 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 ils with an.** e
30e90 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 rror code of [SQ
30ea0 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a LITE_ABORT]..**.
30eb0 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 ** On success, S
30ec0 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 QLITE_OK is retu
30ed0 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 rned..** Otherwi
30ee0 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f se, an [error co
30ef0 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e de] or an [exten
30f00 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 ded error code]
30f10 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
30f20 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
30f30 0a 2a 2a 20 5b 48 31 37 38 35 33 5d 20 5b 48 31 .** [H17853] [H1
30f40 37 38 35 36 5d 20 5b 48 31 37 38 35 39 5d 20 5b 7856] [H17859] [
30f50 48 31 37 38 36 32 5d 20 5b 48 31 37 38 36 33 5d H17862] [H17863]
30f60 20 5b 48 31 37 38 36 35 5d 20 5b 48 31 37 38 36 [H17865] [H1786
30f70 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 8].*/.int sqlite
30f80 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 3_blob_read(sqli
30f90 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 te3_blob *, void
30fa0 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 20 *Z, int N, int
30fb0 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a iOffset);../*.**
30fc0 20 43 41 50 49 33 52 45 46 3a 20 57 72 69 74 65 CAPI3REF: Write
30fd0 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f Data Into A BLO
30fe0 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 B Incrementally
30ff0 7b 48 31 37 38 37 30 7d 20 3c 53 33 30 32 33 30 {H17870} <S30230
31000 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e >.**.** This fun
31010 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f ction is used to
31020 20 77 72 69 74 65 20 64 61 74 61 20 69 6e 74 6f write data into
31030 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 an open [BLOB h
31040 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a andle] from a.**
31050 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 caller-supplied
31060 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74 65 73 buffer. N bytes
31070 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 of data are cop
31080 69 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66 ied from the buf
31090 66 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 fer Z.** into th
310a0 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 e open BLOB, sta
310b0 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 rting at offset
310c0 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 iOffset..**.** I
310d0 66 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 f the [BLOB hand
310e0 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 le] passed as th
310f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
31100 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 was not opened
31110 66 6f 72 0a 2a 2a 20 77 72 69 74 69 6e 67 20 28 for.** writing (
31120 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 the flags parame
31130 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
31140 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 77 61 73 blob_open()] was
31150 20 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 zero),.** this
31160 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
31170 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c [SQLITE_READONL
31180 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 Y]..**.** This f
31190 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 unction may only
311a0 20 6d 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74 modify the cont
311b0 65 6e 74 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 ents of the BLOB
311c0 3b 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 ; it is.** not p
311d0 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 ossible to incre
311e0 61 73 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ase the size of
311f0 61 20 42 4c 4f 42 20 75 73 69 6e 67 20 74 68 69 a BLOB using thi
31200 73 20 41 50 49 2e 0a 2a 2a 20 49 66 20 6f 66 66 s API..** If off
31210 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c set iOffset is l
31220 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 ess than N bytes
31230 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 from the end of
31240 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 the BLOB,.** [S
31250 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 QLITE_ERROR] is
31260 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 returned and no
31270 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e data is written.
31280 20 20 49 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 If N is.** les
31290 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c s than zero [SQL
312a0 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 ITE_ERROR] is re
312b0 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 turned and no da
312c0 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a ta is written..*
312d0 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d 70 74 20 *.** An attempt
312e0 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65 to write to an e
312f0 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e xpired [BLOB han
31300 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 dle] fails with
31310 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 an.** error code
31320 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 of [SQLITE_ABOR
31330 54 5d 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 T]. Writes to t
31340 68 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63 63 he BLOB that occ
31350 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20 urred.** before
31360 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 the [BLOB handle
31370 5d 20 65 78 70 69 72 65 64 20 61 72 65 20 6e 6f ] expired are no
31380 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 t rolled back by
31390 20 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74 69 the.** expirati
313a0 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c 65 on of the handle
313b0 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 , though of cour
313c0 73 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 se those changes
313d0 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20 62 might.** have b
313e0 65 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e 20 een overwritten
313f0 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 by the statement
31400 20 74 68 61 74 20 65 78 70 69 72 65 64 20 74 68 that expired th
31410 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a e BLOB handle.**
31420 20 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e 64 or by other ind
31430 65 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d 65 ependent stateme
31440 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 nts..**.** On su
31450 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b ccess, SQLITE_OK
31460 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
31470 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 20 Otherwise, an
31480 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 [error code] or
31490 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 an [extended err
314a0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
314b0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 rned..**.** Requ
314c0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
314d0 37 38 37 33 5d 20 5b 48 31 37 38 37 34 5d 20 5b 7873] [H17874] [
314e0 48 31 37 38 37 35 5d 20 5b 48 31 37 38 37 36 5d H17875] [H17876]
314f0 20 5b 48 31 37 38 37 37 5d 20 5b 48 31 37 38 37 [H17877] [H1787
31500 39 5d 20 5b 48 31 37 38 38 32 5d 20 5b 48 31 37 9] [H17882] [H17
31510 38 38 35 5d 0a 2a 2a 20 5b 48 31 37 38 38 38 5d 885].** [H17888]
31520 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
31530 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c 69 74 blob_write(sqlit
31540 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 e3_blob *, const
31550 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c void *z, int n,
31560 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a int iOffset);..
31570 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
31580 56 69 72 74 75 61 6c 20 46 69 6c 65 20 53 79 73 Virtual File Sys
31590 74 65 6d 20 4f 62 6a 65 63 74 73 20 7b 48 31 31 tem Objects {H11
315a0 32 30 30 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 200} <S20100>.**
315b0 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 66 69 .** A virtual fi
315c0 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29 20 69 lesystem (VFS) i
315d0 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 s an [sqlite3_vf
315e0 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 61 s] object.** tha
315f0 74 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 6f t SQLite uses to
31600 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69 74 interact.** wit
31610 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 h the underlying
31620 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
31630 6d 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74 65 20 m. Most SQLite
31640 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69 74 68 builds come with
31650 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66 a.** single def
31660 61 75 6c 74 20 56 46 53 20 74 68 61 74 20 69 73 ault VFS that is
31670 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 appropriate for
31680 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 the host comput
31690 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 er..** New VFSes
316a0 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 can be register
316b0 65 64 20 61 6e 64 20 65 78 69 73 74 69 6e 67 20 ed and existing
316c0 56 46 53 65 73 20 63 61 6e 20 62 65 20 75 6e 72 VFSes can be unr
316d0 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68 egistered..** Th
316e0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 e following inte
316f0 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 rfaces are provi
31700 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ded..**.** The s
31710 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 qlite3_vfs_find(
31720 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
31730 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
31740 20 61 20 56 46 53 20 67 69 76 65 6e 20 69 74 73 a VFS given its
31750 20 6e 61 6d 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20 name..** Names
31760 61 72 65 20 63 61 73 65 20 73 65 6e 73 69 74 69 are case sensiti
31770 76 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 ve..** Names are
31780 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
31790 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a UTF-8 strings..
317a0 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6e ** If there is n
317b0 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 20 o match, a NULL
317c0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 pointer is retur
317d0 6e 65 64 2e 0a 2a 2a 20 49 66 20 7a 56 66 73 4e ned..** If zVfsN
317e0 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e ame is NULL then
317f0 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 the default VFS
31800 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
31810 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 61 72 .** New VFSes ar
31820 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 e registered wit
31830 68 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 h sqlite3_vfs_re
31840 67 69 73 74 65 72 28 29 2e 0a 2a 2a 20 45 61 63 gister()..** Eac
31850 68 20 6e 65 77 20 56 46 53 20 62 65 63 6f 6d 65 h new VFS become
31860 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 s the default VF
31870 53 20 69 66 20 74 68 65 20 6d 61 6b 65 44 66 6c S if the makeDfl
31880 74 20 66 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a t flag is set..*
31890 2a 20 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 * The same VFS c
318a0 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 an be registered
318b0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 multiple times
318c0 77 69 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a without injury..
318d0 2a 2a 20 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 ** To make an ex
318e0 69 73 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 isting VFS into
318f0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c the default VFS,
31900 20 72 65 67 69 73 74 65 72 20 69 74 20 61 67 61 register it aga
31910 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d in.** with the m
31920 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 akeDflt flag set
31930 2e 20 20 49 66 20 74 77 6f 20 64 69 66 66 65 72 . If two differ
31940 65 6e 74 20 56 46 53 65 73 20 77 69 74 68 20 74 ent VFSes with t
31950 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 he.** same name
31960 61 72 65 20 72 65 67 69 73 74 65 72 65 64 2c 20 are registered,
31970 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
31980 75 6e 64 65 66 69 6e 65 64 2e 20 20 49 66 20 61 undefined. If a
31990 0a 2a 2a 20 56 46 53 20 69 73 20 72 65 67 69 73 .** VFS is regis
319a0 74 65 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d tered with a nam
319b0 65 20 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f e that is NULL o
319c0 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e r an empty strin
319d0 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 g,.** then the b
319e0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
319f0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 55 6e 72 65 ined..**.** Unre
31a00 67 69 73 74 65 72 20 61 20 56 46 53 20 77 69 74 gister a VFS wit
31a10 68 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 h the sqlite3_vf
31a20 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 s_unregister() i
31a30 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 66 20 nterface..** If
31a40 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 the default VFS
31a50 69 73 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c is unregistered,
31a60 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20 another VFS is
31a70 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 chosen as.** the
31a80 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63 default. The c
31a90 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65 hoice for the ne
31aa0 77 20 56 46 53 20 69 73 20 61 72 62 69 74 72 61 w VFS is arbitra
31ab0 72 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ry..**.** Requir
31ac0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 31 32 ements:.** [H112
31ad0 30 33 5d 20 5b 48 31 31 32 30 36 5d 20 5b 48 31 03] [H11206] [H1
31ae0 31 32 30 39 5d 20 5b 48 31 31 32 31 32 5d 20 5b 1209] [H11212] [
31af0 48 31 31 32 31 35 5d 20 5b 48 31 31 32 31 38 5d H11215] [H11218]
31b00 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73 20 .*/.sqlite3_vfs
31b10 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e *sqlite3_vfs_fin
31b20 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 d(const char *zV
31b30 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c fsName);.int sql
31b40 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 ite3_vfs_registe
31b50 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 r(sqlite3_vfs*,
31b60 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 int makeDflt);.i
31b70 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 nt sqlite3_vfs_u
31b80 6e 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 nregister(sqlite
31b90 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 3_vfs*);../*.**
31ba0 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 65 CAPI3REF: Mutexe
31bb0 73 20 7b 48 31 37 30 30 30 7d 20 3c 53 32 30 30 s {H17000} <S200
31bc0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 00>.**.** The SQ
31bd0 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 Lite core uses t
31be0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f hese routines fo
31bf0 72 20 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63 r thread.** sync
31c00 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54 68 6f hronization. Tho
31c10 75 67 68 20 74 68 65 79 20 61 72 65 20 69 6e 74 ugh they are int
31c20 65 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 72 6e ended for intern
31c30 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c al.** use by SQL
31c40 69 74 65 2c 20 63 6f 64 65 20 74 68 61 74 20 6c ite, code that l
31c50 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c inks against SQL
31c60 69 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 ite is.** permit
31c70 74 65 64 20 74 6f 20 75 73 65 20 61 6e 79 20 6f ted to use any o
31c80 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
31c90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 ..**.** The SQLi
31ca0 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 63 te source code c
31cb0 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 ontains multiple
31cc0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
31cd0 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d 75 74 .** of these mut
31ce0 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e ex routines. An
31cf0 20 61 70 70 72 6f 70 72 69 61 74 65 20 69 6d 70 appropriate imp
31d00 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 lementation.** i
31d10 73 20 73 65 6c 65 63 74 65 64 20 61 75 74 6f 6d s selected autom
31d20 61 74 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70 atically at comp
31d30 69 6c 65 2d 74 69 6d 65 2e 20 20 54 68 65 20 66 ile-time. The f
31d40 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c ollowing.** impl
31d50 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72 65 20 ementations are
31d60 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 available in the
31d70 20 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a SQLite core:.**
31d80 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
31d90 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f SQLITE_MUTEX_
31da0 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 OS2.** <li> SQ
31db0 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 LITE_MUTEX_PTHRE
31dc0 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c AD.** <li> SQL
31dd0 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a 2a 2a ITE_MUTEX_W32.**
31de0 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d <li> SQLITE_M
31df0 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 UTEX_NOOP.** </u
31e00 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c l>.**.** The SQL
31e10 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 ITE_MUTEX_NOOP i
31e20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 mplementation is
31e30 20 61 20 73 65 74 20 6f 66 20 72 6f 75 74 69 6e a set of routin
31e40 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 es.** that does
31e50 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 no real locking
31e60 61 6e 64 20 69 73 20 61 70 70 72 6f 70 72 69 61 and is appropria
31e70 74 65 20 66 6f 72 20 75 73 65 20 69 6e 0a 2a 2a te for use in.**
31e80 20 61 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 a single-thread
31e90 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 ed application.
31ea0 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 The SQLITE_MUTE
31eb0 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 X_OS2,.** SQLITE
31ec0 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 2c 20 _MUTEX_PTHREAD,
31ed0 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 and SQLITE_MUTEX
31ee0 5f 57 33 32 20 69 6d 70 6c 65 6d 65 6e 74 61 74 _W32 implementat
31ef0 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 70 70 72 ions.** are appr
31f00 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 opriate for use
31f10 6f 6e 20 4f 53 2f 32 2c 20 55 6e 69 78 2c 20 61 on OS/2, Unix, a
31f20 6e 64 20 57 69 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a nd Windows..**.*
31f30 2a 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 * If SQLite is c
31f40 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
31f50 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 SQLITE_MUTEX_AP
31f60 50 44 45 46 20 70 72 65 70 72 6f 63 65 73 73 6f PDEF preprocesso
31f70 72 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e r.** macro defin
31f80 65 64 20 28 77 69 74 68 20 22 2d 44 53 51 4c 49 ed (with "-DSQLI
31f90 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 3d TE_MUTEX_APPDEF=
31fa0 31 22 29 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 1"), then no mut
31fb0 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 ex.** implementa
31fc0 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 tion is included
31fd0 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 with the librar
31fe0 79 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 y. In this case
31ff0 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 the.** applicati
32000 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 on must supply a
32010 20 63 75 73 74 6f 6d 20 6d 75 74 65 78 20 69 6d custom mutex im
32020 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 69 plementation usi
32030 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 ng the.** [SQLIT
32040 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 E_CONFIG_MUTEX]
32050 6f 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 71 option of the sq
32060 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 66 lite3_config() f
32070 75 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72 unction.** befor
32080 65 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 e calling sqlite
32090 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 6f 3_initialize() o
320a0 72 20 61 6e 79 20 6f 74 68 65 72 20 70 75 62 6c r any other publ
320b0 69 63 20 73 71 6c 69 74 65 33 5f 0a 2a 2a 20 66 ic sqlite3_.** f
320c0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6c unction that cal
320d0 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ls sqlite3_initi
320e0 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b alize()..**.** {
320f0 48 31 37 30 31 31 7d 20 54 68 65 20 73 71 6c 69 H17011} The sqli
32100 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 te3_mutex_alloc(
32110 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 61 ) routine alloca
32120 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 74 tes a new.** mut
32130 65 78 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 ex and returns a
32140 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 pointer to it.
32150 7b 48 31 37 30 31 32 7d 20 49 66 20 69 74 20 72 {H17012} If it r
32160 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 eturns NULL.** t
32170 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61 hat means that a
32180 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 mutex could not
32190 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 7b be allocated. {
321a0 48 31 37 30 31 33 7d 20 53 51 4c 69 74 65 0a 2a H17013} SQLite.*
321b0 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20 69 74 * will unwind it
321c0 73 20 73 74 61 63 6b 20 61 6e 64 20 72 65 74 75 s stack and retu
321d0 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 7b 48 31 rn an error. {H1
321e0 37 30 31 34 7d 20 54 68 65 20 61 72 67 75 6d 65 7014} The argume
321f0 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 nt.** to sqlite3
32200 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 _mutex_alloc() i
32210 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 s one of these i
32220 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
32230 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
32240 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 <li> SQLITE_MUT
32250 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 EX_FAST.** <li>
32260 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 SQLITE_MUTEX_RE
32270 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 CURSIVE.** <li>
32280 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
32290 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c ATIC_MASTER.** <
322a0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 li> SQLITE_MUTE
322b0 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 X_STATIC_MEM.**
322c0 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 <li> SQLITE_MUT
322d0 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a EX_STATIC_MEM2.*
322e0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d * <li> SQLITE_M
322f0 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 UTEX_STATIC_PRNG
32300 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
32310 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 _MUTEX_STATIC_LR
32320 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 U.** <li> SQLIT
32330 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c E_MUTEX_STATIC_L
32340 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a RU2.** </ul>.**.
32350 2a 2a 20 7b 48 31 37 30 31 35 7d 20 54 68 65 20 ** {H17015} The
32360 66 69 72 73 74 20 74 77 6f 20 63 6f 6e 73 74 61 first two consta
32370 6e 74 73 20 63 61 75 73 65 20 73 71 6c 69 74 65 nts cause sqlite
32380 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 3_mutex_alloc()
32390 74 6f 20 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e to create.** a n
323a0 65 77 20 6d 75 74 65 78 2e 20 20 54 68 65 20 6e ew mutex. The n
323b0 65 77 20 6d 75 74 65 78 20 69 73 20 72 65 63 75 ew mutex is recu
323c0 72 73 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54 rsive when SQLIT
323d0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 E_MUTEX_RECURSIV
323e0 45 0a 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74 E.** is used but
323f0 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79 not necessarily
32400 20 73 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f so when SQLITE_
32410 4d 55 54 45 58 5f 46 41 53 54 20 69 73 20 75 73 MUTEX_FAST is us
32420 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 65 ed. {END}.** The
32430 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 mutex implement
32440 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e ation does not n
32450 65 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 eed to make a di
32460 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 stinction.** bet
32470 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 ween SQLITE_MUTE
32480 58 5f 52 45 43 55 52 53 49 56 45 20 61 6e 64 20 X_RECURSIVE and
32490 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 SQLITE_MUTEX_FAS
324a0 54 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 T if it does.**
324b0 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 7b 48 not want to. {H
324c0 31 37 30 31 36 7d 20 42 75 74 20 53 51 4c 69 74 17016} But SQLit
324d0 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 e will only requ
324e0 65 73 74 20 61 20 72 65 63 75 72 73 69 76 65 20 est a recursive
324f0 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 mutex in.** case
32500 73 20 77 68 65 72 65 20 69 74 20 72 65 61 6c 6c s where it reall
32510 79 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20 7b 45 y needs one. {E
32520 4e 44 7d 20 49 66 20 61 20 66 61 73 74 65 72 20 ND} If a faster
32530 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d 75 non-recursive mu
32540 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 tex.** implement
32550 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 ation is availab
32560 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20 70 le on the host p
32570 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74 latform, the mut
32580 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 ex subsystem.**
32590 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73 75 63 might return suc
325a0 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65 73 h a mutex in res
325b0 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45 5f ponse to SQLITE_
325c0 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a MUTEX_FAST..**.*
325d0 2a 20 7b 48 31 37 30 31 37 7d 20 54 68 65 20 6f * {H17017} The o
325e0 74 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 ther allowed par
325f0 61 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74 ameters to sqlit
32600 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 e3_mutex_alloc()
32610 20 65 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20 each return.**
32620 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 a pointer to a s
32630 74 61 74 69 63 20 70 72 65 65 78 69 73 74 69 6e tatic preexistin
32640 67 20 6d 75 74 65 78 2e 20 7b 45 4e 44 7d 20 20 g mutex. {END}
32650 46 6f 75 72 20 73 74 61 74 69 63 20 6d 75 74 65 Four static mute
32660 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 xes are.** used
32670 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 by the current v
32680 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 ersion of SQLite
32690 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f . Future versio
326a0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 ns of SQLite.**
326b0 6d 61 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e may add addition
326c0 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 al static mutexe
326d0 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65 78 s. Static mutex
326e0 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72 es are for inter
326f0 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 nal.** use by SQ
32700 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c Lite only. Appl
32710 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 ications that us
32720 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73 e SQLite mutexes
32730 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f should.** use o
32740 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20 nly the dynamic
32750 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e 65 64 mutexes returned
32760 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 by SQLITE_MUTEX
32770 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 _FAST or.** SQLI
32780 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 TE_MUTEX_RECURSI
32790 56 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 VE..**.** {H1701
327a0 38 7d 20 4e 6f 74 65 20 74 68 61 74 20 69 66 20 8} Note that if
327b0 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 6e 61 6d one of the dynam
327c0 69 63 20 6d 75 74 65 78 20 70 61 72 61 6d 65 74 ic mutex paramet
327d0 65 72 73 20 28 53 51 4c 49 54 45 5f 4d 55 54 45 ers (SQLITE_MUTE
327e0 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53 51 4c X_FAST.** or SQL
327f0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 ITE_MUTEX_RECURS
32800 49 56 45 29 20 69 73 20 75 73 65 64 20 74 68 65 IVE) is used the
32810 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f n sqlite3_mutex_
32820 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 75 72 alloc().** retur
32830 6e 73 20 61 20 64 69 66 66 65 72 65 6e 74 20 6d ns a different m
32840 75 74 65 78 20 6f 6e 20 65 76 65 72 79 20 63 61 utex on every ca
32850 6c 6c 2e 20 20 7b 48 31 37 30 33 34 7d 20 42 75 ll. {H17034} Bu
32860 74 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 t for the static
32870 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c .** mutex types,
32880 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 the same mutex
32890 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 is returned on e
328a0 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 very call that h
328b0 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 as.** the same t
328c0 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a ype number..**.*
328d0 2a 20 7b 48 31 37 30 31 39 7d 20 54 68 65 20 73 * {H17019} The s
328e0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 qlite3_mutex_fre
328f0 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65 61 6c e() routine deal
32900 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76 69 6f locates a previo
32910 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 usly.** allocate
32920 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 2e d dynamic mutex.
32930 20 7b 48 31 37 30 32 30 7d 20 53 51 4c 69 74 65 {H17020} SQLite
32940 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64 is careful to d
32950 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a eallocate every.
32960 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 ** dynamic mutex
32970 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 that it allocat
32980 65 73 2e 20 7b 41 31 37 30 32 31 7d 20 54 68 65 es. {A17021} The
32990 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 dynamic mutexes
329a0 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 69 6e 0a must not be in.
329b0 2a 2a 20 75 73 65 20 77 68 65 6e 20 74 68 65 79 ** use when they
329c0 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 are deallocated
329d0 2e 20 7b 41 31 37 30 32 32 7d 20 41 74 74 65 6d . {A17022} Attem
329e0 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 pting to dealloc
329f0 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 ate a static.**
32a00 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e mutex results in
32a10 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
32a20 69 6f 72 2e 20 7b 48 31 37 30 32 33 7d 20 53 51 ior. {H17023} SQ
32a30 4c 69 74 65 20 6e 65 76 65 72 20 64 65 61 6c 6c Lite never deall
32a40 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73 74 61 74 ocates.** a stat
32a50 69 63 20 6d 75 74 65 78 2e 20 7b 45 4e 44 7d 0a ic mutex. {END}.
32a60 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
32a70 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 3_mutex_enter()
32a80 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 and sqlite3_mute
32a90 78 5f 74 72 79 28 29 20 72 6f 75 74 69 6e 65 73 x_try() routines
32aa0 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 attempt.** to e
32ab0 6e 74 65 72 20 61 20 6d 75 74 65 78 2e 20 7b 48 nter a mutex. {H
32ac0 31 37 30 32 34 7d 20 49 66 20 61 6e 6f 74 68 65 17024} If anothe
32ad0 72 20 74 68 72 65 61 64 20 69 73 20 61 6c 72 65 r thread is alre
32ae0 61 64 79 20 77 69 74 68 69 6e 20 74 68 65 20 6d ady within the m
32af0 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 utex,.** sqlite3
32b00 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 77 _mutex_enter() w
32b10 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71 ill block and sq
32b20 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 lite3_mutex_try(
32b30 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a ) will return.**
32b40 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 7b 48 SQLITE_BUSY. {H
32b50 31 37 30 32 35 7d 20 20 54 68 65 20 73 71 6c 69 17025} The sqli
32b60 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 te3_mutex_try()
32b70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
32b80 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a s [SQLITE_OK].**
32b90 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c upon successful
32ba0 20 65 6e 74 72 79 2e 20 20 7b 48 31 37 30 32 36 entry. {H17026
32bb0 7d 20 4d 75 74 65 78 65 73 20 63 72 65 61 74 65 } Mutexes create
32bc0 64 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 d using.** SQLIT
32bd0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 E_MUTEX_RECURSIV
32be0 45 20 63 61 6e 20 62 65 20 65 6e 74 65 72 65 64 E can be entered
32bf0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 multiple times
32c00 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 by the same thre
32c10 61 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 37 7d 20 ad..** {H17027}
32c20 49 6e 20 73 75 63 68 20 63 61 73 65 73 20 74 68 In such cases th
32c30 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 73 74 e,.** mutex must
32c40 20 62 65 20 65 78 69 74 65 64 20 61 6e 20 65 71 be exited an eq
32c50 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 ual number of ti
32c60 6d 65 73 20 62 65 66 6f 72 65 20 61 6e 6f 74 68 mes before anoth
32c70 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 63 61 6e er thread.** can
32c80 20 65 6e 74 65 72 2e 20 20 7b 41 31 37 30 32 38 enter. {A17028
32c90 7d 20 49 66 20 74 68 65 20 73 61 6d 65 20 74 68 } If the same th
32ca0 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e read tries to en
32cb0 74 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a ter any other.**
32cc0 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d kind of mutex m
32cd0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 ore than once, t
32ce0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
32cf0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 7b 48 31 ndefined..** {H1
32d00 37 30 32 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 7029} SQLite wil
32d10 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69 74 0a l never exhibit.
32d20 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69 6f 72 ** such behavior
32d30 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73 65 20 in its own use
32d40 6f 66 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a of mutexes..**.*
32d50 2a 20 53 6f 6d 65 20 73 79 73 74 65 6d 73 20 28 * Some systems (
32d60 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 57 69 6e for example, Win
32d70 64 6f 77 73 20 39 35 29 20 64 6f 20 6e 6f 74 20 dows 95) do not
32d80 73 75 70 70 6f 72 74 20 74 68 65 20 6f 70 65 72 support the oper
32d90 61 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 ation.** impleme
32da0 6e 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f nted by sqlite3_
32db0 6d 75 74 65 78 5f 74 72 79 28 29 2e 20 20 4f 6e mutex_try(). On
32dc0 20 74 68 6f 73 65 20 73 79 73 74 65 6d 73 2c 20 those systems,
32dd0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 sqlite3_mutex_tr
32de0 79 28 29 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 y().** will alwa
32df0 79 73 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 ys return SQLITE
32e00 5f 42 55 53 59 2e 20 20 7b 48 31 37 30 33 30 7d _BUSY. {H17030}
32e10 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
32e20 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 73 0a only ever uses.
32e30 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ** sqlite3_mutex
32e40 5f 74 72 79 28 29 20 61 73 20 61 6e 20 6f 70 74 _try() as an opt
32e50 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 imization so thi
32e60 73 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 s is acceptable
32e70 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 behavior..**.**
32e80 7b 48 31 37 30 33 31 7d 20 54 68 65 20 73 71 6c {H17031} The sql
32e90 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 ite3_mutex_leave
32ea0 28 29 20 72 6f 75 74 69 6e 65 20 65 78 69 74 73 () routine exits
32eb0 20 61 20 6d 75 74 65 78 20 74 68 61 74 20 77 61 a mutex that wa
32ec0 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 s.** previously
32ed0 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 20 73 entered by the s
32ee0 61 6d 65 20 74 68 72 65 61 64 2e 20 20 7b 41 31 ame thread. {A1
32ef0 37 30 33 32 7d 20 54 68 65 20 62 65 68 61 76 69 7032} The behavi
32f00 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e or.** is undefin
32f10 65 64 20 69 66 20 74 68 65 20 6d 75 74 65 78 20 ed if the mutex
32f20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 is not currently
32f30 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 0a entered by the.
32f40 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 ** calling threa
32f50 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 75 72 72 d or is not curr
32f60 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65 64 2e ently allocated.
32f70 20 20 7b 48 31 37 30 33 33 7d 20 53 51 4c 69 74 {H17033} SQLit
32f80 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 e will.** never
32f90 64 6f 20 65 69 74 68 65 72 2e 20 7b 45 4e 44 7d do either. {END}
32fa0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 61 72 .**.** If the ar
32fb0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
32fc0 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 2c 3_mutex_enter(),
32fd0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 sqlite3_mutex_t
32fe0 72 79 28 29 2c 20 6f 72 0a 2a 2a 20 73 71 6c 69 ry(), or.** sqli
32ff0 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 te3_mutex_leave(
33000 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e ) is a NULL poin
33010 74 65 72 2c 20 74 68 65 6e 20 61 6c 6c 20 74 68 ter, then all th
33020 72 65 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 ree routines.**
33030 62 65 68 61 76 65 20 61 73 20 6e 6f 2d 6f 70 73 behave as no-ops
33040 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
33050 3a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 : [sqlite3_mutex
33060 5f 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b 73 71 _held()] and [sq
33070 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 lite3_mutex_noth
33080 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 eld()]..*/.sqlit
33090 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 e3_mutex *sqlite
330a0 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 3_mutex_alloc(in
330b0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 t);.void sqlite3
330c0 5f 6d 75 74 65 78 5f 66 72 65 65 28 73 71 6c 69 _mutex_free(sqli
330d0 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 te3_mutex*);.voi
330e0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f d sqlite3_mutex_
330f0 65 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 6d 75 enter(sqlite3_mu
33100 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 tex*);.int sqlit
33110 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 73 71 6c e3_mutex_try(sql
33120 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f ite3_mutex*);.vo
33130 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 id sqlite3_mutex
33140 5f 6c 65 61 76 65 28 73 71 6c 69 74 65 33 5f 6d _leave(sqlite3_m
33150 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 utex*);../*.** C
33160 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 4d API3REF: Mutex M
33170 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 ethods Object {H
33180 31 37 31 32 30 7d 20 3c 53 32 30 31 33 30 3e 0a 17120} <S20130>.
33190 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
331a0 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 **.** An instanc
331b0 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 e of this struct
331c0 75 72 65 20 64 65 66 69 6e 65 73 20 74 68 65 20 ure defines the
331d0 6c 6f 77 2d 6c 65 76 65 6c 20 72 6f 75 74 69 6e low-level routin
331e0 65 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 61 6c es.** used to al
331f0 6c 6f 63 61 74 65 20 61 6e 64 20 75 73 65 20 6d locate and use m
33200 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 utexes..**.** Us
33210 75 61 6c 6c 79 2c 20 74 68 65 20 64 65 66 61 75 ually, the defau
33220 6c 74 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 lt mutex impleme
33230 6e 74 61 74 69 6f 6e 73 20 70 72 6f 76 69 64 65 ntations provide
33240 64 20 62 79 20 53 51 4c 69 74 65 20 61 72 65 0a d by SQLite are.
33250 2a 2a 20 73 75 66 66 69 63 69 65 6e 74 2c 20 68 ** sufficient, h
33260 6f 77 65 76 65 72 20 74 68 65 20 75 73 65 72 20 owever the user
33270 68 61 73 20 74 68 65 20 6f 70 74 69 6f 6e 20 6f has the option o
33280 66 20 73 75 62 73 74 69 74 75 74 69 6e 67 20 61 f substituting a
33290 20 63 75 73 74 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 custom.** imple
332a0 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 73 70 mentation for sp
332b0 65 63 69 61 6c 69 7a 65 64 20 64 65 70 6c 6f 79 ecialized deploy
332c0 6d 65 6e 74 73 20 6f 72 20 73 79 73 74 65 6d 73 ments or systems
332d0 20 66 6f 72 20 77 68 69 63 68 20 53 51 4c 69 74 for which SQLit
332e0 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 70 72 e.** does not pr
332f0 6f 76 69 64 65 20 61 20 73 75 69 74 61 62 6c 65 ovide a suitable
33300 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
33310 20 49 6e 20 74 68 69 73 20 63 61 73 65 2c 20 74 In this case, t
33320 68 65 20 75 73 65 72 0a 2a 2a 20 63 72 65 61 74 he user.** creat
33330 65 73 20 61 6e 64 20 70 6f 70 75 6c 61 74 65 73 es and populates
33340 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
33350 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 74 this structure t
33360 6f 20 70 61 73 73 0a 2a 2a 20 74 6f 20 73 71 6c o pass.** to sql
33370 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 61 6c ite3_config() al
33380 6f 6e 67 20 77 69 74 68 20 74 68 65 20 5b 53 51 ong with the [SQ
33390 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
333a0 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 64 X] option..** Ad
333b0 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 61 6e 20 69 ditionally, an i
333c0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
333d0 73 74 72 75 63 74 75 72 65 20 63 61 6e 20 62 65 structure can be
333e0 20 75 73 65 64 20 61 73 20 61 6e 0a 2a 2a 20 6f used as an.** o
333f0 75 74 70 75 74 20 76 61 72 69 61 62 6c 65 20 77 utput variable w
33400 68 65 6e 20 71 75 65 72 79 69 6e 67 20 74 68 65 hen querying the
33410 20 73 79 73 74 65 6d 20 66 6f 72 20 74 68 65 20 system for the
33420 63 75 72 72 65 6e 74 20 6d 75 74 65 78 0a 2a 2a current mutex.**
33430 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c implementation,
33440 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 using the [SQLI
33450 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
33460 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a EX] option..**.*
33470 2a 20 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 * The xMutexInit
33480 20 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20 method defined
33490 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 by this structur
334a0 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a e is invoked as.
334b0 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74 65 ** part of syste
334c0 6d 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e m initialization
334d0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f by the sqlite3_
334e0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 66 75 6e initialize() fun
334f0 63 74 69 6f 6e 2e 0a 2a 2a 20 7b 48 31 37 30 30 ction..** {H1700
33500 31 7d 20 54 68 65 20 78 4d 75 74 65 78 49 6e 69 1} The xMutexIni
33510 74 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 t routine shall
33520 62 65 20 63 61 6c 6c 65 64 20 62 79 20 53 51 4c be called by SQL
33530 69 74 65 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 ite once for eac
33540 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 65 20 63 h.** effective c
33550 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
33560 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e 0a 2a initialize()]..*
33570 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 45 *.** The xMutexE
33580 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 nd method define
33590 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74 d by this struct
335a0 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 ure is invoked a
335b0 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 73 s.** part of sys
335c0 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 62 79 20 tem shutdown by
335d0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 the sqlite3_shut
335e0 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 6f 6e 2e down() function.
335f0 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e The.** implemen
33600 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d tation of this m
33610 65 74 68 6f 64 20 69 73 20 65 78 70 65 63 74 65 ethod is expecte
33620 64 20 74 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c d to release all
33630 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 outstanding.**
33640 72 65 73 6f 75 72 63 65 73 20 6f 62 74 61 69 6e resources obtain
33650 65 64 20 62 79 20 74 68 65 20 6d 75 74 65 78 20 ed by the mutex
33660 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 6d 65 6e methods implemen
33670 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 69 61 6c tation, especial
33680 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f 62 74 61 ly.** those obta
33690 69 6e 65 64 20 62 79 20 74 68 65 20 78 4d 75 74 ined by the xMut
336a0 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 2e 20 7b exInit method. {
336b0 48 31 37 30 30 33 7d 20 54 68 65 20 78 4d 75 74 H17003} The xMut
336c0 65 78 45 6e 64 28 29 0a 2a 2a 20 69 6e 74 65 72 exEnd().** inter
336d0 66 61 63 65 20 73 68 61 6c 6c 20 62 65 20 69 6e face shall be in
336e0 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 voked once for e
336f0 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ach call to [sql
33700 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
33710 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 ..**.** The rema
33720 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 74 68 ining seven meth
33730 6f 64 73 20 64 65 66 69 6e 65 64 20 62 79 20 74 ods defined by t
33740 68 69 73 20 73 74 72 75 63 74 75 72 65 20 28 78 his structure (x
33750 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 MutexAlloc,.** x
33760 4d 75 74 65 78 46 72 65 65 2c 20 78 4d 75 74 65 MutexFree, xMute
33770 78 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 54 72 xEnter, xMutexTr
33780 79 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 2c 20 y, xMutexLeave,
33790 78 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a xMutexHeld and.*
337a0 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 * xMutexNotheld)
337b0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 66 implement the f
337c0 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 ollowing interfa
337d0 63 65 73 20 28 72 65 73 70 65 63 74 69 76 65 6c ces (respectivel
337e0 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a y):.**.** <ul>.*
337f0 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 * <li> [sqlit
33800 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 e3_mutex_alloc()
33810 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 ] </li>.** <li
33820 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 > [sqlite3_mute
33830 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a x_free()] </li>.
33840 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 ** <li> [sqli
33850 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 te3_mutex_enter(
33860 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c )] </li>.** <l
33870 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 i> [sqlite3_mut
33880 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a ex_try()] </li>.
33890 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 ** <li> [sqli
338a0 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 te3_mutex_leave(
338b0 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c )] </li>.** <l
338c0 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 i> [sqlite3_mut
338d0 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e ex_held()] </li>
338e0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c .** <li> [sql
338f0 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 ite3_mutex_nothe
33900 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c ld()] </li>.** <
33910 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f /ul>.**.** The o
33920 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 69 nly difference i
33930 73 20 74 68 61 74 20 74 68 65 20 70 75 62 6c 69 s that the publi
33940 63 20 73 71 6c 69 74 65 33 5f 58 58 58 20 66 75 c sqlite3_XXX fu
33950 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61 74 nctions enumerat
33960 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69 6c 65 ed.** above sile
33970 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e 79 20 ntly ignore any
33980 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 invocations that
33990 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 70 6f 69 pass a NULL poi
339a0 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 nter instead.**
339b0 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78 of a valid mutex
339c0 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 69 6d 70 handle. The imp
339d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 lementations of
339e0 74 68 65 20 6d 65 74 68 6f 64 73 20 64 65 66 69 the methods defi
339f0 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20 73 ned.** by this s
33a00 74 72 75 63 74 75 72 65 20 61 72 65 20 6e 6f 74 tructure are not
33a10 20 72 65 71 75 69 72 65 64 20 74 6f 20 68 61 6e required to han
33a20 64 6c 65 20 74 68 69 73 20 63 61 73 65 2c 20 74 dle this case, t
33a30 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20 6f 66 he results.** of
33a40 20 70 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 passing a NULL
33a50 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 pointer instead
33a60 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78 of a valid mutex
33a70 20 68 61 6e 64 6c 65 20 61 72 65 20 75 6e 64 65 handle are unde
33a80 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e 20 69 fined.** (i.e. i
33a90 74 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 t is acceptable
33aa0 74 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69 6d to provide an im
33ab0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 plementation tha
33ac0 74 20 73 65 67 66 61 75 6c 74 73 20 69 66 0a 2a t segfaults if.*
33ad0 2a 20 69 74 20 69 73 20 70 61 73 73 65 64 20 61 * it is passed a
33ae0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29 2e 0a NULL pointer)..
33af0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
33b00 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f t sqlite3_mutex_
33b10 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f methods sqlite3_
33b20 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 mutex_methods;.s
33b30 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 truct sqlite3_mu
33b40 74 65 78 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 tex_methods {.
33b50 69 6e 74 20 28 2a 78 4d 75 74 65 78 49 6e 69 74 int (*xMutexInit
33b60 29 28 76 6f 69 64 29 3b 0a 20 20 69 6e 74 20 28 )(void);. int (
33b70 2a 78 4d 75 74 65 78 45 6e 64 29 28 76 6f 69 64 *xMutexEnd)(void
33b80 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 6d 75 74 );. sqlite3_mut
33b90 65 78 20 2a 28 2a 78 4d 75 74 65 78 41 6c 6c 6f ex *(*xMutexAllo
33ba0 63 29 28 69 6e 74 29 3b 0a 20 20 76 6f 69 64 20 c)(int);. void
33bb0 28 2a 78 4d 75 74 65 78 46 72 65 65 29 28 73 71 (*xMutexFree)(sq
33bc0 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a lite3_mutex *);.
33bd0 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 45 void (*xMutexE
33be0 6e 74 65 72 29 28 73 71 6c 69 74 65 33 5f 6d 75 nter)(sqlite3_mu
33bf0 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a tex *);. int (*
33c00 78 4d 75 74 65 78 54 72 79 29 28 73 71 6c 69 74 xMutexTry)(sqlit
33c10 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 e3_mutex *);. v
33c20 6f 69 64 20 28 2a 78 4d 75 74 65 78 4c 65 61 76 oid (*xMutexLeav
33c30 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e)(sqlite3_mutex
33c40 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 *);. int (*xMu
33c50 74 65 78 48 65 6c 64 29 28 73 71 6c 69 74 65 33 texHeld)(sqlite3
33c60 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 _mutex *);. int
33c70 20 28 2a 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 (*xMutexNotheld
33c80 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 )(sqlite3_mutex
33c90 2a 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 *);.};../*.** CA
33ca0 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 56 65 PI3REF: Mutex Ve
33cb0 72 69 66 69 63 61 74 69 6f 6e 20 52 6f 75 74 69 rification Routi
33cc0 6e 65 73 20 7b 48 31 37 30 38 30 7d 20 3c 53 32 nes {H17080} <S2
33cd0 30 31 33 30 3e 20 3c 53 33 30 38 30 30 3e 0a 2a 0130> <S30800>.*
33ce0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
33cf0 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61 6e _mutex_held() an
33d00 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f d sqlite3_mutex_
33d10 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69 6e notheld() routin
33d20 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 es.** are intend
33d30 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 ed for use insid
33d40 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 e assert() state
33d50 6d 65 6e 74 73 2e 20 7b 48 31 37 30 38 31 7d 20 ments. {H17081}
33d60 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 0a The SQLite core.
33d70 2a 2a 20 6e 65 76 65 72 20 75 73 65 73 20 74 68 ** never uses th
33d80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 65 78 63 ese routines exc
33d90 65 70 74 20 69 6e 73 69 64 65 20 61 6e 20 61 73 ept inside an as
33da0 73 65 72 74 28 29 20 61 6e 64 20 61 70 70 6c 69 sert() and appli
33db0 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 cations.** are a
33dc0 64 76 69 73 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 dvised to follow
33dd0 20 74 68 65 20 6c 65 61 64 20 6f 66 20 74 68 65 the lead of the
33de0 20 63 6f 72 65 2e 20 20 7b 48 31 37 30 38 32 7d core. {H17082}
33df0 20 54 68 65 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a The core only.*
33e00 2a 20 70 72 6f 76 69 64 65 73 20 69 6d 70 6c 65 * provides imple
33e10 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 74 mentations for t
33e20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 68 hese routines wh
33e30 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 en it is compile
33e40 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 53 51 d.** with the SQ
33e50 4c 49 54 45 5f 44 45 42 55 47 20 66 6c 61 67 2e LITE_DEBUG flag.
33e60 20 20 7b 41 31 37 30 38 37 7d 20 45 78 74 65 72 {A17087} Exter
33e70 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d nal mutex implem
33e80 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 entations.** are
33e90 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20 74 only required t
33ea0 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 65 20 o provide these
33eb0 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c 49 routines if SQLI
33ec0 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 64 TE_DEBUG is.** d
33ed0 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e 44 efined and if ND
33ee0 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66 69 EBUG is not defi
33ef0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 ned..**.** {H170
33f00 38 33 7d 20 54 68 65 73 65 20 72 6f 75 74 69 6e 83} These routin
33f10 65 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e es should return
33f20 20 74 72 75 65 20 69 66 20 74 68 65 20 6d 75 74 true if the mut
33f30 65 78 20 69 6e 20 74 68 65 69 72 20 61 72 67 75 ex in their argu
33f40 6d 65 6e 74 0a 2a 2a 20 69 73 20 68 65 6c 64 20 ment.** is held
33f50 6f 72 20 6e 6f 74 20 68 65 6c 64 2c 20 72 65 73 or not held, res
33f60 70 65 63 74 69 76 65 6c 79 2c 20 62 79 20 74 68 pectively, by th
33f70 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 e calling thread
33f80 2e 0a 2a 2a 0a 2a 2a 20 7b 58 31 37 30 38 34 7d ..**.** {X17084}
33f90 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 The implementat
33fa0 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69 ion is not requi
33fb0 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20 red to provided
33fc0 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 versions of thes
33fd0 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 e.** routines th
33fe0 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b at actually work
33ff0 2e 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65 . If the impleme
34000 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 ntation does not
34010 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67 provide working
34020 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 .** versions of
34030 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 these routines,
34040 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61 it should at lea
34050 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 62 73 st provide stubs
34060 20 74 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20 that always.**
34070 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74 return true so t
34080 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 hat one does not
34090 20 67 65 74 20 73 70 75 72 69 6f 75 73 20 61 73 get spurious as
340a0 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 sertion failures
340b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 35 7d ..**.** {H17085}
340c0 20 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 If the argument
340d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 to sqlite3_mute
340e0 78 5f 68 65 6c 64 28 29 20 69 73 20 61 20 4e 55 x_held() is a NU
340f0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a LL pointer then.
34100 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 73 ** the routine s
34110 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 31 2e 20 hould return 1.
34120 20 7b 45 4e 44 7d 20 54 68 69 73 20 73 65 65 6d {END} This seem
34130 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69 74 s counter-intuit
34140 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63 6c 65 ive since.** cle
34150 61 72 6c 79 20 74 68 65 20 6d 75 74 65 78 20 63 arly the mutex c
34160 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20 69 66 annot be held if
34170 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 it does not exi
34180 73 74 2e 20 20 42 75 74 20 74 68 65 0a 2a 2a 20 st. But the.**
34190 74 68 65 20 72 65 61 73 6f 6e 20 74 68 65 20 6d the reason the m
341a0 75 74 65 78 20 64 6f 65 73 20 6e 6f 74 20 65 78 utex does not ex
341b0 69 73 74 20 69 73 20 62 65 63 61 75 73 65 20 74 ist is because t
341c0 68 65 20 62 75 69 6c 64 20 69 73 20 6e 6f 74 0a he build is not.
341d0 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65 78 65 73 ** using mutexes
341e0 2e 20 20 41 6e 64 20 77 65 20 64 6f 20 6e 6f 74 . And we do not
341f0 20 77 61 6e 74 20 74 68 65 20 61 73 73 65 72 74 want the assert
34200 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 () containing th
34210 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c e.** call to sql
34220 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 ite3_mutex_held(
34230 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20 61 20 ) to fail, so a
34240 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 non-zero return
34250 69 73 0a 2a 2a 20 74 68 65 20 61 70 70 72 6f 70 is.** the approp
34260 72 69 61 74 65 20 74 68 69 6e 67 20 74 6f 20 64 riate thing to d
34270 6f 2e 20 20 7b 48 31 37 30 38 36 7d 20 54 68 65 o. {H17086} The
34280 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e sqlite3_mutex_n
34290 6f 74 68 65 6c 64 28 29 0a 2a 2a 20 69 6e 74 65 otheld().** inte
342a0 72 66 61 63 65 20 73 68 6f 75 6c 64 20 61 6c 73 rface should als
342b0 6f 20 72 65 74 75 72 6e 20 31 20 77 68 65 6e 20 o return 1 when
342c0 67 69 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 given a NULL poi
342d0 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c nter..*/.int sql
342e0 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 ite3_mutex_held(
342f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b sqlite3_mutex*);
34300 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 .int sqlite3_mut
34310 65 78 5f 6e 6f 74 68 65 6c 64 28 73 71 6c 69 74 ex_notheld(sqlit
34320 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a e3_mutex*);../*.
34330 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 ** CAPI3REF: Mut
34340 65 78 20 54 79 70 65 73 20 7b 48 31 37 30 30 31 ex Types {H17001
34350 7d 20 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a } <H17000>.**.**
34360 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 The [sqlite3_mu
34370 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 tex_alloc()] int
34380 65 72 66 61 63 65 20 74 61 6b 65 73 20 61 20 73 erface takes a s
34390 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a ingle argument.*
343a0 2a 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f * which is one o
343b0 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 f these integer
343c0 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a constants..**.**
343d0 20 54 68 65 20 73 65 74 20 6f 66 20 73 74 61 74 The set of stat
343e0 69 63 20 6d 75 74 65 78 65 73 20 6d 61 79 20 63 ic mutexes may c
343f0 68 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53 hange from one S
34400 51 4c 69 74 65 20 72 65 6c 65 61 73 65 20 74 6f QLite release to
34410 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 the.** next. A
34420 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
34430 20 6f 76 65 72 72 69 64 65 20 74 68 65 20 62 75 override the bu
34440 69 6c 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67 ilt-in mutex log
34450 69 63 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72 ic must be.** pr
34460 65 70 61 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d epared to accomm
34470 6f 64 61 74 65 20 61 64 64 69 74 69 6f 6e 61 6c odate additional
34480 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e static mutexes.
34490 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
344a0 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 20 TE_MUTEX_FAST
344b0 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 0.#def
344c0 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 ine SQLITE_MUTEX
344d0 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 _RECURSIVE
344e0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
344f0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
34500 4d 41 53 54 45 52 20 20 20 20 32 0a 23 64 65 66 MASTER 2.#def
34510 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 ine SQLITE_MUTEX
34520 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 20 _STATIC_MEM
34530 20 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 3 /* sqlite3_
34540 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66 malloc() */.#def
34550 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 ine SQLITE_MUTEX
34560 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 20 _STATIC_MEM2
34570 20 20 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 4 /* NOT USED
34580 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
34590 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
345a0 4f 50 45 4e 20 20 20 20 20 20 34 20 20 2f 2a 20 OPEN 4 /*
345b0 73 71 6c 69 74 65 33 42 74 72 65 65 4f 70 65 6e sqlite3BtreeOpen
345c0 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
345d0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
345e0 43 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f C_PRNG 5 /
345f0 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d * sqlite3_random
34600 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
34610 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
34620 43 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f C_LRU 6 /
34630 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 * lru page list
34640 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
34650 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c E_MUTEX_STATIC_L
34660 52 55 32 20 20 20 20 20 20 37 20 20 2f 2a 20 6c RU2 7 /* l
34670 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a ru page list */.
34680 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
34690 20 52 65 74 72 69 65 76 65 20 74 68 65 20 6d 75 Retrieve the mu
346a0 74 65 78 20 66 6f 72 20 61 20 64 61 74 61 62 61 tex for a databa
346b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 se connection {H
346c0 31 37 30 30 32 7d 20 3c 48 31 37 30 30 30 3e 0a 17002} <H17000>.
346d0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
346e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
346f0 6f 69 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69 ointer the [sqli
34700 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 te3_mutex] objec
34710 74 20 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61 t that .** seria
34720 6c 69 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20 lizes access to
34730 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
34740 6e 6e 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20 nnection] given
34750 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a in the argument.
34760 2a 2a 20 77 68 65 6e 20 74 68 65 20 5b 74 68 72 ** when the [thr
34770 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 eading mode] is
34780 53 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 49 Serialized..** I
34790 66 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 f the [threading
347a0 20 6d 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c 65 mode] is Single
347b0 2d 74 68 72 65 61 64 20 6f 72 20 4d 75 6c 74 69 -thread or Multi
347c0 2d 74 68 72 65 61 64 20 74 68 65 6e 20 74 68 69 -thread then thi
347d0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 s.** routine ret
347e0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e urns a NULL poin
347f0 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f ter..*/.sqlite3_
34800 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 64 mutex *sqlite3_d
34810 62 5f 6d 75 74 65 78 28 73 71 6c 69 74 65 33 2a b_mutex(sqlite3*
34820 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
34830 45 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f EF: Low-Level Co
34840 6e 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73 ntrol Of Databas
34850 65 20 46 69 6c 65 73 20 7b 48 31 31 33 30 30 7d e Files {H11300}
34860 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S30800>.**.**
34870 7b 48 31 31 33 30 31 7d 20 54 68 65 20 5b 73 71 {H11301} The [sq
34880 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
34890 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 ol()] interface
348a0 6d 61 6b 65 73 20 61 20 64 69 72 65 63 74 20 63 makes a direct c
348b0 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 78 46 all to the.** xF
348c0 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
348d0 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 d for the [sqlit
348e0 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
348f0 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 bject associated
34900 0a 2a 2a 20 77 69 74 68 20 61 20 70 61 72 74 69 .** with a parti
34910 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 69 cular database i
34920 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 dentified by the
34930 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
34940 2e 20 7b 48 31 31 33 30 32 7d 20 54 68 65 0a 2a . {H11302} The.*
34950 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 * name of the da
34960 74 61 62 61 73 65 20 69 73 20 74 68 65 20 6e 61 tabase is the na
34970 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 74 me assigned to t
34980 68 65 20 64 61 74 61 62 61 73 65 20 62 79 20 74 he database by t
34990 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 6c he.** <a href="l
349a0 61 6e 67 5f 61 74 74 61 63 68 2e 68 74 6d 6c 22 ang_attach.html"
349b0 3e 41 54 54 41 43 48 3c 2f 61 3e 20 53 51 4c 20 >ATTACH</a> SQL
349c0 63 6f 6d 6d 61 6e 64 20 74 68 61 74 20 6f 70 65 command that ope
349d0 6e 65 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 ned the.** datab
349e0 61 73 65 2e 20 7b 48 31 31 33 30 33 7d 20 54 6f ase. {H11303} To
349f0 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 6d 61 69 control the mai
34a00 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c n database file,
34a10 20 75 73 65 20 74 68 65 20 6e 61 6d 65 20 22 6d use the name "m
34a20 61 69 6e 22 0a 2a 2a 20 6f 72 20 61 20 4e 55 4c ain".** or a NUL
34a30 4c 20 70 6f 69 6e 74 65 72 2e 20 7b 48 31 31 33 L pointer. {H113
34a40 30 34 7d 20 54 68 65 20 74 68 69 72 64 20 61 6e 04} The third an
34a50 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 d fourth paramet
34a60 65 72 73 20 74 6f 20 74 68 69 73 20 72 6f 75 74 ers to this rout
34a70 69 6e 65 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 ine.** are passe
34a80 64 20 64 69 72 65 63 74 6c 79 20 74 68 72 6f 75 d directly throu
34a90 67 68 20 74 6f 20 74 68 65 20 73 65 63 6f 6e 64 gh to the second
34aa0 20 61 6e 64 20 74 68 69 72 64 20 70 61 72 61 6d and third param
34ab0 65 74 65 72 73 20 6f 66 0a 2a 2a 20 74 68 65 20 eters of.** the
34ac0 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
34ad0 68 6f 64 2e 20 20 7b 48 31 31 33 30 35 7d 20 54 hod. {H11305} T
34ae0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
34af0 6f 66 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 of the xFileCont
34b00 72 6f 6c 0a 2a 2a 20 6d 65 74 68 6f 64 20 62 65 rol.** method be
34b10 63 6f 6d 65 73 20 74 68 65 20 72 65 74 75 72 6e comes the return
34b20 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 value of this r
34b30 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 outine..**.** {H
34b40 31 31 33 30 36 7d 20 49 66 20 74 68 65 20 73 65 11306} If the se
34b50 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 cond parameter (
34b60 7a 44 62 4e 61 6d 65 29 20 64 6f 65 73 20 6e 6f zDbName) does no
34b70 74 20 6d 61 74 63 68 20 74 68 65 20 6e 61 6d 65 t match the name
34b80 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 of any.** open
34b90 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 database file, t
34ba0 68 65 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 hen SQLITE_ERROR
34bb0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 7b 48 is returned. {H
34bc0 31 31 33 30 37 7d 20 54 68 69 73 20 65 72 72 6f 11307} This erro
34bd0 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 6e 6f 74 r.** code is not
34be0 20 72 65 6d 65 6d 62 65 72 65 64 20 61 6e 64 20 remembered and
34bf0 77 69 6c 6c 20 6e 6f 74 20 62 65 20 72 65 63 61 will not be reca
34c00 6c 6c 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 lled by [sqlite3
34c10 5f 65 72 72 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f _errcode()].** o
34c20 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 r [sqlite3_errms
34c30 67 28 29 5d 2e 20 7b 41 31 31 33 30 38 7d 20 54 g()]. {A11308} T
34c40 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 he underlying xF
34c50 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
34c60 64 20 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 d might.** also
34c70 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 return SQLITE_ER
34c80 52 4f 52 2e 20 20 7b 41 31 31 33 30 39 7d 20 54 ROR. {A11309} T
34c90 68 65 72 65 20 69 73 20 6e 6f 20 77 61 79 20 74 here is no way t
34ca0 6f 20 64 69 73 74 69 6e 67 75 69 73 68 20 62 65 o distinguish be
34cb0 74 77 65 65 6e 0a 2a 2a 20 61 6e 20 69 6e 63 6f tween.** an inco
34cc0 72 72 65 63 74 20 7a 44 62 4e 61 6d 65 20 61 6e rrect zDbName an
34cd0 64 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f d an SQLITE_ERRO
34ce0 52 20 72 65 74 75 72 6e 20 66 72 6f 6d 20 74 68 R return from th
34cf0 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 e underlying.**
34d00 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
34d10 68 6f 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a hod. {END}.**.**
34d20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 See also: [SQLI
34d30 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
34d40 54 45 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 TE].*/.int sqlit
34d50 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
34d60 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 sqlite3*, const
34d70 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 char *zDbName, i
34d80 6e 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a nt op, void*);..
34d90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
34da0 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 Testing Interfac
34db0 65 20 7b 48 31 31 34 30 30 7d 20 3c 53 33 30 38 e {H11400} <S308
34dc0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 00>.**.** The sq
34dd0 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 lite3_test_contr
34de0 6f 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ol() interface i
34df0 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f s used to read o
34e00 75 74 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 ut internal.** s
34e10 74 61 74 65 20 6f 66 20 53 51 4c 69 74 65 20 61 tate of SQLite a
34e20 6e 64 20 74 6f 20 69 6e 6a 65 63 74 20 66 61 75 nd to inject fau
34e30 6c 74 73 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 lts into SQLite
34e40 66 6f 72 20 74 65 73 74 69 6e 67 0a 2a 2a 20 70 for testing.** p
34e50 75 72 70 6f 73 65 73 2e 20 20 54 68 65 20 66 69 urposes. The fi
34e60 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
34e70 20 61 6e 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f an operation co
34e80 64 65 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e de that determin
34e90 65 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 es.** the number
34ea0 2c 20 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f , meaning, and o
34eb0 70 65 72 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20 peration of all
34ec0 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d subsequent param
34ed0 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 eters..**.** Thi
34ee0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e s interface is n
34ef0 6f 74 20 66 6f 72 20 75 73 65 20 62 79 20 61 70 ot for use by ap
34f00 70 6c 69 63 61 74 69 6f 6e 73 2e 20 20 49 74 20 plications. It
34f10 65 78 69 73 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a exists solely.**
34f20 20 66 6f 72 20 76 65 72 69 66 79 69 6e 67 20 74 for verifying t
34f30 68 65 20 63 6f 72 72 65 63 74 20 6f 70 65 72 61 he correct opera
34f40 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 tion of the SQLi
34f50 74 65 20 6c 69 62 72 61 72 79 2e 20 20 44 65 70 te library. Dep
34f60 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77 ending.** on how
34f70 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
34f80 61 72 79 20 69 73 20 63 6f 6d 70 69 6c 65 64 2c ary is compiled,
34f90 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
34fa0 6d 69 67 68 74 20 6e 6f 74 20 65 78 69 73 74 2e might not exist.
34fb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 .**.** The detai
34fc0 6c 73 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 ls of the operat
34fd0 69 6f 6e 20 63 6f 64 65 73 2c 20 74 68 65 69 72 ion codes, their
34fe0 20 6d 65 61 6e 69 6e 67 73 2c 20 74 68 65 20 70 meanings, the p
34ff0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 65 arameters.** the
35000 79 20 74 61 6b 65 2c 20 61 6e 64 20 77 68 61 74 y take, and what
35010 20 74 68 65 79 20 64 6f 20 61 72 65 20 61 6c 6c they do are all
35020 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
35030 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 ge without notic
35040 65 2e 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73 e..** Unlike mos
35050 74 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 t of the SQLite
35060 41 50 49 2c 20 74 68 69 73 20 66 75 6e 63 74 69 API, this functi
35070 6f 6e 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e on is not guaran
35080 74 65 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 61 teed to.** opera
35090 74 65 20 63 6f 6e 73 69 73 74 65 6e 74 6c 79 20 te consistently
350a0 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 from one release
350b0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f to the next..*/
350c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 65 73 .int sqlite3_tes
350d0 74 5f 63 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f 70 t_control(int op
350e0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , ...);../*.** C
350f0 41 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 API3REF: Testing
35100 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 72 61 Interface Opera
35110 74 69 6f 6e 20 43 6f 64 65 73 20 7b 48 31 31 34 tion Codes {H114
35120 31 30 7d 20 3c 48 31 31 34 30 30 3e 0a 2a 2a 0a 10} <H11400>.**.
35130 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
35140 74 73 20 61 72 65 20 74 68 65 20 76 61 6c 69 64 ts are the valid
35150 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 operation code
35160 70 61 72 61 6d 65 74 65 72 73 20 75 73 65 64 0a parameters used.
35170 2a 2a 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ** as the first
35180 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c argument to [sql
35190 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f ite3_test_contro
351a0 6c 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 l()]..**.** Thes
351b0 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 e parameters and
351c0 20 74 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 20 their meanings
351d0 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 are subject to c
351e0 68 61 6e 67 65 0a 2a 2a 20 77 69 74 68 6f 75 74 hange.** without
351f0 20 6e 6f 74 69 63 65 2e 20 20 54 68 65 73 65 20 notice. These
35200 76 61 6c 75 65 73 20 61 72 65 20 66 6f 72 20 74 values are for t
35210 65 73 74 69 6e 67 20 70 75 72 70 6f 73 65 73 20 esting purposes
35220 6f 6e 6c 79 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 only..** Applica
35230 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 tions should not
35240 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 use any of thes
35250 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 e parameters or
35260 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
35270 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 test_control()]
35280 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 interface..*/.#d
35290 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 efine SQLITE_TES
352a0 54 43 54 52 4c 5f 50 52 4e 47 5f 53 41 56 45 20 TCTRL_PRNG_SAVE
352b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 5
352c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
352d0 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 TESTCTRL_PRNG_RE
352e0 53 54 4f 52 45 20 20 20 20 20 20 20 20 20 20 20 STORE
352f0 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 6.#define SQLI
35300 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 TE_TESTCTRL_PRNG
35310 5f 52 45 53 45 54 20 20 20 20 20 20 20 20 20 20 _RESET
35320 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 7.#define S
35330 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 QLITE_TESTCTRL_B
35340 49 54 56 45 43 5f 54 45 53 54 20 20 20 20 20 20 ITVEC_TEST
35350 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 8.#defin
35360 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 e SQLITE_TESTCTR
35370 4c 5f 46 41 55 4c 54 5f 49 4e 53 54 41 4c 4c 20 L_FAULT_INSTALL
35380 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 9.#de
35390 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 fine SQLITE_TEST
353a0 43 54 52 4c 5f 42 45 4e 49 47 4e 5f 4d 41 4c 4c CTRL_BENIGN_MALL
353b0 4f 43 5f 48 4f 4f 4b 53 20 20 20 20 20 31 30 0a OC_HOOKS 10.
353c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
353d0 45 53 54 43 54 52 4c 5f 50 45 4e 44 49 4e 47 5f ESTCTRL_PENDING_
353e0 42 59 54 45 20 20 20 20 20 20 20 20 20 20 20 20 BYTE
353f0 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 11../*.** CAPI3R
35400 45 46 3a 20 53 51 4c 69 74 65 20 52 75 6e 74 69 EF: SQLite Runti
35410 6d 65 20 53 74 61 74 75 73 20 7b 48 31 37 32 30 me Status {H1720
35420 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 0} <S60200>.** E
35430 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
35440 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
35450 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 74 72 is used to retr
35460 69 65 76 65 20 72 75 6e 74 69 6d 65 20 73 74 61 ieve runtime sta
35470 74 75 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a tus information.
35480 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 70 72 65 ** about the pre
35490 66 6f 72 6d 61 6e 63 65 20 6f 66 20 53 51 4c 69 formance of SQLi
354a0 74 65 2c 20 61 6e 64 20 6f 70 74 69 6f 6e 61 6c te, and optional
354b0 6c 79 20 74 6f 20 72 65 73 65 74 20 76 61 72 69 ly to reset vari
354c0 6f 75 73 0a 2a 2a 20 68 69 67 68 77 61 74 65 72 ous.** highwater
354d0 20 6d 61 72 6b 73 2e 20 20 54 68 65 20 66 69 72 marks. The fir
354e0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 st argument is a
354f0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 66 n integer code f
35500 6f 72 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 66 or.** the specif
35510 69 63 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ic parameter to
35520 6d 65 61 73 75 72 65 2e 20 20 52 65 63 6f 67 6e measure. Recogn
35530 69 7a 65 64 20 69 6e 74 65 67 65 72 20 63 6f 64 ized integer cod
35540 65 73 0a 2a 2a 20 61 72 65 20 6f 66 20 74 68 65 es.** are of the
35550 20 66 6f 72 6d 20 5b 53 51 4c 49 54 45 5f 53 54 form [SQLITE_ST
35560 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 ATUS_MEMORY_USED
35570 20 7c 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 | SQLITE_STATUS
35580 5f 2e 2e 2e 5d 2e 0a 2a 2a 20 54 68 65 20 63 75 _...]..** The cu
35590 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 rrent value of t
355a0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 he parameter is
355b0 72 65 74 75 72 6e 65 64 20 69 6e 74 6f 20 2a 70 returned into *p
355c0 43 75 72 72 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 Current..** The
355d0 68 69 67 68 65 73 74 20 72 65 63 6f 72 64 65 64 highest recorded
355e0 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e value is return
355f0 65 64 20 69 6e 20 2a 70 48 69 67 68 77 61 74 65 ed in *pHighwate
35600 72 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 72 65 r. If the.** re
35610 73 65 74 46 6c 61 67 20 69 73 20 74 72 75 65 2c setFlag is true,
35620 20 74 68 65 6e 20 74 68 65 20 68 69 67 68 65 73 then the highes
35630 74 20 72 65 63 6f 72 64 20 76 61 6c 75 65 20 69 t record value i
35640 73 20 72 65 73 65 74 20 61 66 74 65 72 0a 2a 2a s reset after.**
35650 20 2a 70 48 69 67 68 77 61 74 65 72 20 69 73 20 *pHighwater is
35660 77 72 69 74 74 65 6e 2e 20 53 6f 6d 65 20 70 61 written. Some pa
35670 72 61 6d 65 74 65 72 73 20 64 6f 20 6e 6f 74 20 rameters do not
35680 72 65 63 6f 72 64 20 74 68 65 20 68 69 67 68 65 record the highe
35690 73 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 20 46 6f st.** value. Fo
356a0 72 20 74 68 6f 73 65 20 70 61 72 61 6d 65 74 65 r those paramete
356b0 72 73 0a 2a 2a 20 6e 6f 74 68 69 6e 67 20 69 73 rs.** nothing is
356c0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 written into *p
356d0 48 69 67 68 77 61 74 65 72 20 61 6e 64 20 74 68 Highwater and th
356e0 65 20 72 65 73 65 74 46 6c 61 67 20 69 73 20 69 e resetFlag is i
356f0 67 6e 6f 72 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 gnored..** Other
35700 20 70 61 72 61 6d 65 74 65 72 73 20 72 65 63 6f parameters reco
35710 72 64 20 6f 6e 6c 79 20 74 68 65 20 68 69 67 68 rd only the high
35720 77 61 74 65 72 20 6d 61 72 6b 20 61 6e 64 20 6e water mark and n
35730 6f 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a ot the current.*
35740 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 68 * value. For th
35750 65 73 65 20 6c 61 74 74 65 72 20 70 61 72 61 6d ese latter param
35760 65 74 65 72 73 20 6e 6f 74 68 69 6e 67 20 69 73 eters nothing is
35770 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 written into *p
35780 43 75 72 72 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 Current..**.** T
35790 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
357a0 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e rns SQLITE_OK on
357b0 20 73 75 63 63 65 73 73 20 61 6e 64 20 61 20 6e success and a n
357c0 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 5b 65 72 72 6f on-zero.** [erro
357d0 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 r code] on failu
357e0 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 re..**.** This r
357f0 6f 75 74 69 6e 65 20 69 73 20 74 68 72 65 61 64 outine is thread
35800 73 61 66 65 20 62 75 74 20 69 73 20 6e 6f 74 20 safe but is not
35810 61 74 6f 6d 69 63 2e 20 20 54 68 69 73 20 72 6f atomic. This ro
35820 75 74 69 6e 65 20 63 61 6e 0a 2a 2a 20 63 61 6c utine can.** cal
35830 6c 65 64 20 77 68 69 6c 65 20 6f 74 68 65 72 20 led while other
35840 74 68 72 65 61 64 73 20 61 72 65 20 72 75 6e 6e threads are runn
35850 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6f 72 20 ing the same or
35860 64 69 66 66 65 72 65 6e 74 20 53 51 4c 69 74 65 different SQLite
35870 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 20 .** interfaces.
35880 20 48 6f 77 65 76 65 72 20 74 68 65 20 76 61 6c However the val
35890 75 65 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20 ues returned in
358a0 2a 70 43 75 72 72 65 6e 74 20 61 6e 64 0a 2a 2a *pCurrent and.**
358b0 20 2a 70 48 69 67 68 77 61 74 65 72 20 72 65 66 *pHighwater ref
358c0 6c 65 63 74 20 74 68 65 20 73 74 61 74 75 73 20 lect the status
358d0 6f 66 20 53 51 4c 69 74 65 20 61 74 20 64 69 66 of SQLite at dif
358e0 66 65 72 65 6e 74 20 70 6f 69 6e 74 73 20 69 6e ferent points in
358f0 20 74 69 6d 65 0a 2a 2a 20 61 6e 64 20 69 74 20 time.** and it
35900 69 73 20 70 6f 73 73 69 62 6c 65 20 74 68 61 74 is possible that
35910 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 another thread
35920 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 might change the
35930 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e parameter.** in
35940 20 62 65 74 77 65 65 6e 20 74 68 65 20 74 69 6d between the tim
35950 65 73 20 77 68 65 6e 20 2a 70 43 75 72 72 65 6e es when *pCurren
35960 74 20 61 6e 64 20 2a 70 48 69 67 68 77 61 74 65 t and *pHighwate
35970 72 20 61 72 65 20 77 72 69 74 74 65 6e 2e 0a 2a r are written..*
35980 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
35990 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 sqlite3_db_statu
359a0 73 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 s()].*/.SQLITE_E
359b0 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 XPERIMENTAL int
359c0 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 69 sqlite3_status(i
359d0 6e 74 20 6f 70 2c 20 69 6e 74 20 2a 70 43 75 72 nt op, int *pCur
359e0 72 65 6e 74 2c 20 69 6e 74 20 2a 70 48 69 67 68 rent, int *pHigh
359f0 77 61 74 65 72 2c 20 69 6e 74 20 72 65 73 65 74 water, int reset
35a00 46 6c 61 67 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 Flag);.../*.** C
35a10 41 50 49 33 52 45 46 3a 20 53 74 61 74 75 73 20 API3REF: Status
35a20 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31 37 32 Parameters {H172
35a30 35 30 7d 20 3c 48 31 37 32 30 30 3e 0a 2a 2a 20 50} <H17200>.**
35a40 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
35a50 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 ** These integer
35a60 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 73 69 67 constants desig
35a70 6e 61 74 65 20 76 61 72 69 6f 75 73 20 72 75 6e nate various run
35a80 2d 74 69 6d 65 20 73 74 61 74 75 73 20 70 61 72 -time status par
35a90 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 61 74 20 ameters.** that
35aa0 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 can be returned
35ab0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 by [sqlite3_stat
35ac0 75 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c us()]..**.** <dl
35ad0 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f >.** <dt>SQLITE_
35ae0 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 STATUS_MEMORY_US
35af0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ED</dt>.** <dd>T
35b00 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 his parameter is
35b10 20 74 68 65 20 63 75 72 72 65 6e 74 20 61 6d 6f the current amo
35b20 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 63 68 unt of memory ch
35b30 65 63 6b 65 64 20 6f 75 74 0a 2a 2a 20 75 73 69 ecked out.** usi
35b40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ng [sqlite3_mall
35b50 6f 63 28 29 5d 2c 20 65 69 74 68 65 72 20 64 69 oc()], either di
35b60 72 65 63 74 6c 79 20 6f 72 20 69 6e 64 69 72 65 rectly or indire
35b70 63 74 6c 79 2e 20 20 54 68 65 0a 2a 2a 20 66 69 ctly. The.** fi
35b80 67 75 72 65 20 69 6e 63 6c 75 64 65 73 20 63 61 gure includes ca
35b90 6c 6c 73 20 6d 61 64 65 20 74 6f 20 5b 73 71 6c lls made to [sql
35ba0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 ite3_malloc()] b
35bb0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f y the applicatio
35bc0 6e 0a 2a 2a 20 61 6e 64 20 69 6e 74 65 72 6e 61 n.** and interna
35bd0 6c 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 62 l memory usage b
35be0 79 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 y the SQLite lib
35bf0 72 61 72 79 2e 20 20 53 63 72 61 74 63 68 20 6d rary. Scratch m
35c00 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 74 72 6f 6c emory.** control
35c10 6c 65 64 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 led by [SQLITE_C
35c20 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 ONFIG_SCRATCH] a
35c30 6e 64 20 61 75 78 69 6c 69 61 72 79 20 70 61 67 nd auxiliary pag
35c40 65 2d 63 61 63 68 65 0a 2a 2a 20 6d 65 6d 6f 72 e-cache.** memor
35c50 79 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 y controlled by
35c60 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
35c70 41 47 45 43 41 43 48 45 5d 20 69 73 20 6e 6f 74 AGECACHE] is not
35c80 20 69 6e 63 6c 75 64 65 64 20 69 6e 0a 2a 2a 20 included in.**
35c90 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 2e 20 this parameter.
35ca0 20 54 68 65 20 61 6d 6f 75 6e 74 20 72 65 74 75 The amount retu
35cb0 72 6e 65 64 20 69 73 20 74 68 65 20 73 75 6d 20 rned is the sum
35cc0 6f 66 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f of the allocatio
35cd0 6e 0a 2a 2a 20 73 69 7a 65 73 20 61 73 20 72 65 n.** sizes as re
35ce0 70 6f 72 74 65 64 20 62 79 20 74 68 65 20 78 53 ported by the xS
35cf0 69 7a 65 20 6d 65 74 68 6f 64 20 69 6e 20 5b 73 ize method in [s
35d00 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
35d10 64 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ds].</dd>.**.**
35d20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 <dt>SQLITE_STATU
35d30 53 5f 4d 41 4c 4c 4f 43 5f 53 49 5a 45 3c 2f 64 S_MALLOC_SIZE</d
35d40 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 t>.** <dd>This p
35d50 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 arameter records
35d60 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d the largest mem
35d70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
35d80 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64 equest.** handed
35d90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c to [sqlite3_mal
35da0 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 loc()] or [sqlit
35db0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 28 6f e3_realloc()] (o
35dc0 72 20 74 68 65 69 72 0a 2a 2a 20 69 6e 74 65 72 r their.** inter
35dd0 6e 61 6c 20 65 71 75 69 76 61 6c 65 6e 74 73 29 nal equivalents)
35de0 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 . Only the valu
35df0 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68 e returned in th
35e00 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 e.** *pHighwater
35e10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
35e20 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d qlite3_status()]
35e30 20 69 73 20 6f 66 20 69 6e 74 65 72 65 73 74 2e is of interest.
35e40 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 .** The value
35e50 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 written into the
35e60 20 2a 70 43 75 72 72 65 6e 74 20 70 61 72 61 6d *pCurrent param
35e70 65 74 65 72 20 69 73 20 75 6e 64 65 66 69 6e 65 eter is undefine
35e80 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 d.</dd>.**.** <d
35e90 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f t>SQLITE_STATUS_
35ea0 50 41 47 45 43 41 43 48 45 5f 55 53 45 44 3c 2f PAGECACHE_USED</
35eb0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
35ec0 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e parameter return
35ed0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
35ee0 70 61 67 65 73 20 75 73 65 64 20 6f 75 74 20 6f pages used out o
35ef0 66 20 74 68 65 0a 2a 2a 20 5b 70 61 67 65 63 61 f the.** [pageca
35f00 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 che memory alloc
35f10 61 74 6f 72 5d 20 74 68 61 74 20 77 61 73 20 63 ator] that was c
35f20 6f 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67 20 onfigured using
35f30 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
35f40 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 20 20 IG_PAGECACHE].
35f50 54 68 65 0a 2a 2a 20 76 61 6c 75 65 20 72 65 74 The.** value ret
35f60 75 72 6e 65 64 20 69 73 20 69 6e 20 70 61 67 65 urned is in page
35f70 73 2c 20 6e 6f 74 20 69 6e 20 62 79 74 65 73 2e s, not in bytes.
35f80 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
35f90 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 SQLITE_STATUS_PA
35fa0 47 45 43 41 43 48 45 5f 4f 56 45 52 46 4c 4f 57 GECACHE_OVERFLOW
35fb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
35fc0 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 s parameter retu
35fd0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
35fe0 66 20 62 79 74 65 73 20 6f 66 20 70 61 67 65 20 f bytes of page
35ff0 63 61 63 68 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 cache.** allocat
36000 69 6f 6e 20 77 68 69 63 68 20 63 6f 75 6c 64 20 ion which could
36010 6e 6f 74 20 62 65 20 73 74 61 74 69 73 66 69 65 not be statisfie
36020 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 d by the [SQLITE
36030 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
36040 45 5d 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e 64 E].** buffer and
36050 20 77 68 65 72 65 20 66 6f 72 63 65 64 20 74 6f where forced to
36060 20 6f 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 71 overflow to [sq
36070 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
36080 20 20 54 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 The.** returne
36090 64 20 76 61 6c 75 65 20 69 6e 63 6c 75 64 65 73 d value includes
360a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 74 68 61 allocations tha
360b0 74 20 6f 76 65 72 66 6c 6f 77 65 64 20 62 65 63 t overflowed bec
360c0 61 75 73 65 20 74 68 65 79 0a 2a 2a 20 77 68 65 ause they.** whe
360d0 72 65 20 74 6f 6f 20 6c 61 72 67 65 20 28 74 68 re too large (th
360e0 65 79 20 77 65 72 65 20 6c 61 72 67 65 72 20 74 ey were larger t
360f0 68 61 6e 20 74 68 65 20 22 73 7a 22 20 70 61 72 han the "sz" par
36100 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 ameter to.** [SQ
36110 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
36120 43 41 43 48 45 5d 29 20 61 6e 64 20 61 6c 6c 6f CACHE]) and allo
36130 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 cations that ove
36140 72 66 6c 6f 77 65 64 20 62 65 63 61 75 73 65 0a rflowed because.
36150 2a 2a 20 6e 6f 20 73 70 61 63 65 20 77 61 73 20 ** no space was
36160 6c 65 66 74 20 69 6e 20 74 68 65 20 70 61 67 65 left in the page
36170 20 63 61 63 68 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a cache.</dd>.**.
36180 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 ** <dt>SQLITE_ST
36190 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 53 ATUS_PAGECACHE_S
361a0 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e IZE</dt>.** <dd>
361b0 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 This parameter r
361c0 65 63 6f 72 64 73 20 74 68 65 20 6c 61 72 67 65 ecords the large
361d0 73 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 st memory alloca
361e0 74 69 6f 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 tion request.**
361f0 68 61 6e 64 65 64 20 74 6f 20 5b 70 61 67 65 63 handed to [pagec
36200 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ache memory allo
36210 63 61 74 6f 72 5d 2e 20 20 4f 6e 6c 79 20 74 68 cator]. Only th
36220 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
36230 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67 in the.** *pHig
36240 68 77 61 74 65 72 20 70 61 72 61 6d 65 74 65 72 hwater parameter
36250 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 to [sqlite3_sta
36260 74 75 73 28 29 5d 20 69 73 20 6f 66 20 69 6e 74 tus()] is of int
36270 65 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20 erest. .** The
36280 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 69 6e value written in
36290 74 6f 20 74 68 65 20 2a 70 43 75 72 72 65 6e 74 to the *pCurrent
362a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 6e parameter is un
362b0 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a defined.</dd>.**
362c0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 .** <dt>SQLITE_S
362d0 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f 55 53 TATUS_SCRATCH_US
362e0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ED</dt>.** <dd>T
362f0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 his parameter re
36300 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
36310 20 6f 66 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 of allocations
36320 75 73 65 64 20 6f 75 74 20 6f 66 20 74 68 65 0a used out of the.
36330 2a 2a 20 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f ** [scratch memo
36340 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f ry allocator] co
36350 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67 0a 2a nfigured using.*
36360 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
36370 5f 53 43 52 41 54 43 48 5d 2e 20 20 54 68 65 20 _SCRATCH]. The
36380 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 value returned i
36390 73 20 69 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 s in allocations
363a0 2c 20 6e 6f 74 0a 2a 2a 20 69 6e 20 62 79 74 65 , not.** in byte
363b0 73 2e 20 20 53 69 6e 63 65 20 61 20 73 69 6e 67 s. Since a sing
363c0 6c 65 20 74 68 72 65 61 64 20 6d 61 79 20 6f 6e le thread may on
363d0 6c 79 20 68 61 76 65 20 6f 6e 65 20 73 63 72 61 ly have one scra
363e0 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a tch allocation.*
363f0 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 61 74 * outstanding at
36400 20 74 69 6d 65 2c 20 74 68 69 73 20 70 61 72 61 time, this para
36410 6d 65 74 65 72 20 61 6c 73 6f 20 72 65 70 6f 72 meter also repor
36420 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ts the number of
36430 20 74 68 72 65 61 64 73 0a 2a 2a 20 75 73 69 6e threads.** usin
36440 67 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 g scratch memory
36450 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
36460 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 e.</dd>.**.** <d
36470 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f t>SQLITE_STATUS_
36480 53 43 52 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57 SCRATCH_OVERFLOW
36490 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
364a0 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 s parameter retu
364b0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
364c0 66 20 62 79 74 65 73 20 6f 66 20 73 63 72 61 74 f bytes of scrat
364d0 63 68 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c ch memory.** all
364e0 6f 63 61 74 69 6f 6e 20 77 68 69 63 68 20 63 6f ocation which co
364f0 75 6c 64 20 6e 6f 74 20 62 65 20 73 74 61 74 69 uld not be stati
36500 73 66 69 65 64 20 62 79 20 74 68 65 20 5b 53 51 sfied by the [SQ
36510 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
36520 54 43 48 5d 0a 2a 2a 20 62 75 66 66 65 72 20 61 TCH].** buffer a
36530 6e 64 20 77 68 65 72 65 20 66 6f 72 63 65 64 20 nd where forced
36540 74 6f 20 6f 76 65 72 66 6c 6f 77 20 74 6f 20 5b to overflow to [
36550 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
36560 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 73 0a 2a ]. The values.*
36570 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 63 6c 75 * returned inclu
36580 64 65 20 6f 76 65 72 66 6c 6f 77 73 20 62 65 63 de overflows bec
36590 61 75 73 65 20 74 68 65 20 72 65 71 75 65 73 74 ause the request
365a0 65 64 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 ed allocation wa
365b0 73 20 74 6f 6f 0a 2a 2a 20 6c 61 72 67 65 72 20 s too.** larger
365c0 28 74 68 61 74 20 69 73 2c 20 62 65 63 61 75 73 (that is, becaus
365d0 65 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 e the requested
365e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 6c allocation was l
365f0 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a arger than the.*
36600 2a 20 22 73 7a 22 20 70 61 72 61 6d 65 74 65 72 * "sz" parameter
36610 20 74 6f 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 to [SQLITE_CONF
36620 49 47 5f 53 43 52 41 54 43 48 5d 29 20 61 6e 64 IG_SCRATCH]) and
36630 20 62 65 63 61 75 73 65 20 6e 6f 20 73 63 72 61 because no scra
36640 74 63 68 20 62 75 66 66 65 72 0a 2a 2a 20 73 6c tch buffer.** sl
36650 6f 74 73 20 77 65 72 65 20 61 76 61 69 6c 61 62 ots were availab
36660 6c 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a le..** </dd>.**.
36670 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 ** <dt>SQLITE_ST
36680 41 54 55 53 5f 53 43 52 41 54 43 48 5f 53 49 5a ATUS_SCRATCH_SIZ
36690 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 E</dt>.** <dd>Th
366a0 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 63 is parameter rec
366b0 6f 72 64 73 20 74 68 65 20 6c 61 72 67 65 73 74 ords the largest
366c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
366d0 6f 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 on request.** ha
366e0 6e 64 65 64 20 74 6f 20 5b 73 63 72 61 74 63 68 nded to [scratch
366f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
36700 72 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 r]. Only the va
36710 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 lue returned in
36720 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 the.** *pHighwat
36730 65 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 er parameter to
36740 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 [sqlite3_status(
36750 29 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65 73 )] is of interes
36760 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 t. .** The valu
36770 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 e written into t
36780 68 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61 72 he *pCurrent par
36790 61 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66 69 ameter is undefi
367a0 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ned.</dd>.**.**
367b0 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 <dt>SQLITE_STATU
367c0 53 5f 50 41 52 53 45 52 5f 53 54 41 43 4b 3c 2f S_PARSER_STACK</
367d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
367e0 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 parameter record
367f0 73 20 74 68 65 20 64 65 65 70 65 73 74 20 70 61 s the deepest pa
36800 72 73 65 72 20 73 74 61 63 6b 2e 20 20 49 74 20 rser stack. It
36810 69 73 20 6f 6e 6c 79 0a 2a 2a 20 6d 65 61 6e 69 is only.** meani
36820 6e 67 66 75 6c 20 69 66 20 53 51 4c 69 74 65 20 ngful if SQLite
36830 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
36840 20 5b 59 59 54 52 41 43 4b 4d 41 58 53 54 41 43 [YYTRACKMAXSTAC
36850 4b 44 45 50 54 48 5d 2e 3c 2f 64 64 3e 0a 2a 2a KDEPTH].</dd>.**
36860 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 4e 65 77 </dl>.**.** New
36870 20 73 74 61 74 75 73 20 70 61 72 61 6d 65 74 65 status paramete
36880 72 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 rs may be added
36890 66 72 6f 6d 20 74 69 6d 65 20 74 6f 20 74 69 6d from time to tim
368a0 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e..*/.#define SQ
368b0 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f LITE_STATUS_MEMO
368c0 52 59 5f 55 53 45 44 20 20 20 20 20 20 20 20 20 RY_USED
368d0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
368e0 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 43 E_STATUS_PAGECAC
368f0 48 45 5f 55 53 45 44 20 20 20 20 20 20 20 31 0a HE_USED 1.
36900 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
36910 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f TATUS_PAGECACHE_
36920 4f 56 45 52 46 4c 4f 57 20 20 20 32 0a 23 64 65 OVERFLOW 2.#de
36930 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 fine SQLITE_STAT
36940 55 53 5f 53 43 52 41 54 43 48 5f 55 53 45 44 20 US_SCRATCH_USED
36950 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 3.#defin
36960 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f e SQLITE_STATUS_
36970 53 43 52 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57 SCRATCH_OVERFLOW
36980 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 4.#define S
36990 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c QLITE_STATUS_MAL
369a0 4c 4f 43 5f 53 49 5a 45 20 20 20 20 20 20 20 20 LOC_SIZE
369b0 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 5.#define SQLI
369c0 54 45 5f 53 54 41 54 55 53 5f 50 41 52 53 45 52 TE_STATUS_PARSER
369d0 5f 53 54 41 43 4b 20 20 20 20 20 20 20 20 20 36 _STACK 6
369e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
369f0 53 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 STATUS_PAGECACHE
36a00 5f 53 49 5a 45 20 20 20 20 20 20 20 37 0a 23 64 _SIZE 7.#d
36a10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 efine SQLITE_STA
36a20 54 55 53 5f 53 43 52 41 54 43 48 5f 53 49 5a 45 TUS_SCRATCH_SIZE
36a30 20 20 20 20 20 20 20 20 20 38 0a 0a 2f 2a 0a 2a 8../*.*
36a40 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 * CAPI3REF: Data
36a50 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 base Connection
36a60 53 74 61 74 75 73 20 7b 48 31 37 35 30 30 7d 20 Status {H17500}
36a70 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 <S60200>.** EXPE
36a80 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
36a90 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
36aa0 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 used to retriev
36ab0 65 20 72 75 6e 74 69 6d 65 20 73 74 61 74 75 73 e runtime status
36ac0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a information .**
36ad0 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 about a single
36ae0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
36af0 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 tion]. The firs
36b00 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 t argument is th
36b10 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f e.** database co
36b20 6e 6e 65 63 74 69 6f 6e 20 6f 62 6a 65 63 74 20 nnection object
36b30 74 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 74 to be interrogat
36b40 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ed. The second
36b50 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 74 argument.** is t
36b60 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 he parameter to
36b70 69 6e 74 65 72 72 6f 67 61 74 65 2e 20 20 43 75 interrogate. Cu
36b80 72 72 65 6e 74 6c 79 2c 20 74 68 65 20 6f 6e 6c rrently, the onl
36b90 79 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 0a y allowed value.
36ba0 2a 2a 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e ** for the secon
36bb0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 5b d parameter is [
36bc0 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f SQLITE_DBSTATUS_
36bd0 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 5d 2e LOOKASIDE_USED].
36be0 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6f .** Additional o
36bf0 70 74 69 6f 6e 73 20 77 69 6c 6c 20 6c 69 6b 65 ptions will like
36c00 6c 79 20 61 70 70 65 61 72 20 69 6e 20 66 75 74 ly appear in fut
36c10 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
36c20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 SQLite..**.** Th
36c30 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 e current value
36c40 6f 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 of the requested
36c50 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 77 72 parameter is wr
36c60 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 72 itten into *pCur
36c70 0a 2a 2a 20 61 6e 64 20 74 68 65 20 68 69 67 68 .** and the high
36c80 65 73 74 20 69 6e 73 74 61 6e 74 61 6e 65 6f 75 est instantaneou
36c90 73 20 76 61 6c 75 65 20 69 73 20 77 72 69 74 74 s value is writt
36ca0 65 6e 20 69 6e 74 6f 20 2a 70 48 69 77 74 72 2e en into *pHiwtr.
36cb0 20 20 49 66 0a 2a 2a 20 74 68 65 20 72 65 73 65 If.** the rese
36cc0 74 46 6c 67 20 69 73 20 74 72 75 65 2c 20 74 68 tFlg is true, th
36cd0 65 6e 20 74 68 65 20 68 69 67 68 65 73 74 20 69 en the highest i
36ce0 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 76 61 6c nstantaneous val
36cf0 75 65 20 69 73 0a 2a 2a 20 72 65 73 65 74 20 62 ue is.** reset b
36d00 61 63 6b 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 ack down to the
36d10 63 75 72 72 65 6e 74 20 76 61 6c 75 65 2e 0a 2a current value..*
36d20 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
36d30 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 sqlite3_status()
36d40 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 ] and [sqlite3_s
36d50 74 6d 74 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a tmt_status()]..*
36d60 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d /.SQLITE_EXPERIM
36d70 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 ENTAL int sqlite
36d80 33 5f 64 62 5f 73 74 61 74 75 73 28 73 71 6c 69 3_db_status(sqli
36d90 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 69 6e te3*, int op, in
36da0 74 20 2a 70 43 75 72 2c 20 69 6e 74 20 2a 70 48 t *pCur, int *pH
36db0 69 77 74 72 2c 20 69 6e 74 20 72 65 73 65 74 46 iwtr, int resetF
36dc0 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 lg);../*.** CAPI
36dd0 33 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 3REF: Status Par
36de0 61 6d 65 74 65 72 73 20 66 6f 72 20 64 61 74 61 ameters for data
36df0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
36e00 20 7b 48 31 37 35 32 30 7d 20 3c 48 31 37 35 30 {H17520} <H1750
36e10 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
36e20 41 4c 0a 2a 2a 0a 2a 2a 20 53 74 61 74 75 73 20 AL.**.** Status
36e30 76 65 72 62 73 20 66 6f 72 20 5b 73 71 6c 69 74 verbs for [sqlit
36e40 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 2e e3_db_status()].
36e50 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c .**.** <dl>.** <
36e60 64 74 3e 53 51 4c 49 54 45 5f 44 42 53 54 41 54 dt>SQLITE_DBSTAT
36e70 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45 US_LOOKASIDE_USE
36e80 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
36e90 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 is parameter ret
36ea0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
36eb0 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d of lookaside mem
36ec0 6f 72 79 20 73 6c 6f 74 73 20 63 75 72 72 65 6e ory slots curren
36ed0 74 6c 79 0a 2a 2a 20 63 68 65 63 6b 65 64 20 6f tly.** checked o
36ee0 75 74 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c ut.</dd>.** </dl
36ef0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c >.*/.#define SQL
36f00 49 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f ITE_DBSTATUS_LOO
36f10 4b 41 53 49 44 45 5f 55 53 45 44 20 20 20 20 20 KASIDE_USED
36f20 30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 0.../*.** CAPI3R
36f30 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 EF: Prepared Sta
36f40 74 65 6d 65 6e 74 20 53 74 61 74 75 73 20 7b 48 tement Status {H
36f50 31 37 35 35 30 7d 20 3c 53 36 30 32 30 30 3e 0a 17550} <S60200>.
36f60 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
36f70 2a 2a 0a 2a 2a 20 45 61 63 68 20 70 72 65 70 61 **.** Each prepa
36f80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 red statement ma
36f90 69 6e 74 61 69 6e 73 20 76 61 72 69 6f 75 73 0a intains various.
36fa0 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 53 ** [SQLITE_STMTS
36fb0 54 41 54 55 53 5f 53 4f 52 54 20 7c 20 63 6f 75 TATUS_SORT | cou
36fc0 6e 74 65 72 73 5d 20 74 68 61 74 20 6d 65 61 73 nters] that meas
36fd0 75 72 65 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a ure the number.*
36fe0 2a 20 6f 66 20 74 69 6d 65 73 20 69 74 20 68 61 * of times it ha
36ff0 73 20 70 65 72 66 6f 72 6d 65 64 20 73 70 65 63 s performed spec
37000 69 66 69 63 20 6f 70 65 72 61 74 69 6f 6e 73 2e ific operations.
37010 20 20 54 68 65 73 65 20 63 6f 75 6e 74 65 72 73 These counters
37020 20 63 61 6e 0a 2a 2a 20 62 65 20 75 73 65 64 20 can.** be used
37030 74 6f 20 6d 6f 6e 69 74 6f 72 20 74 68 65 20 70 to monitor the p
37040 65 72 66 6f 72 6d 61 6e 63 65 20 63 68 61 72 61 erformance chara
37050 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 cteristics of th
37060 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 e prepared.** st
37070 61 74 65 6d 65 6e 74 73 2e 20 20 46 6f 72 20 65 atements. For e
37080 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 6e xample, if the n
37090 75 6d 62 65 72 20 6f 66 20 74 61 62 6c 65 20 73 umber of table s
370a0 74 65 70 73 20 67 72 65 61 74 6c 79 20 65 78 63 teps greatly exc
370b0 65 65 64 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 eeds.** the numb
370c0 65 72 20 6f 66 20 74 61 62 6c 65 20 73 65 61 72 er of table sear
370d0 63 68 65 73 20 6f 72 20 72 65 73 75 6c 74 20 72 ches or result r
370e0 6f 77 73 2c 20 74 68 61 74 20 77 6f 75 6c 64 20 ows, that would
370f0 74 65 6e 64 20 74 6f 20 69 6e 64 69 63 61 74 65 tend to indicate
37100 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 65 .** that the pre
37110 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
37120 69 73 20 75 73 69 6e 67 20 61 20 66 75 6c 6c 20 is using a full
37130 74 61 62 6c 65 20 73 63 61 6e 20 72 61 74 68 65 table scan rathe
37140 72 20 74 68 61 6e 0a 2a 2a 20 61 6e 20 69 6e 64 r than.** an ind
37150 65 78 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ex. .**.** This
37160 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 interface is us
37170 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 ed to retrieve a
37180 6e 64 20 72 65 73 65 74 20 63 6f 75 6e 74 65 72 nd reset counter
37190 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 values from.**
371a0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
371b0 65 6d 65 6e 74 5d 2e 20 20 54 68 65 20 66 69 72 ement]. The fir
371c0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 st argument is t
371d0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 he prepared stat
371e0 65 6d 65 6e 74 0a 2a 2a 20 6f 62 6a 65 63 74 20 ement.** object
371f0 74 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 74 to be interrogat
37200 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ed. The second
37210 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 argument.** is a
37220 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 66 n integer code f
37230 6f 72 20 61 20 73 70 65 63 69 66 69 63 20 5b 53 or a specific [S
37240 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 QLITE_STMTSTATUS
37250 5f 53 4f 52 54 20 7c 20 63 6f 75 6e 74 65 72 5d _SORT | counter]
37260 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 .** to be interr
37270 6f 67 61 74 65 64 2e 20 0a 2a 2a 20 54 68 65 20 ogated. .** The
37280 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 current value of
37290 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 63 the requested c
372a0 6f 75 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e ounter is return
372b0 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 ed..** If the re
372c0 73 65 74 46 6c 67 20 69 73 20 74 72 75 65 2c 20 setFlg is true,
372d0 74 68 65 6e 20 74 68 65 20 63 6f 75 6e 74 65 72 then the counter
372e0 20 69 73 20 72 65 73 65 74 20 74 6f 20 7a 65 72 is reset to zer
372f0 6f 20 61 66 74 65 72 20 74 68 69 73 0a 2a 2a 20 o after this.**
37300 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 72 interface call r
37310 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 eturns..**.** Se
37320 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
37330 5f 73 74 61 74 75 73 28 29 5d 20 61 6e 64 20 5b _status()] and [
37340 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 sqlite3_db_statu
37350 73 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f s()]..*/.SQLITE_
37360 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 EXPERIMENTAL int
37370 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 73 74 sqlite3_stmt_st
37380 61 74 75 73 28 73 71 6c 69 74 65 33 5f 73 74 6d atus(sqlite3_stm
37390 74 2a 2c 20 69 6e 74 20 6f 70 2c 69 6e 74 20 72 t*, int op,int r
373a0 65 73 65 74 46 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a esetFlg);../*.**
373b0 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 74 75 CAPI3REF: Statu
373c0 73 20 50 61 72 61 6d 65 74 65 72 73 20 66 6f 72 s Parameters for
373d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
373e0 65 6e 74 73 20 7b 48 31 37 35 37 30 7d 20 3c 48 ents {H17570} <H
373f0 31 37 35 35 30 3e 0a 2a 2a 20 45 58 50 45 52 49 17550>.** EXPERI
37400 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 MENTAL.**.** The
37410 73 65 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 se preprocessor
37420 6d 61 63 72 6f 73 20 64 65 66 69 6e 65 20 69 6e macros define in
37430 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 teger codes that
37440 20 6e 61 6d 65 20 63 6f 75 6e 74 65 72 0a 2a 2a name counter.**
37450 20 76 61 6c 75 65 73 20 61 73 73 6f 63 69 61 74 values associat
37460 65 64 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c ed with the [sql
37470 69 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 ite3_stmt_status
37480 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
37490 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f * The meanings o
374a0 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 63 6f f the various co
374b0 75 6e 74 65 72 73 20 61 72 65 20 61 73 20 66 6f unters are as fo
374c0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c llows:.**.** <dl
374d0 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f >.** <dt>SQLITE_
374e0 53 54 4d 54 53 54 41 54 55 53 5f 46 55 4c 4c 53 STMTSTATUS_FULLS
374f0 43 41 4e 5f 53 54 45 50 3c 2f 64 74 3e 0a 2a 2a CAN_STEP</dt>.**
37500 20 3c 64 64 3e 54 68 69 73 20 69 73 20 74 68 65 <dd>This is the
37510 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 number of times
37520 20 74 68 61 74 20 53 51 4c 69 74 65 20 68 61 73 that SQLite has
37530 20 73 74 65 70 70 65 64 20 66 6f 72 77 61 72 64 stepped forward
37540 20 69 6e 0a 2a 2a 20 61 20 74 61 62 6c 65 20 61 in.** a table a
37550 73 20 70 61 72 74 20 6f 66 20 61 20 66 75 6c 6c s part of a full
37560 20 74 61 62 6c 65 20 73 63 61 6e 2e 20 20 4c 61 table scan. La
37570 72 67 65 20 6e 75 6d 62 65 72 73 20 66 6f 72 20 rge numbers for
37580 74 68 69 73 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 this counter.**
37590 6d 61 79 20 69 6e 64 69 63 61 74 65 20 6f 70 70 may indicate opp
375a0 6f 72 74 75 6e 69 74 69 65 73 20 66 6f 72 20 70 ortunities for p
375b0 65 72 66 6f 72 6d 61 6e 63 65 20 69 6d 70 72 6f erformance impro
375c0 76 65 6d 65 6e 74 20 74 68 72 6f 75 67 68 20 0a vement through .
375d0 2a 2a 20 63 61 72 65 66 75 6c 20 75 73 65 20 6f ** careful use o
375e0 66 20 69 6e 64 69 63 65 73 2e 3c 2f 64 64 3e 0a f indices.</dd>.
375f0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
37600 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 _STMTSTATUS_SORT
37610 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
37620 73 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 s is the number
37630 6f 66 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f of sort operatio
37640 6e 73 20 74 68 61 74 20 68 61 76 65 20 6f 63 63 ns that have occ
37650 75 72 72 65 64 2e 0a 2a 2a 20 41 20 6e 6f 6e 2d urred..** A non-
37660 7a 65 72 6f 20 76 61 6c 75 65 20 69 6e 20 74 68 zero value in th
37670 69 73 20 63 6f 75 6e 74 65 72 20 6d 61 79 20 69 is counter may i
37680 6e 64 69 63 61 74 65 20 61 6e 20 6f 70 70 6f 72 ndicate an oppor
37690 74 75 6e 69 74 79 20 74 6f 0a 2a 2a 20 69 6d 70 tunity to.** imp
376a0 72 6f 76 65 6d 65 6e 74 20 70 65 72 66 6f 72 6d rovement perform
376b0 61 6e 63 65 20 74 68 72 6f 75 67 68 20 63 61 72 ance through car
376c0 65 66 75 6c 20 75 73 65 20 6f 66 20 69 6e 64 69 eful use of indi
376d0 63 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ces.</dd>.**.**
376e0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </dl>.*/.#define
376f0 20 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 SQLITE_STMTSTAT
37700 55 53 5f 46 55 4c 4c 53 43 41 4e 5f 53 54 45 50 US_FULLSCAN_STEP
37710 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
37720 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 QLITE_STMTSTATUS
37730 5f 53 4f 52 54 20 20 20 20 20 20 20 20 20 20 20 _SORT
37740 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 2../*.** CAPI
37750 33 52 45 46 3a 20 43 75 73 74 6f 6d 20 50 61 67 3REF: Custom Pag
37760 65 20 43 61 63 68 65 20 4f 62 6a 65 63 74 0a 2a e Cache Object.*
37770 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
37780 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
37790 5f 70 63 61 63 68 65 20 74 79 70 65 20 69 73 20 _pcache type is
377a0 6f 70 61 71 75 65 2e 20 20 49 74 20 69 73 20 69 opaque. It is i
377b0 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 0a 2a 2a mplemented by.**
377c0 20 74 68 65 20 70 6c 75 67 67 61 62 6c 65 20 6d the pluggable m
377d0 6f 64 75 6c 65 2e 20 20 54 68 65 20 53 51 4c 69 odule. The SQLi
377e0 74 65 20 63 6f 72 65 20 68 61 73 20 6e 6f 20 6b te core has no k
377f0 6e 6f 77 6c 65 64 67 65 20 6f 66 0a 2a 2a 20 69 nowledge of.** i
37800 74 73 20 73 69 7a 65 20 6f 72 20 69 6e 74 65 72 ts size or inter
37810 6e 61 6c 20 73 74 72 75 63 74 75 72 65 20 61 6e nal structure an
37820 64 20 6e 65 76 65 72 20 64 65 61 6c 73 20 77 69 d never deals wi
37830 74 68 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 th the.** sqlite
37840 33 5f 70 63 61 63 68 65 20 6f 62 6a 65 63 74 20 3_pcache object
37850 65 78 63 65 70 74 20 62 79 20 68 6f 6c 64 69 6e except by holdin
37860 67 20 61 6e 64 20 70 61 73 73 69 6e 67 20 70 6f g and passing po
37870 69 6e 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 inters.** to the
37880 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 53 object..**.** S
37890 65 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 ee [sqlite3_pcac
378a0 68 65 5f 6d 65 74 68 6f 64 73 5d 20 66 6f 72 20 he_methods] for
378b0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 additional infor
378c0 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 mation..*/.typed
378d0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
378e0 33 5f 70 63 61 63 68 65 20 73 71 6c 69 74 65 33 3_pcache sqlite3
378f0 5f 70 63 61 63 68 65 3b 0a 0a 2f 2a 0a 2a 2a 20 _pcache;../*.**
37900 43 41 50 49 33 52 45 46 3a 20 41 70 70 6c 69 63 CAPI3REF: Applic
37910 61 74 69 6f 6e 20 44 65 66 69 6e 65 64 20 50 61 ation Defined Pa
37920 67 65 20 43 61 63 68 65 2e 0a 2a 2a 20 45 58 50 ge Cache..** EXP
37930 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
37940 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e The [sqlite3_con
37950 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e fig]([SQLITE_CON
37960 46 49 47 5f 50 43 41 43 48 45 5d 2c 20 2e 2e 2e FIG_PCACHE], ...
37970 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 0a ) interface can.
37980 2a 2a 20 72 65 67 69 73 74 65 72 20 61 6e 20 61 ** register an a
37990 6c 74 65 72 6e 61 74 69 76 65 20 70 61 67 65 20 lternative page
379a0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
379b0 74 69 6f 6e 20 62 79 20 70 61 73 73 69 6e 67 20 tion by passing
379c0 69 6e 20 61 6e 20 0a 2a 2a 20 69 6e 73 74 61 6e in an .** instan
379d0 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 ce of the sqlite
379e0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
379f0 20 73 74 72 75 63 74 75 72 65 2e 20 54 68 65 20 structure. The
37a00 6d 61 6a 6f 72 69 74 79 20 6f 66 20 74 68 65 20 majority of the
37a10 0a 2a 2a 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 .** heap memory
37a20 75 73 65 64 20 62 79 20 73 71 6c 69 74 65 20 69 used by sqlite i
37a30 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 s used by the pa
37a40 67 65 20 63 61 63 68 65 20 74 6f 20 63 61 63 68 ge cache to cach
37a50 65 20 64 61 74 61 20 72 65 61 64 20 0a 2a 2a 20 e data read .**
37a60 66 72 6f 6d 2c 20 6f 72 20 72 65 61 64 79 20 74 from, or ready t
37a70 6f 20 62 65 20 77 72 69 74 74 65 6e 20 74 6f 2c o be written to,
37a80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
37a90 6c 65 2e 20 42 79 20 69 6d 70 6c 65 6d 65 6e 74 le. By implement
37aa0 69 6e 67 20 61 20 0a 2a 2a 20 63 75 73 74 6f 6d ing a .** custom
37ab0 20 70 61 67 65 20 63 61 63 68 65 20 75 73 69 6e page cache usin
37ac0 67 20 74 68 69 73 20 41 50 49 2c 20 61 6e 20 61 g this API, an a
37ad0 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 63 pplication can c
37ae0 6f 6e 74 72 6f 6c 20 6d 6f 72 65 20 0a 2a 2a 20 ontrol more .**
37af0 70 72 65 63 69 73 65 6c 79 20 74 68 65 20 61 6d precisely the am
37b00 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 63 ount of memory c
37b10 6f 6e 73 75 6d 65 64 20 62 79 20 73 71 6c 69 74 onsumed by sqlit
37b20 65 2c 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 e, the way in wh
37b30 69 63 68 20 0a 2a 2a 20 73 61 69 64 20 6d 65 6d ich .** said mem
37b40 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 ory is allocated
37b50 20 61 6e 64 20 72 65 6c 65 61 73 65 64 2c 20 61 and released, a
37b60 6e 64 20 74 68 65 20 70 6f 6c 69 63 69 65 73 20 nd the policies
37b70 75 73 65 64 20 74 6f 20 0a 2a 2a 20 64 65 74 65 used to .** dete
37b80 72 6d 69 6e 65 20 65 78 61 63 74 6c 79 20 77 68 rmine exactly wh
37b90 69 63 68 20 70 61 72 74 73 20 6f 66 20 61 20 64 ich parts of a d
37ba0 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 72 65 atabase file are
37bb0 20 63 61 63 68 65 64 20 61 6e 64 20 66 6f 72 20 cached and for
37bc0 0a 2a 2a 20 68 6f 77 20 6c 6f 6e 67 2e 0a 2a 2a .** how long..**
37bd0 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 6e 74 73 .** The contents
37be0 20 6f 66 20 74 68 65 20 73 74 72 75 63 74 75 72 of the structur
37bf0 65 20 61 72 65 20 63 6f 70 69 65 64 20 74 6f 20 e are copied to
37c00 61 6e 20 69 6e 74 65 72 6e 61 6c 20 62 75 66 66 an internal buff
37c10 65 72 20 62 79 20 73 71 6c 69 74 65 0a 2a 2a 20 er by sqlite.**
37c20 77 69 74 68 69 6e 20 74 68 65 20 63 61 6c 6c 20 within the call
37c30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to [sqlite3_conf
37c40 69 67 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ig]..**.** The x
37c50 49 6e 69 74 28 29 20 6d 65 74 68 6f 64 20 69 73 Init() method is
37c60 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 called once for
37c70 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 each call to [s
37c80 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
37c90 65 28 29 5d 0a 2a 2a 20 28 75 73 75 61 6c 6c 79 e()].** (usually
37ca0 20 6f 6e 6c 79 20 6f 6e 63 65 20 64 75 72 69 6e only once durin
37cb0 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f g the lifetime o
37cc0 66 20 74 68 65 20 70 72 6f 63 65 73 73 29 2e 20 f the process).
37cd0 49 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 It is passed.**
37ce0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 73 71 a copy of the sq
37cf0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
37d00 68 6f 64 73 2e 70 41 72 67 20 76 61 6c 75 65 2e hods.pArg value.
37d10 20 49 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 It can be used
37d20 74 6f 20 73 65 74 0a 2a 2a 20 75 70 20 67 6c 6f to set.** up glo
37d30 62 61 6c 20 73 74 72 75 63 74 75 72 65 73 20 61 bal structures a
37d40 6e 64 20 6d 75 74 65 78 65 73 20 72 65 71 75 69 nd mutexes requi
37d50 72 65 64 20 62 79 20 74 68 65 20 63 75 73 74 6f red by the custo
37d60 6d 20 70 61 67 65 20 63 61 63 68 65 20 0a 2a 2a m page cache .**
37d70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
37d80 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 28 29 The xShutdown()
37d90 20 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c 65 method is calle
37da0 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 0a 2a d from within .*
37db0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 * [sqlite3_shutd
37dc0 6f 77 6e 28 29 5d 2c 20 69 66 20 74 68 65 20 61 own()], if the a
37dd0 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 76 6f 6b pplication invok
37de0 65 73 20 74 68 69 73 20 41 50 49 2e 20 49 74 20 es this API. It
37df0 63 61 6e 20 62 65 20 75 73 65 64 0a 2a 2a 20 74 can be used.** t
37e00 6f 20 63 6c 65 61 6e 20 75 70 20 61 6e 79 20 6f o clean up any o
37e10 75 74 73 74 61 6e 64 69 6e 67 20 72 65 73 6f 75 utstanding resou
37e20 72 63 65 73 20 62 65 66 6f 72 65 20 70 72 6f 63 rces before proc
37e30 65 73 73 20 73 68 75 74 64 6f 77 6e 2c 20 69 66 ess shutdown, if
37e40 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a required..**.**
37e50 20 54 68 65 20 78 43 72 65 61 74 65 28 29 20 6d The xCreate() m
37e60 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 74 6f ethod is used to
37e70 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 construct a new
37e80 20 63 61 63 68 65 20 69 6e 73 74 61 6e 63 65 2e cache instance.
37e90 20 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 The.** first pa
37ea0 72 61 6d 65 74 65 72 2c 20 73 7a 50 61 67 65 2c rameter, szPage,
37eb0 20 69 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20 is the size in
37ec0 62 79 74 65 73 20 6f 66 20 74 68 65 20 70 61 67 bytes of the pag
37ed0 65 73 20 74 68 61 74 20 6d 75 73 74 0a 2a 2a 20 es that must.**
37ee0 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 be allocated by
37ef0 74 68 65 20 63 61 63 68 65 2e 20 73 7a 50 61 67 the cache. szPag
37f00 65 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 61 20 e will not be a
37f10 70 6f 77 65 72 20 6f 66 20 74 77 6f 2e 20 54 68 power of two. Th
37f20 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 61 72 67 75 e.** second argu
37f30 6d 65 6e 74 2c 20 62 50 75 72 67 65 61 62 6c 65 ment, bPurgeable
37f40 2c 20 69 73 20 74 72 75 65 20 69 66 20 74 68 65 , is true if the
37f50 20 63 61 63 68 65 20 62 65 69 6e 67 20 63 72 65 cache being cre
37f60 61 74 65 64 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 ated will.** be
37f70 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 used to cache da
37f80 74 61 62 61 73 65 20 70 61 67 65 73 20 72 65 61 tabase pages rea
37f90 64 20 66 72 6f 6d 20 61 20 66 69 6c 65 20 73 74 d from a file st
37fa0 6f 72 65 64 20 6f 6e 20 64 69 73 6b 2c 20 6f 72 ored on disk, or
37fb0 0a 2a 2a 20 66 61 6c 73 65 20 69 66 20 69 74 20 .** false if it
37fc0 69 73 20 75 73 65 64 20 66 6f 72 20 61 6e 20 69 is used for an i
37fd0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 n-memory databas
37fe0 65 2e 20 54 68 65 20 63 61 63 68 65 20 69 6d 70 e. The cache imp
37ff0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 64 lementation.** d
38000 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 20 oes not have to
38010 64 6f 20 61 6e 79 74 68 69 6e 67 20 73 70 65 63 do anything spec
38020 69 61 6c 20 62 61 73 65 64 20 6f 6e 20 74 68 65 ial based on the
38030 20 76 61 6c 75 65 20 6f 66 20 62 50 75 72 67 65 value of bPurge
38040 61 62 6c 65 2c 0a 2a 2a 20 69 74 20 69 73 20 70 able,.** it is p
38050 75 72 65 6c 79 20 61 64 76 69 73 6f 72 79 2e 20 urely advisory.
38060 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 61 63 68 .**.** The xCach
38070 65 73 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 6d esize() method m
38080 61 79 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 ay be called at
38090 61 6e 79 20 74 69 6d 65 20 62 79 20 53 51 4c 69 any time by SQLi
380a0 74 65 20 74 6f 20 73 65 74 20 74 68 65 0a 2a 2a te to set the.**
380b0 20 73 75 67 67 65 73 74 65 64 20 6d 61 78 69 6d suggested maxim
380c0 75 6d 20 63 61 63 68 65 2d 73 69 7a 65 20 28 6e um cache-size (n
380d0 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 73 umber of pages s
380e0 74 6f 72 65 64 20 62 79 29 20 74 68 65 20 63 61 tored by) the ca
380f0 63 68 65 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 che.** instance
38100 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 passed as the fi
38110 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 rst argument. Th
38120 69 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 is is the value
38130 63 6f 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67 configured using
38140 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 22 .** the SQLite "
38150 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 [PRAGMA cache_si
38160 7a 65 5d 22 20 63 6f 6d 6d 61 6e 64 2e 20 41 73 ze]" command. As
38170 20 77 69 74 68 20 74 68 65 20 62 50 75 72 67 65 with the bPurge
38180 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 2c 0a able parameter,.
38190 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 ** the implement
381a0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 ation is not req
381b0 75 69 72 65 64 20 74 6f 20 64 6f 20 61 6e 79 74 uired to do anyt
381c0 68 69 6e 67 20 73 70 65 63 69 61 6c 20 77 69 74 hing special wit
381d0 68 20 74 68 69 73 0a 2a 2a 20 76 61 6c 75 65 2c h this.** value,
381e0 20 69 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 it is advisory
381f0 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 only..**.** The
38200 78 50 61 67 65 63 6f 75 6e 74 28 29 20 6d 65 74 xPagecount() met
38210 68 6f 64 20 73 68 6f 75 6c 64 20 72 65 74 75 72 hod should retur
38220 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 n the number of
38230 70 61 67 65 73 20 63 75 72 72 65 6e 74 6c 79 0a pages currently.
38240 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 ** stored in the
38250 20 63 61 63 68 65 20 73 75 70 70 6c 69 65 64 20 cache supplied
38260 61 73 20 61 6e 20 61 72 67 75 6d 65 6e 74 2e 0a as an argument..
38270 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 46 65 74 63 ** .** The xFetc
38280 68 28 29 20 6d 65 74 68 6f 64 20 69 73 20 75 73 h() method is us
38290 65 64 20 74 6f 20 66 65 74 63 68 20 61 20 70 61 ed to fetch a pa
382a0 67 65 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 ge and return a
382b0 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 0a pointer to it. .
382c0 2a 2a 20 41 20 27 70 61 67 65 27 2c 20 69 6e 20 ** A 'page', in
382d0 74 68 69 73 20 63 6f 6e 74 65 78 74 2c 20 69 73 this context, is
382e0 20 61 20 62 75 66 66 65 72 20 6f 66 20 73 7a 50 a buffer of szP
382f0 61 67 65 20 62 79 74 65 73 20 61 6c 69 67 6e 65 age bytes aligne
38300 64 20 61 74 20 61 6e 0a 2a 2a 20 38 2d 62 79 74 d at an.** 8-byt
38310 65 20 62 6f 75 6e 64 61 72 79 2e 20 54 68 65 20 e boundary. The
38320 70 61 67 65 20 74 6f 20 62 65 20 66 65 74 63 68 page to be fetch
38330 65 64 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 ed is determined
38340 20 62 79 20 74 68 65 20 6b 65 79 2e 20 54 68 65 by the key. The
38350 0a 2a 2a 20 6d 69 6d 69 6d 75 6d 20 6b 65 79 20 .** mimimum key
38360 76 61 6c 75 65 20 69 73 20 31 2e 20 41 66 74 65 value is 1. Afte
38370 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 r it has been re
38380 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 78 46 trieved using xF
38390 65 74 63 68 2c 20 74 68 65 20 70 61 67 65 20 0a etch, the page .
383a0 2a 2a 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 ** is considered
383b0 20 74 6f 20 62 65 20 70 69 6e 6e 65 64 2e 0a 2a to be pinned..*
383c0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 71 75 *.** If the requ
383d0 65 73 74 65 64 20 70 61 67 65 20 69 73 20 61 6c ested page is al
383e0 72 65 61 64 79 20 69 6e 20 74 68 65 20 70 61 67 ready in the pag
383f0 65 20 63 61 63 68 65 2c 20 74 68 65 6e 20 61 20 e cache, then a
38400 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 pointer to.** th
38410 65 20 63 61 63 68 65 64 20 62 75 66 66 65 72 20 e cached buffer
38420 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e should be return
38430 65 64 20 77 69 74 68 20 69 74 73 20 63 6f 6e 74 ed with its cont
38440 65 6e 74 73 20 69 6e 74 61 63 74 2e 20 49 66 20 ents intact. If
38450 74 68 65 0a 2a 2a 20 70 61 67 65 20 69 73 20 6e the.** page is n
38460 6f 74 20 61 6c 72 65 61 64 79 20 69 6e 20 74 68 ot already in th
38470 65 20 63 61 63 68 65 2c 20 74 68 65 6e 20 74 68 e cache, then th
38480 65 20 65 78 70 65 63 74 65 64 20 62 65 68 61 76 e expected behav
38490 69 6f 75 72 20 6f 66 20 74 68 65 0a 2a 2a 20 63 iour of the.** c
384a0 61 63 68 65 20 69 73 20 64 65 74 65 72 6d 69 6e ache is determin
384b0 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 ed by the value
384c0 6f 66 20 74 68 65 20 63 72 65 61 74 65 46 6c 61 of the createFla
384d0 67 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 g parameter pass
384e0 65 64 0a 2a 2a 20 74 6f 20 78 46 65 74 63 68 2c ed.** to xFetch,
384f0 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 according to th
38500 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c e following tabl
38510 65 3a 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 e:.**.** <table
38520 62 6f 72 64 65 72 3d 31 20 77 69 64 74 68 3d 38 border=1 width=8
38530 35 25 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 3e 5% align=center>
38540 0a 2a 2a 20 20 20 3c 74 72 3e 3c 74 68 3e 63 72 .** <tr><th>cr
38550 65 61 74 65 46 6c 61 67 3c 74 68 3e 45 78 70 65 eateFlag<th>Expe
38560 63 74 65 64 20 42 65 68 61 76 69 6f 75 72 0a 2a cted Behaviour.*
38570 2a 20 20 20 3c 74 72 3e 3c 74 64 3e 30 3c 74 64 * <tr><td>0<td
38580 3e 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 >NULL should be
38590 72 65 74 75 72 6e 65 64 2e 20 4e 6f 20 6e 65 77 returned. No new
385a0 20 63 61 63 68 65 20 65 6e 74 72 79 20 69 73 20 cache entry is
385b0 63 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 3c 74 created..** <t
385c0 72 3e 3c 74 64 3e 31 3c 74 64 3e 49 66 20 63 72 r><td>1<td>If cr
385d0 65 61 74 65 46 6c 61 67 20 69 73 20 73 65 74 20 eateFlag is set
385e0 74 6f 20 31 2c 20 74 68 69 73 20 69 6e 64 69 63 to 1, this indic
385f0 61 74 65 73 20 74 68 61 74 20 0a 2a 2a 20 20 20 ates that .**
38600 20 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c SQL
38610 69 74 65 20 69 73 20 68 6f 6c 64 69 6e 67 20 70 ite is holding p
38620 69 6e 6e 65 64 20 70 61 67 65 73 20 74 68 61 74 inned pages that
38630 20 63 61 6e 20 62 65 20 75 6e 70 69 6e 6e 65 64 can be unpinned
38640 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 .**
38650 20 20 20 62 79 20 77 72 69 74 69 6e 67 20 74 68 by writing th
38660 65 69 72 20 63 6f 6e 74 65 6e 74 73 20 74 6f 20 eir contents to
38670 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
38680 65 20 28 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 e (a.**
38690 20 20 20 20 20 20 20 72 65 6c 61 74 69 76 65 6c relativel
386a0 79 20 65 78 70 65 6e 73 69 76 65 20 6f 70 65 72 y expensive oper
386b0 61 74 69 6f 6e 29 2e 20 49 6e 20 74 68 69 73 20 ation). In this
386c0 73 69 74 75 61 74 69 6f 6e 20 74 68 65 0a 2a 2a situation the.**
386d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
386e0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
386f0 74 69 6f 6e 20 68 61 73 20 74 77 6f 20 63 68 6f tion has two cho
38700 69 63 65 73 3a 20 69 74 20 63 61 6e 20 72 65 74 ices: it can ret
38710 75 72 6e 20 4e 55 4c 4c 2c 0a 2a 2a 20 20 20 20 urn NULL,.**
38720 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 20 77 in w
38730 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 hich case SQLite
38740 20 77 69 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f will attempt to
38750 20 75 6e 70 69 6e 20 6f 6e 65 20 6f 72 20 6d 6f unpin one or mo
38760 72 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 re .**
38770 20 20 20 20 20 20 70 61 67 65 73 20 62 65 66 6f pages befo
38780 72 65 20 72 65 2d 72 65 71 75 65 73 74 69 6e 67 re re-requesting
38790 20 74 68 65 20 73 61 6d 65 20 70 61 67 65 2c 20 the same page,
387a0 6f 72 20 69 74 20 63 61 6e 0a 2a 2a 20 20 20 20 or it can.**
387b0 20 20 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f allo
387c0 63 61 74 65 20 61 20 6e 65 77 20 70 61 67 65 20 cate a new page
387d0 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 and return a poi
387e0 6e 74 65 72 20 74 6f 20 69 74 2e 20 49 66 20 61 nter to it. If a
387f0 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 new.**
38800 20 20 20 20 20 20 20 70 61 67 65 20 69 73 20 61 page is a
38810 6c 6c 6f 63 61 74 65 64 2c 20 74 68 65 6e 20 74 llocated, then t
38820 68 65 20 66 69 72 73 74 20 73 69 7a 65 6f 66 28 he first sizeof(
38830 76 6f 69 64 2a 29 20 62 79 74 65 73 20 6f 66 0a void*) bytes of.
38840 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 **
38850 20 20 69 74 20 28 61 74 20 6c 65 61 73 74 29 20 it (at least)
38860 6d 75 73 74 20 62 65 20 7a 65 72 6f 65 64 20 62 must be zeroed b
38870 65 66 6f 72 65 20 69 74 20 69 73 20 72 65 74 75 efore it is retu
38880 72 6e 65 64 2e 0a 2a 2a 20 20 20 3c 74 72 3e 3c rned..** <tr><
38890 74 64 3e 32 3c 74 64 3e 49 66 20 63 72 65 61 74 td>2<td>If creat
388a0 65 46 6c 61 67 20 69 73 20 73 65 74 20 74 6f 20 eFlag is set to
388b0 32 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 69 2, then SQLite i
388c0 73 20 6e 6f 74 20 68 6f 6c 64 69 6e 67 20 61 6e s not holding an
388d0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 y.**
388e0 20 20 20 20 70 69 6e 6e 65 64 20 70 61 67 65 73 pinned pages
388f0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
38900 20 74 68 65 20 73 70 65 63 69 66 69 63 20 63 61 the specific ca
38910 63 68 65 20 70 61 73 73 65 64 0a 2a 2a 20 20 20 che passed.**
38920 20 20 20 20 20 20 20 20 20 20 20 20 20 61 73 20 as
38930 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
38940 6e 74 20 74 6f 20 78 46 65 74 63 68 28 29 20 74 nt to xFetch() t
38950 68 61 74 20 63 61 6e 20 62 65 20 75 6e 70 69 6e hat can be unpin
38960 6e 65 64 2e 20 54 68 65 0a 2a 2a 20 20 20 20 20 ned. The.**
38970 20 20 20 20 20 20 20 20 20 20 20 63 61 63 68 65 cache
38980 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
38990 73 68 6f 75 6c 64 20 61 74 74 65 6d 70 74 20 74 should attempt t
389a0 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 77 o allocate a new
389b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 .**
389c0 20 20 20 63 61 63 68 65 20 65 6e 74 72 79 20 61 cache entry a
389d0 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e nd return a poin
389e0 74 65 72 20 74 6f 20 69 74 2e 20 41 67 61 69 6e ter to it. Again
389f0 2c 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 20 , the first.**
38a00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 69 si
38a10 7a 65 6f 66 28 76 6f 69 64 2a 29 20 62 79 74 65 zeof(void*) byte
38a20 73 20 6f 66 20 74 68 65 20 70 61 67 65 20 73 68 s of the page sh
38a30 6f 75 6c 64 20 62 65 20 7a 65 72 6f 65 64 20 62 ould be zeroed b
38a40 65 66 6f 72 65 20 0a 2a 2a 20 20 20 20 20 20 20 efore .**
38a50 20 20 20 20 20 20 20 20 20 69 74 20 69 73 20 72 it is r
38a60 65 74 75 72 6e 65 64 2e 20 49 66 20 74 68 65 20 eturned. If the
38a70 78 46 65 74 63 68 28 29 20 6d 65 74 68 6f 64 20 xFetch() method
38a80 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 77 68 65 returns NULL whe
38a90 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 n .**
38aa0 20 20 20 20 20 63 72 65 61 74 65 46 6c 61 67 3d createFlag=
38ab0 3d 32 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d =2, SQLite assum
38ac0 65 73 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 es that a memory
38ad0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 allocation .**
38ae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 66 f
38af0 61 69 6c 65 64 20 61 6e 64 20 72 65 74 75 72 6e ailed and return
38b00 73 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 74 s SQLITE_NOMEM t
38b10 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 20 3c o the user..** <
38b20 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 78 55 /table>.**.** xU
38b30 6e 70 69 6e 28 29 20 69 73 20 63 61 6c 6c 65 64 npin() is called
38b40 20 62 79 20 53 51 4c 69 74 65 20 77 69 74 68 20 by SQLite with
38b50 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 a pointer to a c
38b60 75 72 72 65 6e 74 6c 79 20 70 69 6e 6e 65 64 20 urrently pinned
38b70 70 61 67 65 0a 2a 2a 20 61 73 20 69 74 73 20 73 page.** as its s
38b80 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 econd argument.
38b90 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 If the third par
38ba0 61 6d 65 74 65 72 2c 20 64 69 73 63 61 72 64 2c ameter, discard,
38bb0 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a is non-zero,.**
38bc0 20 74 68 65 6e 20 74 68 65 20 70 61 67 65 20 73 then the page s
38bd0 68 6f 75 6c 64 20 62 65 20 65 76 69 63 74 65 64 hould be evicted
38be0 20 66 72 6f 6d 20 74 68 65 20 63 61 63 68 65 2e from the cache.
38bf0 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 53 51 In this case SQ
38c00 4c 69 74 65 20 0a 2a 2a 20 61 73 73 75 6d 65 73 Lite .** assumes
38c10 20 74 68 61 74 20 74 68 65 20 6e 65 78 74 20 74 that the next t
38c20 69 6d 65 20 74 68 65 20 70 61 67 65 20 69 73 20 ime the page is
38c30 72 65 74 72 69 65 76 65 64 20 66 72 6f 6d 20 74 retrieved from t
38c40 68 65 20 63 61 63 68 65 20 75 73 69 6e 67 0a 2a he cache using.*
38c50 2a 20 74 68 65 20 78 46 65 74 63 68 28 29 20 6d * the xFetch() m
38c60 65 74 68 6f 64 2c 20 69 74 20 77 69 6c 6c 20 62 ethod, it will b
38c70 65 20 7a 65 72 6f 65 64 2e 20 49 66 20 74 68 65 e zeroed. If the
38c80 20 64 69 73 63 61 72 64 20 70 61 72 61 6d 65 74 discard paramet
38c90 65 72 20 69 73 0a 2a 2a 20 7a 65 72 6f 2c 20 74 er is.** zero, t
38ca0 68 65 6e 20 74 68 65 20 70 61 67 65 20 69 73 20 hen the page is
38cb0 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 considered to be
38cc0 20 75 6e 70 69 6e 6e 65 64 2e 20 54 68 65 20 63 unpinned. The c
38cd0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
38ce0 69 6f 6e 0a 2a 2a 20 6d 61 79 20 63 68 6f 6f 73 ion.** may choos
38cf0 65 20 74 6f 20 72 65 63 6c 61 69 6d 20 28 66 72 e to reclaim (fr
38d00 65 65 20 6f 72 20 72 65 63 79 63 6c 65 29 20 75 ee or recycle) u
38d10 6e 70 69 6e 6e 65 64 20 70 61 67 65 73 20 61 74 npinned pages at
38d20 20 61 6e 79 20 74 69 6d 65 2e 0a 2a 2a 20 53 51 any time..** SQ
38d30 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 Lite assumes tha
38d40 74 20 6e 65 78 74 20 74 69 6d 65 20 74 68 65 20 t next time the
38d50 70 61 67 65 20 69 73 20 72 65 74 72 69 65 76 65 page is retrieve
38d60 64 20 66 72 6f 6d 20 74 68 65 20 63 61 63 68 65 d from the cache
38d70 0a 2a 2a 20 69 74 20 77 69 6c 6c 20 65 69 74 68 .** it will eith
38d80 65 72 20 62 65 20 7a 65 72 6f 65 64 2c 20 6f 72 er be zeroed, or
38d90 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 73 61 6d contain the sam
38da0 65 20 64 61 74 61 20 74 68 61 74 20 69 74 20 64 e data that it d
38db0 69 64 20 77 68 65 6e 20 69 74 0a 2a 2a 20 77 61 id when it.** wa
38dc0 73 20 75 6e 70 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a s unpinned..**.*
38dd0 2a 20 54 68 65 20 63 61 63 68 65 20 69 73 20 6e * The cache is n
38de0 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 ot required to p
38df0 65 72 66 6f 72 6d 20 61 6e 79 20 72 65 66 65 72 erform any refer
38e00 65 6e 63 65 20 63 6f 75 6e 74 69 6e 67 2e 20 41 ence counting. A
38e10 20 73 69 6e 67 6c 65 20 0a 2a 2a 20 63 61 6c 6c single .** call
38e20 20 74 6f 20 78 55 6e 70 69 6e 28 29 20 75 6e 70 to xUnpin() unp
38e30 69 6e 73 20 74 68 65 20 70 61 67 65 20 72 65 67 ins the page reg
38e40 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e ardless of the n
38e50 75 6d 62 65 72 20 6f 66 20 70 72 69 6f 72 20 63 umber of prior c
38e60 61 6c 6c 73 20 0a 2a 2a 20 74 6f 20 78 46 65 74 alls .** to xFet
38e70 63 68 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ch()..**.** The
38e80 78 52 65 6b 65 79 28 29 20 6d 65 74 68 6f 64 20 xRekey() method
38e90 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 is used to chang
38ea0 65 20 74 68 65 20 6b 65 79 20 76 61 6c 75 65 20 e the key value
38eb0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
38ec0 74 68 65 0a 2a 2a 20 70 61 67 65 20 70 61 73 73 the.** page pass
38ed0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
38ee0 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 6f argument from o
38ef0 6c 64 4b 65 79 20 74 6f 20 6e 65 77 4b 65 79 2e ldKey to newKey.
38f00 20 49 66 20 74 68 65 20 63 61 63 68 65 0a 2a 2a If the cache.**
38f10 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6f 6e 74 previously cont
38f20 61 69 6e 73 20 61 6e 20 65 6e 74 72 79 20 61 73 ains an entry as
38f30 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 6e 65 sociated with ne
38f40 77 4b 65 79 2c 20 69 74 20 73 68 6f 75 6c 64 20 wKey, it should
38f50 62 65 0a 2a 2a 20 64 69 73 63 61 72 64 65 64 2e be.** discarded.
38f60 20 41 6e 79 20 70 72 69 6f 72 20 63 61 63 68 65 Any prior cache
38f70 20 65 6e 74 72 79 20 61 73 73 6f 63 69 61 74 65 entry associate
38f80 64 20 77 69 74 68 20 6e 65 77 4b 65 79 20 69 73 d with newKey is
38f90 20 67 75 61 72 61 6e 74 65 65 64 20 6e 6f 74 0a guaranteed not.
38fa0 2a 2a 20 74 6f 20 62 65 20 70 69 6e 6e 65 64 2e ** to be pinned.
38fb0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 .**.** When SQLi
38fc0 74 65 20 63 61 6c 6c 73 20 74 68 65 20 78 54 72 te calls the xTr
38fd0 75 6e 63 61 74 65 28 29 20 6d 65 74 68 6f 64 2c uncate() method,
38fe0 20 74 68 65 20 63 61 63 68 65 20 6d 75 73 74 20 the cache must
38ff0 64 69 73 63 61 72 64 20 61 6c 6c 0a 2a 2a 20 65 discard all.** e
39000 78 69 73 74 69 6e 67 20 63 61 63 68 65 20 65 6e xisting cache en
39010 74 72 69 65 73 20 77 69 74 68 20 70 61 67 65 20 tries with page
39020 6e 75 6d 62 65 72 73 20 28 6b 65 79 73 29 20 67 numbers (keys) g
39030 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65 reater than or e
39040 71 75 61 6c 0a 2a 2a 20 74 6f 20 74 68 65 20 76 qual.** to the v
39050 61 6c 75 65 20 6f 66 20 74 68 65 20 69 4c 69 6d alue of the iLim
39060 69 74 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 it parameter pas
39070 73 65 64 20 74 6f 20 78 54 72 75 6e 63 61 74 65 sed to xTruncate
39080 28 29 2e 20 49 66 20 61 6e 79 0a 2a 2a 20 6f 66 (). If any.** of
39090 20 74 68 65 73 65 20 70 61 67 65 73 20 61 72 65 these pages are
390a0 20 70 69 6e 6e 65 64 2c 20 74 68 65 79 20 61 72 pinned, they ar
390b0 65 20 69 6d 70 6c 69 63 69 74 6c 79 20 75 6e 70 e implicitly unp
390c0 69 6e 6e 65 64 2c 20 6d 65 61 6e 69 6e 67 20 74 inned, meaning t
390d0 68 61 74 0a 2a 2a 20 74 68 65 79 20 63 61 6e 20 hat.** they can
390e0 62 65 20 73 61 66 65 6c 79 20 64 69 73 63 61 72 be safely discar
390f0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ded..**.** The x
39100 44 65 73 74 72 6f 79 28 29 20 6d 65 74 68 6f 64 Destroy() method
39110 20 69 73 20 75 73 65 64 20 74 6f 20 64 65 6c 65 is used to dele
39120 74 65 20 61 20 63 61 63 68 65 20 61 6c 6c 6f 63 te a cache alloc
39130 61 74 65 64 20 62 79 20 78 43 72 65 61 74 65 28 ated by xCreate(
39140 29 2e 0a 2a 2a 20 41 6c 6c 20 72 65 73 6f 75 72 )..** All resour
39150 63 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 ces associated w
39160 69 74 68 20 74 68 65 20 73 70 65 63 69 66 69 65 ith the specifie
39170 64 20 63 61 63 68 65 20 73 68 6f 75 6c 64 20 62 d cache should b
39180 65 20 66 72 65 65 64 2e 20 41 66 74 65 72 0a 2a e freed. After.*
39190 2a 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 44 * calling the xD
391a0 65 73 74 72 6f 79 28 29 20 6d 65 74 68 6f 64 2c estroy() method,
391b0 20 53 51 4c 69 74 65 20 63 6f 6e 73 69 64 65 72 SQLite consider
391c0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 s the [sqlite3_p
391d0 63 61 63 68 65 2a 5d 0a 2a 2a 20 68 61 6e 64 6c cache*].** handl
391e0 65 20 69 6e 76 61 6c 69 64 2c 20 61 6e 64 20 77 e invalid, and w
391f0 69 6c 6c 20 6e 6f 74 20 75 73 65 20 69 74 20 77 ill not use it w
39200 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20 73 71 ith any other sq
39210 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
39220 68 6f 64 73 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e hods.** function
39230 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 s..*/.typedef st
39240 72 75 63 74 20 73 71 6c 69 74 65 33 5f 70 63 61 ruct sqlite3_pca
39250 63 68 65 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 che_methods sqli
39260 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
39270 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 ds;.struct sqlit
39280 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
39290 73 20 7b 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 s {. void *pArg
392a0 3b 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 ;. int (*xInit)
392b0 28 76 6f 69 64 2a 29 3b 0a 20 20 76 6f 69 64 20 (void*);. void
392c0 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 (*xShutdown)(voi
392d0 64 2a 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 70 d*);. sqlite3_p
392e0 63 61 63 68 65 20 2a 28 2a 78 43 72 65 61 74 65 cache *(*xCreate
392f0 29 28 69 6e 74 20 73 7a 50 61 67 65 2c 20 69 6e )(int szPage, in
39300 74 20 62 50 75 72 67 65 61 62 6c 65 29 3b 0a 20 t bPurgeable);.
39310 20 76 6f 69 64 20 28 2a 78 43 61 63 68 65 73 69 void (*xCachesi
39320 7a 65 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 ze)(sqlite3_pcac
39330 68 65 2a 2c 20 69 6e 74 20 6e 43 61 63 68 65 73 he*, int nCaches
39340 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 50 ize);. int (*xP
39350 61 67 65 63 6f 75 6e 74 29 28 73 71 6c 69 74 65 agecount)(sqlite
39360 33 5f 70 63 61 63 68 65 2a 29 3b 0a 20 20 76 6f 3_pcache*);. vo
39370 69 64 20 2a 28 2a 78 46 65 74 63 68 29 28 73 71 id *(*xFetch)(sq
39380 6c 69 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 75 lite3_pcache*, u
39390 6e 73 69 67 6e 65 64 20 6b 65 79 2c 20 69 6e 74 nsigned key, int
393a0 20 63 72 65 61 74 65 46 6c 61 67 29 3b 0a 20 20 createFlag);.
393b0 76 6f 69 64 20 28 2a 78 55 6e 70 69 6e 29 28 73 void (*xUnpin)(s
393c0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 qlite3_pcache*,
393d0 76 6f 69 64 2a 2c 20 69 6e 74 20 64 69 73 63 61 void*, int disca
393e0 72 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 52 rd);. void (*xR
393f0 65 6b 65 79 29 28 73 71 6c 69 74 65 33 5f 70 63 ekey)(sqlite3_pc
39400 61 63 68 65 2a 2c 20 76 6f 69 64 2a 2c 20 75 6e ache*, void*, un
39410 73 69 67 6e 65 64 20 6f 6c 64 4b 65 79 2c 20 75 signed oldKey, u
39420 6e 73 69 67 6e 65 64 20 6e 65 77 4b 65 79 29 3b nsigned newKey);
39430 0a 20 20 76 6f 69 64 20 28 2a 78 54 72 75 6e 63 . void (*xTrunc
39440 61 74 65 29 28 73 71 6c 69 74 65 33 5f 70 63 61 ate)(sqlite3_pca
39450 63 68 65 2a 2c 20 75 6e 73 69 67 6e 65 64 20 69 che*, unsigned i
39460 4c 69 6d 69 74 29 3b 0a 20 20 76 6f 69 64 20 28 Limit);. void (
39470 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 *xDestroy)(sqlit
39480 65 33 5f 70 63 61 63 68 65 2a 29 3b 0a 7d 3b 0a e3_pcache*);.};.
39490 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
394a0 20 4f 6e 6c 69 6e 65 20 42 61 63 6b 75 70 20 4f Online Backup O
394b0 62 6a 65 63 74 0a 2a 2a 20 45 58 50 45 52 49 4d bject.** EXPERIM
394c0 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ENTAL.**.** The
394d0 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f sqlite3_backup o
394e0 62 6a 65 63 74 20 72 65 63 6f 72 64 73 20 73 74 bject records st
394f0 61 74 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 ate information
39500 61 62 6f 75 74 20 61 6e 20 6f 6e 67 6f 69 6e 67 about an ongoing
39510 0a 2a 2a 20 6f 6e 6c 69 6e 65 20 62 61 63 6b 75 .** online backu
39520 70 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 54 68 p operation. Th
39530 65 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 e sqlite3_backup
39540 20 6f 62 6a 65 63 74 20 69 73 20 63 72 65 61 74 object is creat
39550 65 64 20 62 79 0a 2a 2a 20 61 20 63 61 6c 6c 20 ed by.** a call
39560 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b to [sqlite3_back
39570 75 70 5f 69 6e 69 74 28 29 5d 20 61 6e 64 20 69 up_init()] and i
39580 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 61 s destroyed by a
39590 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
395a0 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 ite3_backup_fini
395b0 73 68 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 sh()]..**.** See
395c0 20 41 6c 73 6f 3a 20 5b 55 73 69 6e 67 20 74 68 Also: [Using th
395d0 65 20 53 51 4c 69 74 65 20 4f 6e 6c 69 6e 65 20 e SQLite Online
395e0 42 61 63 6b 75 70 20 41 50 49 5d 0a 2a 2f 0a 74 Backup API].*/.t
395f0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
39600 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 73 71 6c lite3_backup sql
39610 69 74 65 33 5f 62 61 63 6b 75 70 3b 0a 0a 2f 2a ite3_backup;../*
39620 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e .** CAPI3REF: On
39630 6c 69 6e 65 20 42 61 63 6b 75 70 20 41 50 49 2e line Backup API.
39640 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
39650 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 .**.** This API
39660 69 73 20 75 73 65 64 20 74 6f 20 6f 76 65 72 77 is used to overw
39670 72 69 74 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 rite the content
39680 73 20 6f 66 20 6f 6e 65 20 64 61 74 61 62 61 73 s of one databas
39690 65 20 77 69 74 68 20 74 68 61 74 0a 2a 2a 20 6f e with that.** o
396a0 66 20 61 6e 6f 74 68 65 72 2e 20 49 74 20 69 73 f another. It is
396b0 20 75 73 65 66 75 6c 20 65 69 74 68 65 72 20 66 useful either f
396c0 6f 72 20 63 72 65 61 74 69 6e 67 20 62 61 63 6b or creating back
396d0 75 70 73 20 6f 66 20 64 61 74 61 62 61 73 65 73 ups of databases
396e0 20 6f 72 0a 2a 2a 20 66 6f 72 20 63 6f 70 79 69 or.** for copyi
396f0 6e 67 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 ng in-memory dat
39700 61 62 61 73 65 73 20 74 6f 20 6f 72 20 66 72 6f abases to or fro
39710 6d 20 70 65 72 73 69 73 74 65 6e 74 20 66 69 6c m persistent fil
39720 65 73 2e 20 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 es. .**.** See A
39730 6c 73 6f 3a 20 5b 55 73 69 6e 67 20 74 68 65 20 lso: [Using the
39740 53 51 4c 69 74 65 20 4f 6e 6c 69 6e 65 20 42 61 SQLite Online Ba
39750 63 6b 75 70 20 41 50 49 5d 0a 2a 2a 0a 2a 2a 20 ckup API].**.**
39760 45 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 Exclusive access
39770 20 69 73 20 72 65 71 75 69 72 65 64 20 74 6f 20 is required to
39780 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 the destination
39790 64 61 74 61 62 61 73 65 20 66 6f 72 20 74 68 65 database for the
397a0 20 0a 2a 2a 20 64 75 72 61 74 69 6f 6e 20 6f 66 .** duration of
397b0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 the operation.
397c0 48 6f 77 65 76 65 72 20 74 68 65 20 73 6f 75 72 However the sour
397d0 63 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f ce database is o
397e0 6e 6c 79 0a 2a 2a 20 72 65 61 64 2d 6c 6f 63 6b nly.** read-lock
397f0 65 64 20 77 68 69 6c 65 20 69 74 20 69 73 20 61 ed while it is a
39800 63 74 75 61 6c 6c 79 20 62 65 69 6e 67 20 72 65 ctually being re
39810 61 64 2c 20 69 74 20 69 73 20 6e 6f 74 20 6c 6f ad, it is not lo
39820 63 6b 65 64 0a 2a 2a 20 63 6f 6e 74 69 6e 75 6f cked.** continuo
39830 75 73 6c 79 20 66 6f 72 20 74 68 65 20 65 6e 74 usly for the ent
39840 69 72 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 54 ire operation. T
39850 68 75 73 2c 20 74 68 65 20 62 61 63 6b 75 70 20 hus, the backup
39860 6d 61 79 20 62 65 0a 2a 2a 20 70 65 72 66 6f 72 may be.** perfor
39870 6d 65 64 20 6f 6e 20 61 20 6c 69 76 65 20 64 61 med on a live da
39880 74 61 62 61 73 65 20 77 69 74 68 6f 75 74 20 70 tabase without p
39890 72 65 76 65 6e 74 69 6e 67 20 6f 74 68 65 72 20 reventing other
398a0 75 73 65 72 73 20 66 72 6f 6d 0a 2a 2a 20 77 72 users from.** wr
398b0 69 74 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74 iting to the dat
398c0 61 62 61 73 65 20 66 6f 72 20 61 6e 20 65 78 74 abase for an ext
398d0 65 6e 64 65 64 20 70 65 72 69 6f 64 20 6f 66 20 ended period of
398e0 74 69 6d 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 6f 20 time..** .** To
398f0 70 65 72 66 6f 72 6d 20 61 20 62 61 63 6b 75 70 perform a backup
39900 20 6f 70 65 72 61 74 69 6f 6e 3a 20 0a 2a 2a 20 operation: .**
39910 20 20 3c 6f 6c 3e 0a 2a 2a 20 20 20 20 20 3c 6c <ol>.** <l
39920 69 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 i><b>sqlite3_bac
39930 6b 75 70 5f 69 6e 69 74 28 29 3c 2f 62 3e 20 69 kup_init()</b> i
39940 73 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 74 6f s called once to
39950 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 0a initialize the.
39960 2a 2a 20 20 20 20 20 20 20 20 20 62 61 63 6b 75 ** backu
39970 70 2c 20 0a 2a 2a 20 20 20 20 20 3c 6c 69 3e 3c p, .** <li><
39980 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 b>sqlite3_backup
39990 5f 73 74 65 70 28 29 3c 2f 62 3e 20 69 73 20 63 _step()</b> is c
399a0 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 alled one or mor
399b0 65 20 74 69 6d 65 73 20 74 6f 20 74 72 61 6e 73 e times to trans
399c0 66 65 72 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 fer .**
399d0 74 68 65 20 64 61 74 61 20 62 65 74 77 65 65 6e the data between
399e0 20 74 68 65 20 74 77 6f 20 64 61 74 61 62 61 73 the two databas
399f0 65 73 2c 20 61 6e 64 20 66 69 6e 61 6c 6c 79 0a es, and finally.
39a00 2a 2a 20 20 20 20 20 3c 6c 69 3e 3c 62 3e 73 71 ** <li><b>sq
39a10 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e lite3_backup_fin
39a20 69 73 68 28 29 3c 2f 62 3e 20 69 73 20 63 61 6c ish()</b> is cal
39a30 6c 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 61 led to release a
39a40 6c 6c 20 72 65 73 6f 75 72 63 65 73 20 0a 2a 2a ll resources .**
39a50 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 associa
39a60 74 65 64 20 77 69 74 68 20 74 68 65 20 62 61 63 ted with the bac
39a70 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 2e 20 0a kup operation. .
39a80 2a 2a 20 20 20 3c 2f 6f 6c 3e 0a 2a 2a 20 54 68 ** </ol>.** Th
39a90 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 65 78 ere should be ex
39aa0 61 63 74 6c 79 20 6f 6e 65 20 63 61 6c 6c 20 74 actly one call t
39ab0 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 o sqlite3_backup
39ac0 5f 66 69 6e 69 73 68 28 29 20 66 6f 72 20 65 61 _finish() for ea
39ad0 63 68 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c ch.** successful
39ae0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
39af0 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 2e 0a _backup_init()..
39b00 2a 2a 0a 2a 2a 20 3c 62 3e 73 71 6c 69 74 65 33 **.** <b>sqlite3
39b10 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 3c 2f _backup_init()</
39b20 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 b>.**.** The fir
39b30 73 74 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 st two arguments
39b40 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 passed to [sqli
39b50 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 te3_backup_init(
39b60 29 5d 20 61 72 65 20 74 68 65 20 64 61 74 61 62 )] are the datab
39b70 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 20 61 73 ase.** handle as
39b80 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
39b90 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 e destination da
39ba0 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 64 tabase and the d
39bb0 61 74 61 62 61 73 65 20 6e 61 6d 65 20 0a 2a 2a atabase name .**
39bc0 20 75 73 65 64 20 74 6f 20 61 74 74 61 63 68 20 used to attach
39bd0 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 the destination
39be0 64 61 74 61 62 61 73 65 20 74 6f 20 74 68 65 20 database to the
39bf0 68 61 6e 64 6c 65 2e 20 54 68 65 20 64 61 74 61 handle. The data
39c00 62 61 73 65 20 6e 61 6d 65 0a 2a 2a 20 69 73 20 base name.** is
39c10 22 6d 61 69 6e 22 20 66 6f 72 20 74 68 65 20 6d "main" for the m
39c20 61 69 6e 20 64 61 74 61 62 61 73 65 2c 20 22 74 ain database, "t
39c30 65 6d 70 22 20 66 6f 72 20 74 68 65 20 74 65 6d emp" for the tem
39c40 70 6f 72 61 72 79 20 64 61 74 61 62 61 73 65 2c porary database,
39c50 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 or.** the name
39c60 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 specified as par
39c70 74 20 6f 66 20 74 68 65 20 5b 41 54 54 41 43 48 t of the [ATTACH
39c80 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 74 ] statement if t
39c90 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 69 he destination i
39ca0 73 0a 2a 2a 20 61 6e 20 61 74 74 61 63 68 65 64 s.** an attached
39cb0 20 64 61 74 61 62 61 73 65 2e 20 54 68 65 20 74 database. The t
39cc0 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 hird and fourth
39cd0 61 72 67 75 6d 65 6e 74 73 20 70 61 73 73 65 64 arguments passed
39ce0 20 74 6f 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f to .** sqlite3_
39cf0 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 20 69 64 backup_init() id
39d00 65 6e 74 69 66 79 20 74 68 65 20 5b 64 61 74 61 entify the [data
39d10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
39d20 0a 2a 2a 20 61 6e 64 20 64 61 74 61 62 61 73 65 .** and database
39d30 20 6e 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f name used.** to
39d40 20 61 63 63 65 73 73 20 74 68 65 20 73 6f 75 72 access the sour
39d50 63 65 20 64 61 74 61 62 61 73 65 2e 20 54 68 65 ce database. The
39d60 20 76 61 6c 75 65 73 20 70 61 73 73 65 64 20 66 values passed f
39d70 6f 72 20 74 68 65 20 73 6f 75 72 63 65 20 61 6e or the source an
39d80 64 20 0a 2a 2a 20 64 65 73 74 69 6e 61 74 69 6f d .** destinatio
39d90 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
39da0 65 63 74 69 6f 6e 5d 20 70 61 72 61 6d 65 74 65 ection] paramete
39db0 72 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 74 rs must not be t
39dc0 68 65 20 73 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 he same..**.** I
39dd0 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 f an error occur
39de0 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 s within sqlite3
39df0 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 2c 20 _backup_init(),
39e00 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 then NULL is ret
39e10 75 72 6e 65 64 0a 2a 2a 20 61 6e 64 20 61 6e 20 urned.** and an
39e20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 65 error code and e
39e30 72 72 6f 72 20 6d 65 73 73 61 67 65 20 77 72 69 rror message wri
39e40 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 5b 64 tten into the [d
39e50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
39e60 6f 6e 5d 20 0a 2a 2a 20 70 61 73 73 65 64 20 61 on] .** passed a
39e70 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
39e80 6d 65 6e 74 2e 20 54 68 65 79 20 6d 61 79 20 62 ment. They may b
39e90 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e e retrieved usin
39ea0 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 g the.** [sqlite
39eb0 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 3_errcode()], [s
39ec0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
39ed0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 , and [sqlite3_e
39ee0 72 72 6d 73 67 31 36 28 29 5d 20 66 75 6e 63 74 rrmsg16()] funct
39ef0 69 6f 6e 73 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 ions..** Otherwi
39f00 73 65 2c 20 69 66 20 73 75 63 63 65 73 73 66 75 se, if successfu
39f10 6c 2c 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 l, a pointer to
39f20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b an [sqlite3_back
39f30 75 70 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a up] object is.**
39f40 20 72 65 74 75 72 6e 65 64 2e 20 54 68 69 73 20 returned. This
39f50 70 6f 69 6e 74 65 72 20 6d 61 79 20 62 65 20 75 pointer may be u
39f60 73 65 64 20 77 69 74 68 20 74 68 65 20 73 71 6c sed with the sql
39f70 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
39f80 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 () and.** sqlite
39f90 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 3_backup_finish(
39fa0 29 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 70 ) functions to p
39fb0 65 72 66 6f 72 6d 20 74 68 65 20 73 70 65 63 69 erform the speci
39fc0 66 69 65 64 20 62 61 63 6b 75 70 20 0a 2a 2a 20 fied backup .**
39fd0 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a operation..**.**
39fe0 20 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b <b>sqlite3_back
39ff0 75 70 5f 73 74 65 70 28 29 3c 2f 62 3e 0a 2a 2a up_step()</b>.**
3a000 0a 2a 2a 20 46 75 6e 63 74 69 6f 6e 20 5b 73 71 .** Function [sq
3a010 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3a020 70 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 p()] is used to
3a030 63 6f 70 79 20 75 70 20 74 6f 20 6e 50 61 67 65 copy up to nPage
3a040 20 70 61 67 65 73 20 62 65 74 77 65 65 6e 20 0a pages between .
3a050 2a 2a 20 74 68 65 20 73 6f 75 72 63 65 20 61 6e ** the source an
3a060 64 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 d destination da
3a070 74 61 62 61 73 65 73 2c 20 77 68 65 72 65 20 6e tabases, where n
3a080 50 61 67 65 20 69 73 20 74 68 65 20 76 61 6c 75 Page is the valu
3a090 65 20 6f 66 20 74 68 65 20 0a 2a 2a 20 73 65 63 e of the .** sec
3a0a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 ond parameter pa
3a0b0 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f ssed to sqlite3_
3a0c0 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 20 49 backup_step(). I
3a0d0 66 20 6e 50 61 67 65 20 69 73 20 61 20 6e 65 67 f nPage is a neg
3a0e0 61 74 69 76 65 0a 2a 2a 20 76 61 6c 75 65 2c 20 ative.** value,
3a0f0 61 6c 6c 20 72 65 6d 61 69 6e 69 6e 67 20 73 6f all remaining so
3a100 75 72 63 65 20 70 61 67 65 73 20 61 72 65 20 63 urce pages are c
3a110 6f 70 69 65 64 2e 20 49 66 20 74 68 65 20 72 65 opied. If the re
3a120 71 75 69 72 65 64 20 70 61 67 65 73 20 61 72 65 quired pages are
3a130 20 0a 2a 2a 20 73 75 63 63 65 73 66 75 6c 6c 79 .** succesfully
3a140 20 63 6f 70 69 65 64 2c 20 62 75 74 20 74 68 65 copied, but the
3a150 72 65 20 61 72 65 20 73 74 69 6c 6c 20 6d 6f 72 re are still mor
3a160 65 20 70 61 67 65 73 20 74 6f 20 63 6f 70 79 20 e pages to copy
3a170 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 62 before the .** b
3a180 61 63 6b 75 70 20 69 73 20 63 6f 6d 70 6c 65 74 ackup is complet
3a190 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 e, it returns [S
3a1a0 51 4c 49 54 45 5f 4f 4b 5d 2e 20 49 66 20 6e 6f QLITE_OK]. If no
3a1b0 20 65 72 72 6f 72 20 6f 63 63 75 72 65 64 20 61 error occured a
3a1c0 6e 64 20 74 68 65 72 65 20 0a 2a 2a 20 61 72 65 nd there .** are
3a1d0 20 6e 6f 20 6d 6f 72 65 20 70 61 67 65 73 20 74 no more pages t
3a1e0 6f 20 63 6f 70 79 2c 20 74 68 65 6e 20 5b 53 51 o copy, then [SQ
3a1f0 4c 49 54 45 5f 44 4f 4e 45 5d 20 69 73 20 72 65 LITE_DONE] is re
3a200 74 75 72 6e 65 64 2e 20 49 66 20 61 6e 20 65 72 turned. If an er
3a210 72 6f 72 20 0a 2a 2a 20 6f 63 63 75 72 73 2c 20 ror .** occurs,
3a220 74 68 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 65 then an SQLite e
3a230 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 rror code is ret
3a240 75 72 6e 65 64 2e 20 41 73 20 77 65 6c 6c 20 61 urned. As well a
3a250 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e s [SQLITE_OK] an
3a260 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e d.** [SQLITE_DON
3a270 45 5d 2c 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 E], a call to sq
3a280 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3a290 70 28 29 20 6d 61 79 20 72 65 74 75 72 6e 20 5b p() may return [
3a2a0 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d SQLITE_READONLY]
3a2b0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d ,.** [SQLITE_NOM
3a2c0 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 EM], [SQLITE_BUS
3a2d0 59 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b Y], [SQLITE_LOCK
3a2e0 45 44 5d 2c 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 ED], or an.** [S
3a2f0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 QLITE_IOERR_ACCE
3a300 53 53 20 7c 20 53 51 4c 49 54 45 5f 49 4f 45 52 SS | SQLITE_IOER
3a310 52 5f 58 58 58 5d 20 65 78 74 65 6e 64 65 64 20 R_XXX] extended
3a320 65 72 72 6f 72 20 63 6f 64 65 2e 0a 2a 2a 0a 2a error code..**.*
3a330 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 74 68 65 * As well as the
3a340 20 63 61 73 65 20 77 68 65 72 65 20 74 68 65 20 case where the
3a350 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 destination data
3a360 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 6f 70 base file was op
3a370 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 72 65 61 64 ened for.** read
3a380 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2c 20 73 71 -only access, sq
3a390 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3a3a0 70 28 29 20 6d 61 79 20 72 65 74 75 72 6e 20 5b p() may return [
3a3b0 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d SQLITE_READONLY]
3a3c0 20 69 66 0a 2a 2a 20 74 68 65 20 64 65 73 74 69 if.** the desti
3a3d0 6e 61 74 69 6f 6e 20 69 73 20 61 6e 20 69 6e 2d nation is an in-
3a3e0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 memory database
3a3f0 77 69 74 68 20 61 20 64 69 66 66 65 72 65 6e 74 with a different
3a400 20 70 61 67 65 20 73 69 7a 65 0a 2a 2a 20 66 72 page size.** fr
3a410 6f 6d 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 om the source da
3a420 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 tabase..**.** If
3a430 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3a440 73 74 65 70 28 29 20 63 61 6e 6e 6f 74 20 6f 62 step() cannot ob
3a450 74 61 69 6e 20 61 20 72 65 71 75 69 72 65 64 20 tain a required
3a460 66 69 6c 65 2d 73 79 73 74 65 6d 20 6c 6f 63 6b file-system lock
3a470 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 73 , then.** the [s
3a480 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
3a490 6c 65 72 20 7c 20 62 75 73 79 2d 68 61 6e 64 6c ler | busy-handl
3a4a0 65 72 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 er function].**
3a4b0 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 66 20 6f is invoked (if o
3a4c0 6e 65 20 69 73 20 73 70 65 63 69 66 69 65 64 29 ne is specified)
3a4d0 2e 20 49 66 20 74 68 65 20 0a 2a 2a 20 62 75 73 . If the .** bus
3a4e0 79 2d 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e y-handler return
3a4f0 73 20 6e 6f 6e 2d 7a 65 72 6f 20 62 65 66 6f 72 s non-zero befor
3a500 65 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 61 76 e the lock is av
3a510 61 69 6c 61 62 6c 65 2c 20 74 68 65 6e 20 0a 2a ailable, then .*
3a520 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 * [SQLITE_BUSY]
3a530 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 is returned to t
3a540 68 65 20 63 61 6c 6c 65 72 2e 20 49 6e 20 74 68 he caller. In th
3a550 69 73 20 63 61 73 65 20 74 68 65 20 63 61 6c 6c is case the call
3a560 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 to.** sqlite3_b
3a570 61 63 6b 75 70 5f 73 74 65 70 28 29 20 63 61 6e ackup_step() can
3a580 20 62 65 20 72 65 74 72 69 65 64 20 6c 61 74 65 be retried late
3a590 72 2e 20 49 66 20 74 68 65 20 73 6f 75 72 63 65 r. If the source
3a5a0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
3a5b0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 nnection].** is
3a5c0 62 65 69 6e 67 20 75 73 65 64 20 74 6f 20 77 72 being used to wr
3a5d0 69 74 65 20 74 6f 20 74 68 65 20 73 6f 75 72 63 ite to the sourc
3a5e0 65 20 64 61 74 61 62 61 73 65 20 77 68 65 6e 20 e database when
3a5f0 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 sqlite3_backup_s
3a600 74 65 70 28 29 0a 2a 2a 20 69 73 20 63 61 6c 6c tep().** is call
3a610 65 64 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 ed, then [SQLITE
3a620 5f 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 _LOCKED] is retu
3a630 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 rned immediately
3a640 2e 20 41 67 61 69 6e 2c 20 69 6e 20 74 68 69 73 . Again, in this
3a650 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 63 61 6c .** case the cal
3a660 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 l to sqlite3_bac
3a670 6b 75 70 5f 73 74 65 70 28 29 20 63 61 6e 20 62 kup_step() can b
3a680 65 20 72 65 74 72 69 65 64 20 6c 61 74 65 72 20 e retried later
3a690 6f 6e 2e 20 49 66 0a 2a 2a 20 5b 53 51 4c 49 54 on. If.** [SQLIT
3a6a0 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 7c E_IOERR_ACCESS |
3a6b0 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 58 58 SQLITE_IOERR_XX
3a6c0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 X], [SQLITE_NOME
3a6d0 4d 5d 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 M], or.** [SQLIT
3a6e0 45 5f 52 45 41 44 4f 4e 4c 59 5d 20 69 73 20 72 E_READONLY] is r
3a6f0 65 74 75 72 6e 65 64 2c 20 74 68 65 6e 20 0a 2a eturned, then .*
3a700 2a 20 74 68 65 72 65 20 69 73 20 6e 6f 20 70 6f * there is no po
3a710 69 6e 74 20 69 6e 20 72 65 74 72 79 69 6e 67 20 int in retrying
3a720 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 the call to sqli
3a730 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
3a740 29 2e 20 54 68 65 73 65 20 0a 2a 2a 20 65 72 72 ). These .** err
3a750 6f 72 73 20 61 72 65 20 63 6f 6e 73 69 64 65 72 ors are consider
3a760 65 64 20 66 61 74 61 6c 2e 20 41 74 20 74 68 69 ed fatal. At thi
3a770 73 20 70 6f 69 6e 74 20 74 68 65 20 61 70 70 6c s point the appl
3a780 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 61 63 63 ication must acc
3a790 65 70 74 20 0a 2a 2a 20 74 68 61 74 20 74 68 65 ept .** that the
3a7a0 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f backup operatio
3a7b0 6e 20 68 61 73 20 66 61 69 6c 65 64 20 61 6e 64 n has failed and
3a7c0 20 70 61 73 73 20 74 68 65 20 62 61 63 6b 75 70 pass the backup
3a7d0 20 6f 70 65 72 61 74 69 6f 6e 20 68 61 6e 64 6c operation handl
3a7e0 65 20 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c e .** to the sql
3a7f0 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 ite3_backup_fini
3a800 73 68 28 29 20 74 6f 20 72 65 6c 65 61 73 65 20 sh() to release
3a810 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75 associated resou
3a820 72 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 46 6f 6c 6c rces..**.** Foll
3a830 6f 77 69 6e 67 20 74 68 65 20 66 69 72 73 74 20 owing the first
3a840 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
3a850 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2c 20 61 backup_step(), a
3a860 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b n exclusive lock
3a870 20 69 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 is.** obtained
3a880 6f 6e 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 on the destinati
3a890 6f 6e 20 66 69 6c 65 2e 20 49 74 20 69 73 20 6e on file. It is n
3a8a0 6f 74 20 72 65 6c 65 61 73 65 64 20 75 6e 74 69 ot released unti
3a8b0 6c 20 65 69 74 68 65 72 20 0a 2a 2a 20 73 71 6c l either .** sql
3a8c0 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 ite3_backup_fini
3a8d0 73 68 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f sh() is called o
3a8e0 72 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 r the backup ope
3a8f0 72 61 74 69 6f 6e 20 69 73 20 63 6f 6d 70 6c 65 ration is comple
3a900 74 65 20 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 te .** and sqlit
3a910 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3a920 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
3a930 5f 44 4f 4e 45 5d 2e 20 41 64 64 69 74 69 6f 6e _DONE]. Addition
3a940 61 6c 6c 79 2c 20 65 61 63 68 20 74 69 6d 65 20 ally, each time
3a950 0a 2a 2a 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 .** a call to sq
3a960 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3a970 70 28 29 20 69 73 20 6d 61 64 65 20 61 20 5b 73 p() is made a [s
3a980 68 61 72 65 64 20 6c 6f 63 6b 5d 20 69 73 20 6f hared lock] is o
3a990 62 74 61 69 6e 65 64 20 6f 6e 0a 2a 2a 20 74 68 btained on.** th
3a9a0 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 73 e source databas
3a9b0 65 20 66 69 6c 65 2e 20 54 68 69 73 20 6c 6f 63 e file. This loc
3a9c0 6b 20 69 73 20 72 65 6c 65 61 73 65 64 20 62 65 k is released be
3a9d0 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 fore the.** sqli
3a9e0 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
3a9f0 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 20 ) call returns.
3aa00 42 65 63 61 75 73 65 20 74 68 65 20 73 6f 75 72 Because the sour
3aa10 63 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6e ce database is n
3aa20 6f 74 0a 2a 2a 20 6c 6f 63 6b 65 64 20 62 65 74 ot.** locked bet
3aa30 77 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 ween calls to sq
3aa40 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3aa50 70 28 29 2c 20 69 74 20 6d 61 79 20 62 65 20 6d p(), it may be m
3aa60 6f 64 69 66 69 65 64 20 6d 69 64 2d 77 61 79 0a odified mid-way.
3aa70 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 62 ** through the b
3aa80 61 63 6b 75 70 20 70 72 6f 63 65 64 75 72 65 2e ackup procedure.
3aa90 20 49 66 20 74 68 65 20 73 6f 75 72 63 65 20 64 If the source d
3aaa0 61 74 61 62 61 73 65 20 69 73 20 6d 6f 64 69 66 atabase is modif
3aab0 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20 65 78 74 ied by an.** ext
3aac0 65 72 6e 61 6c 20 70 72 6f 63 65 73 73 20 6f 72 ernal process or
3aad0 20 76 69 61 20 61 20 64 61 74 61 62 61 73 65 20 via a database
3aae0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 74 68 65 72 connection other
3aaf0 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 62 65 than the one be
3ab00 69 6e 67 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 ing.** used by t
3ab10 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 he backup operat
3ab20 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 62 61 ion, then the ba
3ab30 63 6b 75 70 20 77 69 6c 6c 20 62 65 20 74 72 61 ckup will be tra
3ab40 6e 73 70 61 72 65 6e 74 6c 79 0a 2a 2a 20 72 65 nsparently.** re
3ab50 73 74 61 72 74 65 64 20 62 79 20 74 68 65 20 6e started by the n
3ab60 65 78 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ext call to sqli
3ab70 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
3ab80 29 2e 20 49 66 20 74 68 65 20 73 6f 75 72 63 65 ). If the source
3ab90 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 .** database is
3aba0 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 modified by the
3abb0 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 using the same
3abc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3abd0 69 6f 6e 20 61 73 20 69 73 20 75 73 65 64 0a 2a ion as is used.*
3abe0 2a 20 62 79 20 74 68 65 20 62 61 63 6b 75 70 20 * by the backup
3abf0 6f 70 65 72 61 74 69 6f 6e 2c 20 74 68 65 6e 20 operation, then
3ac00 74 68 65 20 62 61 63 6b 75 70 20 64 61 74 61 62 the backup datab
3ac10 61 73 65 20 69 73 20 74 72 61 6e 73 70 61 72 65 ase is transpare
3ac20 6e 74 6c 79 20 0a 2a 2a 20 75 70 64 61 74 65 64 ntly .** updated
3ac30 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
3ac40 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 73 71 6c 69 e..**.** <b>sqli
3ac50 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 te3_backup_finis
3ac60 68 28 29 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 4f 6e h()</b>.**.** On
3ac70 63 65 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ce sqlite3_backu
3ac80 70 5f 73 74 65 70 28 29 20 68 61 73 20 72 65 74 p_step() has ret
3ac90 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f urned [SQLITE_DO
3aca0 4e 45 5d 2c 20 6f 72 20 77 68 65 6e 20 74 68 65 NE], or when the
3acb0 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e .** application
3acc0 20 77 69 73 68 65 73 20 74 6f 20 61 62 61 6e 64 wishes to aband
3acd0 6f 6e 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 on the backup op
3ace0 65 72 61 74 69 6f 6e 2c 20 74 68 65 20 5b 73 71 eration, the [sq
3acf0 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 0a 2a 2a lite3_backup].**
3ad00 20 6f 62 6a 65 63 74 20 73 68 6f 75 6c 64 20 62 object should b
3ad10 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 e passed to sqli
3ad20 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 te3_backup_finis
3ad30 68 28 29 2e 20 54 68 69 73 20 72 65 6c 65 61 73 h(). This releas
3ad40 65 73 20 61 6c 6c 0a 2a 2a 20 72 65 73 6f 75 72 es all.** resour
3ad50 63 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 ces associated w
3ad60 69 74 68 20 74 68 65 20 62 61 63 6b 75 70 20 6f ith the backup o
3ad70 70 65 72 61 74 69 6f 6e 2e 20 49 66 20 73 71 6c peration. If sql
3ad80 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3ad90 28 29 0a 2a 2a 20 68 61 73 20 6e 6f 74 20 79 65 ().** has not ye
3ada0 74 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 t returned [SQLI
3adb0 54 45 5f 44 4f 4e 45 5d 2c 20 74 68 65 6e 20 61 TE_DONE], then a
3adc0 6e 79 20 61 63 74 69 76 65 20 77 72 69 74 65 2d ny active write-
3add0 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 6e 20 74 transaction on t
3ade0 68 65 0a 2a 2a 20 64 65 73 74 69 6e 61 74 69 6f he.** destinatio
3adf0 6e 20 64 61 74 61 62 61 73 65 20 69 73 20 72 6f n database is ro
3ae00 6c 6c 65 64 20 62 61 63 6b 2e 20 54 68 65 20 5b lled back. The [
3ae10 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 sqlite3_backup]
3ae20 6f 62 6a 65 63 74 20 69 73 20 69 6e 76 61 6c 69 object is invali
3ae30 64 0a 2a 2a 20 61 6e 64 20 6d 61 79 20 6e 6f 74 d.** and may not
3ae40 20 62 65 20 75 73 65 64 20 66 6f 6c 6c 6f 77 69 be used followi
3ae50 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c ng a call to sql
3ae60 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 ite3_backup_fini
3ae70 73 68 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 sh()..**.** The
3ae80 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
3ae90 79 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 y sqlite3_backup
3aea0 5f 66 69 6e 69 73 68 20 69 73 20 5b 53 51 4c 49 _finish is [SQLI
3aeb0 54 45 5f 4f 4b 5d 20 69 66 20 6e 6f 20 65 72 72 TE_OK] if no err
3aec0 6f 72 0a 2a 2a 20 6f 63 63 75 72 72 65 64 2c 20 or.** occurred,
3aed0 72 65 67 61 72 64 6c 65 73 73 20 6f 72 20 77 68 regardless or wh
3aee0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 71 6c ether or not sql
3aef0 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3af00 28 29 20 77 61 73 20 63 61 6c 6c 65 64 0a 2a 2a () was called.**
3af10 20 61 20 73 75 66 66 69 63 69 65 6e 74 20 6e 75 a sufficient nu
3af20 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 6f mber of times to
3af30 20 63 6f 6d 70 6c 65 74 65 20 74 68 65 20 62 61 complete the ba
3af40 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 2e 20 ckup operation.
3af50 4f 72 2c 20 69 66 0a 2a 2a 20 61 6e 20 6f 75 74 Or, if.** an out
3af60 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 -of-memory condi
3af70 74 69 6f 6e 20 6f 72 20 49 4f 20 65 72 72 6f 72 tion or IO error
3af80 20 6f 63 63 75 72 65 64 20 64 75 72 69 6e 67 20 occured during
3af90 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c a call to.** sql
3afa0 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3afb0 28 29 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f () then [SQLITE_
3afc0 4e 4f 4d 45 4d 5d 20 6f 72 20 61 6e 0a 2a 2a 20 NOMEM] or an.**
3afd0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 [SQLITE_IOERR_AC
3afe0 43 45 53 53 20 7c 20 53 51 4c 49 54 45 5f 49 4f CESS | SQLITE_IO
3aff0 45 52 52 5f 58 58 58 5d 20 65 72 72 6f 72 20 63 ERR_XXX] error c
3b000 6f 64 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e ode.** is return
3b010 65 64 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 ed. In this case
3b020 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 the error code
3b030 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 and an error mes
3b040 73 61 67 65 20 61 72 65 0a 2a 2a 20 77 72 69 74 sage are.** writ
3b050 74 65 6e 20 74 6f 20 74 68 65 20 64 65 73 74 69 ten to the desti
3b060 6e 61 74 69 6f 6e 20 5b 64 61 74 61 62 61 73 65 nation [database
3b070 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
3b080 0a 2a 2a 20 41 20 72 65 74 75 72 6e 20 6f 66 20 .** A return of
3b090 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 [SQLITE_BUSY] or
3b0a0 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5d [SQLITE_LOCKED]
3b0b0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 62 61 from sqlite3_ba
3b0c0 63 6b 75 70 5f 73 74 65 70 28 29 20 69 73 0a 2a ckup_step() is.*
3b0d0 2a 20 6e 6f 74 20 61 20 70 65 72 6d 61 6e 65 6e * not a permanen
3b0e0 74 20 65 72 72 6f 72 20 61 6e 64 20 64 6f 65 73 t error and does
3b0f0 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 not affect the
3b100 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 0a return value of.
3b110 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ** sqlite3_backu
3b120 70 5f 66 69 6e 69 73 68 28 29 2e 0a 2a 2a 0a 2a p_finish()..**.*
3b130 2a 20 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 * <b>sqlite3_bac
3b140 6b 75 70 5f 72 65 6d 61 69 6e 69 6e 67 28 29 2c kup_remaining(),
3b150 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3b160 70 61 67 65 63 6f 75 6e 74 28 29 3c 2f 62 3e 0a pagecount()</b>.
3b170 2a 2a 0a 2a 2a 20 45 61 63 68 20 63 61 6c 6c 20 **.** Each call
3b180 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 to sqlite3_backu
3b190 70 5f 73 74 65 70 28 29 20 73 65 74 73 20 74 77 p_step() sets tw
3b1a0 6f 20 76 61 6c 75 65 73 20 73 74 6f 72 65 64 20 o values stored
3b1b0 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 62 79 internally.** by
3b1c0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 an [sqlite3_bac
3b1d0 6b 75 70 5d 20 6f 62 6a 65 63 74 2e 20 54 68 65 kup] object. The
3b1e0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 number of pages
3b1f0 20 73 74 69 6c 6c 20 74 6f 20 62 65 20 62 61 63 still to be bac
3b200 6b 65 64 0a 2a 2a 20 75 70 2c 20 77 68 69 63 68 ked.** up, which
3b210 20 6d 61 79 20 62 65 20 71 75 65 72 69 65 64 20 may be queried
3b220 62 79 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 by sqlite3_backu
3b230 70 5f 72 65 6d 61 69 6e 69 6e 67 28 29 2c 20 61 p_remaining(), a
3b240 6e 64 20 74 68 65 20 74 6f 74 61 6c 0a 2a 2a 20 nd the total.**
3b250 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 number of pages
3b260 69 6e 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 in the source da
3b270 74 61 62 61 73 65 20 66 69 6c 65 2c 20 77 68 69 tabase file, whi
3b280 63 68 20 6d 61 79 20 62 65 20 71 75 65 72 69 65 ch may be querie
3b290 64 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f d by.** sqlite3_
3b2a0 62 61 63 6b 75 70 5f 70 61 67 65 63 6f 75 6e 74 backup_pagecount
3b2b0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 ()..**.** The va
3b2c0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 lues returned by
3b2d0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
3b2e0 20 61 72 65 20 6f 6e 6c 79 20 75 70 64 61 74 65 are only update
3b2f0 64 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f d by.** sqlite3_
3b300 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 20 49 backup_step(). I
3b310 66 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 f the source dat
3b320 61 62 61 73 65 20 69 73 20 6d 6f 64 69 66 69 65 abase is modifie
3b330 64 20 64 75 72 69 6e 67 20 61 20 62 61 63 6b 75 d during a backu
3b340 70 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 2c 20 p.** operation,
3b350 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 73 20 then the values
3b360 61 72 65 20 6e 6f 74 20 75 70 64 61 74 65 64 20 are not updated
3b370 74 6f 20 61 63 63 6f 75 6e 74 20 66 6f 72 20 61 to account for a
3b380 6e 79 20 65 78 74 72 61 0a 2a 2a 20 70 61 67 65 ny extra.** page
3b390 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 62 s that need to b
3b3a0 65 20 75 70 64 61 74 65 64 20 6f 72 20 74 68 65 e updated or the
3b3b0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 6f 75 size of the sou
3b3c0 72 63 65 20 64 61 74 61 62 61 73 65 20 66 69 6c rce database fil
3b3d0 65 0a 2a 2a 20 63 68 61 6e 67 69 6e 67 2e 0a 2a e.** changing..*
3b3e0 2a 0a 2a 2a 20 3c 62 3e 43 6f 6e 63 75 72 72 65 *.** <b>Concurre
3b3f0 6e 74 20 55 73 61 67 65 20 6f 66 20 44 61 74 61 nt Usage of Data
3b400 62 61 73 65 20 48 61 6e 64 6c 65 73 3c 2f 62 3e base Handles</b>
3b410 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 6f 75 72 63 .**.** The sourc
3b420 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
3b430 65 63 74 69 6f 6e 5d 20 6d 61 79 20 62 65 20 75 ection] may be u
3b440 73 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 sed by the appli
3b450 63 61 74 69 6f 6e 20 66 6f 72 20 6f 74 68 65 72 cation for other
3b460 0a 2a 2a 20 70 75 72 70 6f 73 65 73 20 77 68 69 .** purposes whi
3b470 6c 65 20 61 20 62 61 63 6b 75 70 20 6f 70 65 72 le a backup oper
3b480 61 74 69 6f 6e 20 69 73 20 75 6e 64 65 72 77 61 ation is underwa
3b490 79 20 6f 72 20 62 65 69 6e 67 20 69 6e 69 74 69 y or being initi
3b4a0 61 6c 69 7a 65 64 2e 0a 2a 2a 20 49 66 20 53 51 alized..** If SQ
3b4b0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
3b4c0 20 61 6e 64 20 63 6f 6e 66 69 67 75 72 65 64 20 and configured
3b4d0 74 6f 20 73 75 70 70 6f 72 74 20 74 68 72 65 61 to support threa
3b4e0 64 73 61 66 65 20 64 61 74 61 62 61 73 65 0a 2a dsafe database.*
3b4f0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2c 20 74 * connections, t
3b500 68 65 6e 20 74 68 65 20 73 6f 75 72 63 65 20 64 hen the source d
3b510 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3b520 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 63 on may be used c
3b530 6f 6e 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 66 oncurrently.** f
3b540 72 6f 6d 20 77 69 74 68 69 6e 20 6f 74 68 65 72 rom within other
3b550 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 threads..**.**
3b560 48 6f 77 65 76 65 72 2c 20 74 68 65 20 61 70 70 However, the app
3b570 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 67 75 lication must gu
3b580 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 arantee that the
3b590 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 destination dat
3b5a0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
3b5b0 69 6f 6e 20 68 61 6e 64 6c 65 20 69 73 20 6e 6f ion handle is no
3b5c0 74 20 70 61 73 73 65 64 20 74 6f 20 61 6e 79 20 t passed to any
3b5d0 6f 74 68 65 72 20 41 50 49 20 28 62 79 20 61 6e other API (by an
3b5e0 79 20 74 68 72 65 61 64 29 20 61 66 74 65 72 20 y thread) after
3b5f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b .** sqlite3_back
3b600 75 70 5f 69 6e 69 74 28 29 20 69 73 20 63 61 6c up_init() is cal
3b610 6c 65 64 20 61 6e 64 20 62 65 66 6f 72 65 20 74 led and before t
3b620 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
3b630 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 call to.** sqli
3b640 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 te3_backup_finis
3b650 68 28 29 2e 20 55 6e 66 6f 72 74 75 6e 61 74 65 h(). Unfortunate
3b660 6c 79 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e ly SQLite does n
3b670 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 63 68 65 ot currently che
3b680 63 6b 0a 2a 2a 20 66 6f 72 20 74 68 69 73 2c 20 ck.** for this,
3b690 69 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 if the applicati
3b6a0 6f 6e 20 64 6f 65 73 20 75 73 65 20 74 68 65 20 on does use the
3b6b0 64 65 73 74 69 6e 61 74 69 6f 6e 20 5b 64 61 74 destination [dat
3b6c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3b6d0 5d 0a 2a 2a 20 66 6f 72 20 73 6f 6d 65 20 6f 74 ].** for some ot
3b6e0 68 65 72 20 70 75 72 70 6f 73 65 20 64 75 72 69 her purpose duri
3b6f0 6e 67 20 61 20 62 61 63 6b 75 70 20 6f 70 65 72 ng a backup oper
3b700 61 74 69 6f 6e 2c 20 74 68 69 6e 67 73 20 6d 61 ation, things ma
3b710 79 20 61 70 70 65 61 72 20 74 6f 0a 2a 2a 20 77 y appear to.** w
3b720 6f 72 6b 20 63 6f 72 72 65 63 74 6c 79 20 62 75 ork correctly bu
3b730 74 20 69 6e 20 66 61 63 74 20 62 65 20 73 75 62 t in fact be sub
3b740 74 6c 79 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 69 tly malfunctioni
3b750 6e 67 2e 20 20 55 73 65 20 6f 66 20 74 68 65 0a ng. Use of the.
3b760 2a 2a 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 ** destination d
3b770 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3b780 6f 6e 20 77 68 69 6c 65 20 61 20 62 61 63 6b 75 on while a backu
3b790 70 20 69 73 20 69 6e 20 70 72 6f 67 72 65 73 73 p is in progress
3b7a0 20 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 63 might.** also c
3b7b0 61 75 73 65 20 61 20 6d 75 74 65 78 20 64 65 61 ause a mutex dea
3b7c0 64 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 75 72 dlock..**.** Fur
3b7d0 74 68 65 72 6d 6f 72 65 2c 20 69 66 20 72 75 6e thermore, if run
3b7e0 6e 69 6e 67 20 69 6e 20 5b 73 68 61 72 65 64 20 ning in [shared
3b7f0 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 74 68 65 cache mode], the
3b800 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
3b810 74 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 20 74 t.** guarantee t
3b820 68 61 74 20 74 68 65 20 73 68 61 72 65 64 20 63 hat the shared c
3b830 61 63 68 65 20 75 73 65 64 20 62 79 20 74 68 65 ache used by the
3b840 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 destination dat
3b850 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 abase.** is not
3b860 61 63 63 65 73 73 65 64 20 77 68 69 6c 65 20 74 accessed while t
3b870 68 65 20 62 61 63 6b 75 70 20 69 73 20 72 75 6e he backup is run
3b880 6e 69 6e 67 2e 20 49 6e 20 70 72 61 63 74 69 63 ning. In practic
3b890 65 20 74 68 69 73 20 6d 65 61 6e 73 0a 2a 2a 20 e this means.**
3b8a0 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 that the applica
3b8b0 74 69 6f 6e 20 6d 75 73 74 20 67 75 61 72 61 6e tion must guaran
3b8c0 74 65 65 20 74 68 61 74 20 74 68 65 20 66 69 6c tee that the fil
3b8d0 65 2d 73 79 73 74 65 6d 20 66 69 6c 65 20 62 65 e-system file be
3b8e0 69 6e 67 20 0a 2a 2a 20 62 61 63 6b 65 64 20 75 ing .** backed u
3b8f0 70 20 74 6f 20 69 73 20 6e 6f 74 20 61 63 63 65 p to is not acce
3b900 73 73 65 64 20 62 79 20 61 6e 79 20 63 6f 6e 6e ssed by any conn
3b910 65 63 74 69 6f 6e 20 77 69 74 68 69 6e 20 74 68 ection within th
3b920 65 20 70 72 6f 63 65 73 73 2c 0a 2a 2a 20 6e 6f e process,.** no
3b930 74 20 6a 75 73 74 20 74 68 65 20 73 70 65 63 69 t just the speci
3b940 66 69 63 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 fic connection t
3b950 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20 74 hat was passed t
3b960 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 o sqlite3_backup
3b970 5f 69 6e 69 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 _init()..**.** T
3b980 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b he [sqlite3_back
3b990 75 70 5d 20 6f 62 6a 65 63 74 20 69 74 73 65 6c up] object itsel
3b9a0 66 20 69 73 20 70 61 72 74 69 61 6c 6c 79 20 74 f is partially t
3b9b0 68 72 65 61 64 73 61 66 65 2e 20 4d 75 6c 74 69 hreadsafe. Multi
3b9c0 70 6c 65 20 0a 2a 2a 20 74 68 72 65 61 64 73 20 ple .** threads
3b9d0 6d 61 79 20 73 61 66 65 6c 79 20 6d 61 6b 65 20 may safely make
3b9e0 6d 75 6c 74 69 70 6c 65 20 63 6f 6e 63 75 72 72 multiple concurr
3b9f0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c ent calls to sql
3ba00 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3ba10 28 29 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 ()..** However,
3ba20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 61 63 6b the sqlite3_back
3ba30 75 70 5f 72 65 6d 61 69 6e 69 6e 67 28 29 20 61 up_remaining() a
3ba40 6e 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 nd sqlite3_backu
3ba50 70 5f 70 61 67 65 63 6f 75 6e 74 28 29 0a 2a 2a p_pagecount().**
3ba60 20 41 50 49 73 20 61 72 65 20 6e 6f 74 20 73 74 APIs are not st
3ba70 72 69 63 74 6c 79 20 73 70 65 61 6b 69 6e 67 20 rictly speaking
3ba80 74 68 72 65 61 64 73 61 66 65 2e 20 49 66 20 74 threadsafe. If t
3ba90 68 65 79 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 hey are invoked
3baa0 61 74 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 74 at the.** same t
3bab0 69 6d 65 20 61 73 20 61 6e 6f 74 68 65 72 20 74 ime as another t
3bac0 68 72 65 61 64 20 69 73 20 69 6e 76 6f 6b 69 6e hread is invokin
3bad0 67 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 g sqlite3_backup
3bae0 5f 73 74 65 70 28 29 20 69 74 20 69 73 0a 2a 2a _step() it is.**
3baf0 20 70 6f 73 73 69 62 6c 65 20 74 68 61 74 20 74 possible that t
3bb00 68 65 79 20 72 65 74 75 72 6e 20 69 6e 76 61 6c hey return inval
3bb10 69 64 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 73 71 id values..*/.sq
3bb20 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 2a 73 71 lite3_backup *sq
3bb30 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 lite3_backup_ini
3bb40 74 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 70 44 t(. sqlite3 *pD
3bb50 65 73 74 2c 20 20 20 20 20 20 20 20 20 20 20 20 est,
3bb60 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
3bb70 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 estination datab
3bb80 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
3bb90 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 65 73 const char *zDes
3bba0 74 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 tName,
3bbb0 20 20 20 20 20 20 20 2f 2a 20 44 65 73 74 69 6e /* Destin
3bbc0 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 20 6e ation database n
3bbd0 61 6d 65 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 ame */. sqlite3
3bbe0 20 2a 70 53 6f 75 72 63 65 2c 20 20 20 20 20 20 *pSource,
3bbf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3bc00 2f 2a 20 53 6f 75 72 63 65 20 64 61 74 61 62 61 /* Source databa
3bc10 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
3bc20 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 6f 75 72 onst char *zSour
3bc30 63 65 4e 61 6d 65 20 20 20 20 20 20 20 20 20 20 ceName
3bc40 20 20 20 20 20 20 2f 2a 20 53 6f 75 72 63 65 20 /* Source
3bc50 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 2a 2f database name */
3bc60 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
3bc70 62 61 63 6b 75 70 5f 73 74 65 70 28 73 71 6c 69 backup_step(sqli
3bc80 74 65 33 5f 62 61 63 6b 75 70 20 2a 70 2c 20 69 te3_backup *p, i
3bc90 6e 74 20 6e 50 61 67 65 29 3b 0a 69 6e 74 20 73 nt nPage);.int s
3bca0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 qlite3_backup_fi
3bcb0 6e 69 73 68 28 73 71 6c 69 74 65 33 5f 62 61 63 nish(sqlite3_bac
3bcc0 6b 75 70 20 2a 70 29 3b 0a 69 6e 74 20 73 71 6c kup *p);.int sql
3bcd0 69 74 65 33 5f 62 61 63 6b 75 70 5f 72 65 6d 61 ite3_backup_rema
3bce0 69 6e 69 6e 67 28 73 71 6c 69 74 65 33 5f 62 61 ining(sqlite3_ba
3bcf0 63 6b 75 70 20 2a 70 29 3b 0a 69 6e 74 20 73 71 ckup *p);.int sq
3bd00 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 70 61 67 lite3_backup_pag
3bd10 65 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 62 ecount(sqlite3_b
3bd20 61 63 6b 75 70 20 2a 70 29 3b 0a 0a 2f 2a 0a 2a ackup *p);../*.*
3bd30 2a 20 43 41 50 49 33 52 45 46 3a 20 55 6e 6c 6f * CAPI3REF: Unlo
3bd40 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 0a ck Notification.
3bd50 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
3bd60 2a 2a 0a 2a 2a 20 57 68 65 6e 20 72 75 6e 6e 69 **.** When runni
3bd70 6e 67 20 69 6e 20 73 68 61 72 65 64 2d 63 61 63 ng in shared-cac
3bd80 68 65 20 6d 6f 64 65 2c 20 61 20 64 61 74 61 62 he mode, a datab
3bd90 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 6d 61 ase operation ma
3bda0 79 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 61 y fail with.** a
3bdb0 6e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 n [SQLITE_LOCKED
3bdc0 5d 20 65 72 72 6f 72 20 69 66 20 74 68 65 20 72 ] error if the r
3bdd0 65 71 75 69 72 65 64 20 6c 6f 63 6b 73 20 6f 6e equired locks on
3bde0 20 74 68 65 20 73 68 61 72 65 64 2d 63 61 63 68 the shared-cach
3bdf0 65 20 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 e or.** individu
3be00 61 6c 20 74 61 62 6c 65 73 20 77 69 74 68 69 6e al tables within
3be10 20 74 68 65 20 73 68 61 72 65 64 2d 63 61 63 68 the shared-cach
3be20 65 20 63 61 6e 6e 6f 74 20 62 65 20 6f 62 74 61 e cannot be obta
3be30 69 6e 65 64 2e 20 53 65 65 0a 2a 2a 20 5b 53 51 ined. See.** [SQ
3be40 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 Lite Shared-Cach
3be50 65 20 4d 6f 64 65 5d 20 66 6f 72 20 61 20 64 65 e Mode] for a de
3be60 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 73 68 61 scription of sha
3be70 72 65 64 2d 63 61 63 68 65 20 6c 6f 63 6b 69 6e red-cache lockin
3be80 67 2e 20 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 g. .** This API
3be90 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 72 may be used to r
3bea0 65 67 69 73 74 65 72 20 61 20 63 61 6c 6c 62 61 egister a callba
3beb0 63 6b 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 ck that SQLite w
3bec0 69 6c 6c 20 69 6e 76 6f 6b 65 20 0a 2a 2a 20 77 ill invoke .** w
3bed0 68 65 6e 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 hen the connecti
3bee0 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 68 6f 6c on currently hol
3bef0 64 69 6e 67 20 74 68 65 20 72 65 71 75 69 72 65 ding the require
3bf00 64 20 6c 6f 63 6b 20 72 65 6c 69 6e 71 75 69 73 d lock relinquis
3bf10 68 65 73 20 69 74 2e 0a 2a 2a 20 54 68 69 73 20 hes it..** This
3bf20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 API is only avai
3bf30 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 lable if the lib
3bf40 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 rary was compile
3bf50 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 d with the.** [S
3bf60 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 55 4e 4c QLITE_ENABLE_UNL
3bf70 4f 43 4b 5f 4e 4f 54 49 46 59 5d 20 43 2d 70 72 OCK_NOTIFY] C-pr
3bf80 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f eprocessor symbo
3bf90 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a l defined..**.**
3bfa0 20 53 65 65 20 41 6c 73 6f 3a 20 5b 55 73 69 6e See Also: [Usin
3bfb0 67 20 74 68 65 20 53 51 4c 69 74 65 20 55 6e 6c g the SQLite Unl
3bfc0 6f 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e ock Notification
3bfd0 20 46 65 61 74 75 72 65 5d 2e 0a 2a 2a 0a 2a 2a Feature]..**.**
3bfe0 20 53 68 61 72 65 64 2d 63 61 63 68 65 20 6c 6f Shared-cache lo
3bff0 63 6b 73 20 61 72 65 20 72 65 6c 65 61 73 65 64 cks are released
3c000 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 when a database
3c010 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6f 6e 63 connection conc
3c020 6c 75 64 65 73 0a 2a 2a 20 69 74 73 20 63 75 72 ludes.** its cur
3c030 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e rent transaction
3c040 2c 20 65 69 74 68 65 72 20 62 79 20 63 6f 6d 6d , either by comm
3c050 69 74 74 69 6e 67 20 69 74 20 6f 72 20 72 6f 6c itting it or rol
3c060 6c 69 6e 67 20 69 74 20 62 61 63 6b 2e 20 0a 2a ling it back. .*
3c070 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e 6e *.** When a conn
3c080 65 63 74 69 6f 6e 20 28 6b 6e 6f 77 6e 20 61 73 ection (known as
3c090 20 74 68 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e the blocked con
3c0a0 6e 65 63 74 69 6f 6e 29 20 66 61 69 6c 73 20 74 nection) fails t
3c0b0 6f 20 6f 62 74 61 69 6e 20 61 0a 2a 2a 20 73 68 o obtain a.** sh
3c0c0 61 72 65 64 2d 63 61 63 68 65 20 6c 6f 63 6b 20 ared-cache lock
3c0d0 61 6e 64 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 and SQLITE_LOCKE
3c0e0 44 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f D is returned to
3c0f0 20 74 68 65 20 63 61 6c 6c 65 72 2c 20 74 68 65 the caller, the
3c100 0a 2a 2a 20 69 64 65 6e 74 69 74 79 20 6f 66 20 .** identity of
3c110 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
3c120 6e 65 63 74 69 6f 6e 20 28 74 68 65 20 62 6c 6f nection (the blo
3c130 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e cking connection
3c140 29 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 6c 6f ) that.** has lo
3c150 63 6b 65 64 20 74 68 65 20 72 65 71 75 69 72 65 cked the require
3c160 64 20 72 65 73 6f 75 72 63 65 20 69 73 20 73 74 d resource is st
3c170 6f 72 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e ored internally.
3c180 20 41 66 74 65 72 20 61 6e 20 0a 2a 2a 20 61 70 After an .** ap
3c190 70 6c 69 63 61 74 69 6f 6e 20 72 65 63 65 69 76 plication receiv
3c1a0 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4c 4f 43 es an SQLITE_LOC
3c1b0 4b 45 44 20 65 72 72 6f 72 2c 20 69 74 20 6d 61 KED error, it ma
3c1c0 79 20 63 61 6c 6c 20 74 68 65 0a 2a 2a 20 73 71 y call the.** sq
3c1d0 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 lite3_unlock_not
3c1e0 69 66 79 28 29 20 6d 65 74 68 6f 64 20 77 69 74 ify() method wit
3c1f0 68 20 74 68 65 20 62 6c 6f 63 6b 65 64 20 63 6f h the blocked co
3c200 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 nnection handle
3c210 61 73 20 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 as .** the first
3c220 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 65 67 argument to reg
3c230 69 73 74 65 72 20 66 6f 72 20 61 20 63 61 6c 6c ister for a call
3c240 62 61 63 6b 20 74 68 61 74 20 77 69 6c 6c 20 62 back that will b
3c250 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 e invoked.** whe
3c260 6e 20 74 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 n the blocking c
3c270 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 75 72 72 65 onnections curre
3c280 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 nt transaction i
3c290 73 20 63 6f 6e 63 6c 75 64 65 64 2e 20 54 68 65 s concluded. The
3c2a0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 .** callback is
3c2b0 69 6e 76 6f 6b 65 64 20 66 72 6f 6d 20 77 69 74 invoked from wit
3c2c0 68 69 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 hin the [sqlite3
3c2d0 5f 73 74 65 70 5d 20 6f 72 20 5b 73 71 6c 69 74 _step] or [sqlit
3c2e0 65 33 5f 63 6c 6f 73 65 5d 0a 2a 2a 20 63 61 6c e3_close].** cal
3c2f0 6c 20 74 68 61 74 20 63 6f 6e 63 6c 75 64 65 73 l that concludes
3c300 20 74 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f the blocking co
3c310 6e 6e 65 63 74 69 6f 6e 73 20 74 72 61 6e 73 61 nnections transa
3c320 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ction..**.** If
3c330 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e sqlite3_unlock_n
3c340 6f 74 69 66 79 28 29 20 69 73 20 63 61 6c 6c 65 otify() is calle
3c350 64 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 d in a multi-thr
3c360 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f eaded applicatio
3c370 6e 2c 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 n,.** there is a
3c380 20 63 68 61 6e 63 65 20 74 68 61 74 20 74 68 65 chance that the
3c390 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 blocking connec
3c3a0 74 69 6f 6e 20 77 69 6c 6c 20 68 61 76 65 20 61 tion will have a
3c3b0 6c 72 65 61 64 79 0a 2a 2a 20 63 6f 6e 63 6c 75 lready.** conclu
3c3c0 64 65 64 20 69 74 73 20 74 72 61 6e 73 61 63 74 ded its transact
3c3d0 69 6f 6e 20 62 79 20 74 68 65 20 74 69 6d 65 20 ion by the time
3c3e0 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e sqlite3_unlock_n
3c3f0 6f 74 69 66 79 28 29 20 69 73 20 69 6e 76 6f 6b otify() is invok
3c400 65 64 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 68 ed..** If this h
3c410 61 70 70 65 6e 73 2c 20 74 68 65 6e 20 74 68 65 appens, then the
3c420 20 73 70 65 63 69 66 69 65 64 20 63 61 6c 6c 62 specified callb
3c430 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 ack is invoked i
3c440 6d 6d 65 64 69 61 74 65 6c 79 2c 0a 2a 2a 20 66 mmediately,.** f
3c450 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 63 rom within the c
3c460 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 all to sqlite3_u
3c470 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 2e 0a nlock_notify()..
3c480 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62 6c 6f **.** If the blo
3c490 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 cked connection
3c4a0 69 73 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f is attempting to
3c4b0 20 6f 62 74 61 69 6e 20 61 20 77 72 69 74 65 2d obtain a write-
3c4c0 6c 6f 63 6b 20 6f 6e 20 61 0a 2a 2a 20 73 68 61 lock on a.** sha
3c4d0 72 65 64 2d 63 61 63 68 65 20 74 61 62 6c 65 2c red-cache table,
3c4e0 20 61 6e 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f and more than o
3c4f0 6e 65 20 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74 ne other connect
3c500 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 68 6f ion currently ho
3c510 6c 64 73 0a 2a 2a 20 61 20 72 65 61 64 2d 6c 6f lds.** a read-lo
3c520 63 6b 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 74 ck on the same t
3c530 61 62 6c 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 able, then SQLit
3c540 65 20 61 72 62 69 74 72 61 72 69 6c 79 20 73 65 e arbitrarily se
3c550 6c 65 63 74 73 20 6f 6e 65 20 6f 66 20 0a 2a 2a lects one of .**
3c560 20 74 68 65 20 6f 74 68 65 72 20 63 6f 6e 6e 65 the other conne
3c570 63 74 69 6f 6e 73 20 74 6f 20 75 73 65 20 61 73 ctions to use as
3c580 20 74 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f the blocking co
3c590 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 nnection..**.**
3c5a0 54 68 65 72 65 20 6d 61 79 20 62 65 20 61 74 20 There may be at
3c5b0 6d 6f 73 74 20 6f 6e 65 20 75 6e 6c 6f 63 6b 2d most one unlock-
3c5c0 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 notify callback
3c5d0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 61 20 registered by a
3c5e0 0a 2a 2a 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e .** blocked conn
3c5f0 65 63 74 69 6f 6e 2e 20 49 66 20 73 71 6c 69 74 ection. If sqlit
3c600 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 e3_unlock_notify
3c610 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 () is called whe
3c620 6e 20 74 68 65 0a 2a 2a 20 62 6c 6f 63 6b 65 64 n the.** blocked
3c630 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6c 72 65 connection alre
3c640 61 64 79 20 68 61 73 20 61 20 72 65 67 69 73 74 ady has a regist
3c650 65 72 65 64 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 ered unlock-noti
3c660 66 79 20 63 61 6c 6c 62 61 63 6b 2c 0a 2a 2a 20 fy callback,.**
3c670 74 68 65 6e 20 74 68 65 20 6e 65 77 20 63 61 6c then the new cal
3c680 6c 62 61 63 6b 20 72 65 70 6c 61 63 65 73 20 74 lback replaces t
3c690 68 65 20 6f 6c 64 2e 20 49 66 20 73 71 6c 69 74 he old. If sqlit
3c6a0 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 e3_unlock_notify
3c6b0 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 () is.** called
3c6c0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e with a NULL poin
3c6d0 74 65 72 20 61 73 20 69 74 73 20 73 65 63 6f 6e ter as its secon
3c6e0 64 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 65 6e d argument, then
3c6f0 20 61 6e 79 20 65 78 69 73 74 69 6e 67 0a 2a 2a any existing.**
3c700 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 unlock-notify c
3c710 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 allback is cance
3c720 6c 6c 65 64 2e 20 54 68 65 20 62 6c 6f 63 6b 65 lled. The blocke
3c730 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 0a 2a d connections .*
3c740 2a 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 * unlock-notify
3c750 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 61 6c 73 callback may als
3c760 6f 20 62 65 20 63 61 6e 63 65 6c 65 64 20 62 79 o be canceled by
3c770 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 62 6c 6f closing the blo
3c780 63 6b 65 64 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 cked.** connecti
3c790 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 on using [sqlite
3c7a0 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 3_close()]..**.*
3c7b0 2a 20 54 68 65 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 * The unlock-not
3c7c0 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ify callback is
3c7d0 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 49 not reentrant. I
3c7e0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
3c7f0 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 61 6e 79 20 invokes.** any
3c800 73 71 6c 69 74 65 33 5f 78 78 78 20 41 50 49 20 sqlite3_xxx API
3c810 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 77 functions from w
3c820 69 74 68 69 6e 20 61 6e 20 75 6e 6c 6f 63 6b 2d ithin an unlock-
3c830 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 2c notify callback,
3c840 20 61 0a 2a 2a 20 63 72 61 73 68 20 6f 72 20 64 a.** crash or d
3c850 65 61 64 6c 6f 63 6b 20 6d 61 79 20 62 65 20 74 eadlock may be t
3c860 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a he result..**.**
3c870 20 55 6e 6c 65 73 73 20 64 65 61 64 6c 6f 63 6b Unless deadlock
3c880 20 69 73 20 64 65 74 65 63 74 65 64 20 28 73 65 is detected (se
3c890 65 20 62 65 6c 6f 77 29 2c 20 73 71 6c 69 74 65 e below), sqlite
3c8a0 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 3_unlock_notify(
3c8b0 29 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 ) always.** retu
3c8c0 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a rns SQLITE_OK..*
3c8d0 2a 0a 2a 2a 20 3c 62 3e 43 61 6c 6c 62 61 63 6b *.** <b>Callback
3c8e0 20 49 6e 76 6f 63 61 74 69 6f 6e 20 44 65 74 61 Invocation Deta
3c8f0 69 6c 73 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 57 68 ils</b>.**.** Wh
3c900 65 6e 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 en an unlock-not
3c910 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ify callback is
3c920 72 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 registered, the
3c930 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 application prov
3c940 69 64 65 73 20 61 20 0a 2a 2a 20 73 69 6e 67 6c ides a .** singl
3c950 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 e void* pointer
3c960 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 74 that is passed t
3c970 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 o the callback w
3c980 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 hen it is invoke
3c990 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 d..** However, t
3c9a0 68 65 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 he signature of
3c9b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e the callback fun
3c9c0 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 53 51 4c ction allows SQL
3c9d0 69 74 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20 69 ite to pass.** i
3c9e0 74 20 61 6e 20 61 72 72 61 79 20 6f 66 20 76 6f t an array of vo
3c9f0 69 64 2a 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e id* context poin
3ca00 74 65 72 73 2e 20 54 68 65 20 66 69 72 73 74 20 ters. The first
3ca10 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 argument passed
3ca20 74 6f 0a 2a 2a 20 61 6e 20 75 6e 6c 6f 63 6b 2d to.** an unlock-
3ca30 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 notify callback
3ca40 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
3ca50 61 6e 20 61 72 72 61 79 20 6f 66 20 76 6f 69 64 an array of void
3ca60 2a 20 70 6f 69 6e 74 65 72 73 2c 0a 2a 2a 20 61 * pointers,.** a
3ca70 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 nd the second is
3ca80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 the number of e
3ca90 6e 74 72 69 65 73 20 69 6e 20 74 68 65 20 61 72 ntries in the ar
3caa0 72 61 79 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 ray..**.** When
3cab0 61 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 a blocking conne
3cac0 63 74 69 6f 6e 73 20 74 72 61 6e 73 61 63 74 69 ctions transacti
3cad0 6f 6e 20 69 73 20 63 6f 6e 63 6c 75 64 65 64 2c on is concluded,
3cae0 20 74 68 65 72 65 20 6d 61 79 20 62 65 0a 2a 2a there may be.**
3caf0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 62 more than one b
3cb00 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f locked connectio
3cb10 6e 20 74 68 61 74 20 68 61 73 20 72 65 67 69 73 n that has regis
3cb20 74 65 72 65 64 20 66 6f 72 20 61 6e 20 75 6e 6c tered for an unl
3cb30 6f 63 6b 2d 6e 6f 74 69 66 79 0a 2a 2a 20 63 61 ock-notify.** ca
3cb40 6c 6c 62 61 63 6b 2e 20 49 66 20 74 77 6f 20 6f llback. If two o
3cb50 72 20 6d 6f 72 65 20 73 75 63 68 20 62 6c 6f 63 r more such bloc
3cb60 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ked connections
3cb70 68 61 76 65 20 73 70 65 63 69 66 69 65 64 20 74 have specified t
3cb80 68 65 0a 2a 2a 20 73 61 6d 65 20 63 61 6c 6c 62 he.** same callb
3cb90 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2c 20 74 68 ack function, th
3cba0 65 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e en instead of in
3cbb0 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 voking the callb
3cbc0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ack function.**
3cbd0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 2c 20 multiple times,
3cbe0 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e it is invoked on
3cbf0 63 65 20 77 69 74 68 20 74 68 65 20 73 65 74 20 ce with the set
3cc00 6f 66 20 76 6f 69 64 2a 20 63 6f 6e 74 65 78 74 of void* context
3cc10 20 70 6f 69 6e 74 65 72 73 0a 2a 2a 20 73 70 65 pointers.** spe
3cc20 63 69 66 69 65 64 20 62 79 20 74 68 65 20 62 6c cified by the bl
3cc30 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e ocked connection
3cc40 73 20 62 75 6e 64 6c 65 64 20 74 6f 67 65 74 68 s bundled togeth
3cc50 65 72 20 69 6e 74 6f 20 61 6e 20 61 72 72 61 79 er into an array
3cc60 2e 0a 2a 2a 20 54 68 69 73 20 67 69 76 65 73 20 ..** This gives
3cc70 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
3cc80 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 an opportunity t
3cc90 6f 20 70 72 69 6f 72 69 74 69 7a 65 20 61 6e 79 o prioritize any
3cca0 20 61 63 74 69 6f 6e 73 20 0a 2a 2a 20 72 65 6c actions .** rel
3ccb0 61 74 65 64 20 74 6f 20 74 68 65 20 73 65 74 20 ated to the set
3ccc0 6f 66 20 75 6e 62 6c 6f 63 6b 65 64 20 64 61 74 of unblocked dat
3ccd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3cce0 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 61 64 s..**.** <b>Dead
3ccf0 6c 6f 63 6b 20 44 65 74 65 63 74 69 6f 6e 3c 2f lock Detection</
3cd00 62 3e 0a 2a 2a 0a 2a 2a 20 41 73 73 75 6d 69 6e b>.**.** Assumin
3cd10 67 20 74 68 61 74 20 61 66 74 65 72 20 72 65 67 g that after reg
3cd20 69 73 74 65 72 69 6e 67 20 66 6f 72 20 61 6e 20 istering for an
3cd30 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 unlock-notify ca
3cd40 6c 6c 62 61 63 6b 20 61 20 0a 2a 2a 20 64 61 74 llback a .** dat
3cd50 61 62 61 73 65 20 77 61 69 74 73 20 66 6f 72 20 abase waits for
3cd60 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 the callback to
3cd70 62 65 20 69 73 73 75 65 64 20 62 65 66 6f 72 65 be issued before
3cd80 20 74 61 6b 69 6e 67 20 61 6e 79 20 66 75 72 74 taking any furt
3cd90 68 65 72 0a 2a 2a 20 61 63 74 69 6f 6e 20 28 61 her.** action (a
3cda0 20 72 65 61 73 6f 6e 61 62 6c 65 20 61 73 73 75 reasonable assu
3cdb0 6d 70 74 69 6f 6e 29 2c 20 74 68 65 6e 20 75 73 mption), then us
3cdc0 69 6e 67 20 74 68 69 73 20 41 50 49 20 6d 61 79 ing this API may
3cdd0 20 63 61 75 73 65 20 74 68 65 0a 2a 2a 20 61 70 cause the.** ap
3cde0 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 64 65 61 plication to dea
3cdf0 64 6c 6f 63 6b 2e 20 46 6f 72 20 65 78 61 6d 70 dlock. For examp
3ce00 6c 65 2c 20 69 66 20 63 6f 6e 6e 65 63 74 69 6f le, if connectio
3ce10 6e 20 58 20 69 73 20 77 61 69 74 69 6e 67 20 66 n X is waiting f
3ce20 6f 72 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e or.** connection
3ce30 20 59 27 73 20 74 72 61 6e 73 61 63 74 69 6f 6e Y's transaction
3ce40 20 74 6f 20 62 65 20 63 6f 6e 63 6c 75 64 65 64 to be concluded
3ce50 2c 20 61 6e 64 20 73 69 6d 69 6c 61 72 6c 79 20 , and similarly
3ce60 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 59 20 connection.** Y
3ce70 69 73 20 77 61 69 74 69 6e 67 20 6f 6e 20 63 6f is waiting on co
3ce80 6e 6e 65 63 74 69 6f 6e 20 58 27 73 20 74 72 61 nnection X's tra
3ce90 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 6e nsaction, then n
3cea0 65 69 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f either connectio
3ceb0 6e 0a 2a 2a 20 77 69 6c 6c 20 70 72 6f 63 65 65 n.** will procee
3cec0 64 20 61 6e 64 20 74 68 65 20 73 79 73 74 65 6d d and the system
3ced0 20 6d 61 79 20 72 65 6d 61 69 6e 20 64 65 61 64 may remain dead
3cee0 6c 6f 63 6b 65 64 20 69 6e 64 65 66 69 6e 69 74 locked indefinit
3cef0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 ely..**.** To av
3cf00 6f 69 64 20 74 68 69 73 20 73 63 65 6e 61 72 69 oid this scenari
3cf10 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 75 o, the sqlite3_u
3cf20 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 70 nlock_notify() p
3cf30 65 72 66 6f 72 6d 73 20 64 65 61 64 6c 6f 63 6b erforms deadlock
3cf40 0a 2a 2a 20 64 65 74 65 63 74 69 6f 6e 2e 20 49 .** detection. I
3cf50 66 20 61 20 67 69 76 65 6e 20 63 61 6c 6c 20 74 f a given call t
3cf60 6f 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b o sqlite3_unlock
3cf70 5f 6e 6f 74 69 66 79 28 29 20 77 6f 75 6c 64 20 _notify() would
3cf80 70 75 74 20 74 68 65 0a 2a 2a 20 73 79 73 74 65 put the.** syste
3cf90 6d 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 65 m in a deadlocke
3cfa0 64 20 73 74 61 74 65 2c 20 74 68 65 6e 20 53 51 d state, then SQ
3cfb0 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 69 73 20 72 LITE_LOCKED is r
3cfc0 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 0a 2a eturned and no.*
3cfd0 2a 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 * unlock-notify
3cfe0 63 61 6c 6c 62 61 63 6b 20 69 73 20 72 65 67 69 callback is regi
3cff0 73 74 65 72 65 64 2e 20 54 68 65 20 73 79 73 74 stered. The syst
3d000 65 6d 20 69 73 20 73 61 69 64 20 74 6f 20 62 65 em is said to be
3d010 20 69 6e 0a 2a 2a 20 61 20 64 65 61 64 6c 6f 63 in.** a deadloc
3d020 6b 65 64 20 73 74 61 74 65 20 69 66 20 63 6f 6e ked state if con
3d030 6e 65 63 74 69 6f 6e 20 41 20 68 61 73 20 72 65 nection A has re
3d040 67 69 73 74 65 72 65 64 20 66 6f 72 20 61 6e 20 gistered for an
3d050 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 0a 2a 2a unlock-notify.**
3d060 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 74 68 65 callback on the
3d070 20 63 6f 6e 63 6c 75 73 69 6f 6e 20 6f 66 20 63 conclusion of c
3d080 6f 6e 6e 65 63 74 69 6f 6e 20 42 27 73 20 74 72 onnection B's tr
3d090 61 6e 73 61 63 74 69 6f 6e 2c 20 61 6e 64 20 63 ansaction, and c
3d0a0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 42 20 68 onnection.** B h
3d0b0 61 73 20 69 74 73 65 6c 66 20 72 65 67 69 73 74 as itself regist
3d0c0 65 72 65 64 20 66 6f 72 20 61 6e 20 75 6e 6c 6f ered for an unlo
3d0d0 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 ck-notify callba
3d0e0 63 6b 20 77 68 65 6e 20 63 6f 6e 6e 65 63 74 69 ck when connecti
3d0f0 6f 6e 0a 2a 2a 20 41 27 73 20 74 72 61 6e 73 61 on.** A's transa
3d100 63 74 69 6f 6e 20 69 73 20 63 6f 6e 63 6c 75 64 ction is conclud
3d110 65 64 2e 20 49 6e 64 69 72 65 63 74 20 64 65 61 ed. Indirect dea
3d120 64 6c 6f 63 6b 20 69 73 20 61 6c 73 6f 20 64 65 dlock is also de
3d130 74 65 63 74 65 64 2c 20 73 6f 0a 2a 2a 20 74 68 tected, so.** th
3d140 65 20 73 79 73 74 65 6d 20 69 73 20 61 6c 73 6f e system is also
3d150 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 considered to b
3d160 65 20 64 65 61 64 6c 6f 63 6b 65 64 20 69 66 20 e deadlocked if
3d170 63 6f 6e 6e 65 63 74 69 6f 6e 20 42 20 68 61 73 connection B has
3d180 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 66 .** registered f
3d190 6f 72 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 or an unlock-not
3d1a0 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 ify callback on
3d1b0 74 68 65 20 63 6f 6e 63 6c 75 73 69 6f 6e 20 6f the conclusion o
3d1c0 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 f connection.**
3d1d0 43 27 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c C's transaction,
3d1e0 20 77 68 65 72 65 20 63 6f 6e 6e 65 63 74 69 6f where connectio
3d1f0 6e 20 43 20 69 73 20 77 61 69 74 69 6e 67 20 6f n C is waiting o
3d200 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 41 2e 20 n connection A.
3d210 41 6e 79 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 Any.** number of
3d220 20 6c 65 76 65 6c 73 20 6f 66 20 69 6e 64 69 72 levels of indir
3d230 65 63 74 69 6f 6e 20 61 72 65 20 61 6c 6c 6f 77 ection are allow
3d240 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 ed..**.** <b>The
3d250 20 22 44 52 4f 50 20 54 41 42 4c 45 22 20 45 78 "DROP TABLE" Ex
3d260 63 65 70 74 69 6f 6e 3c 2f 62 3e 0a 2a 2a 0a 2a ception</b>.**.*
3d270 2a 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f * When a call to
3d280 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
3d290 5d 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 ] returns SQLITE
3d2a0 5f 4c 4f 43 4b 45 44 2c 20 69 74 20 69 73 20 61 _LOCKED, it is a
3d2b0 6c 6d 6f 73 74 20 0a 2a 2a 20 61 6c 77 61 79 73 lmost .** always
3d2c0 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 6f 20 appropriate to
3d2d0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 75 6e 6c call sqlite3_unl
3d2e0 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 2e 20 54 68 ock_notify(). Th
3d2f0 65 72 65 20 69 73 20 68 6f 77 65 76 65 72 2c 0a ere is however,.
3d300 2a 2a 20 6f 6e 65 20 65 78 63 65 70 74 69 6f 6e ** one exception
3d310 2e 20 57 68 65 6e 20 65 78 65 63 75 74 69 6e 67 . When executing
3d320 20 61 20 22 44 52 4f 50 20 54 41 42 4c 45 22 20 a "DROP TABLE"
3d330 6f 72 20 22 44 52 4f 50 20 49 4e 44 45 58 22 20 or "DROP INDEX"
3d340 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 53 51 statement,.** SQ
3d350 4c 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 Lite checks if t
3d360 68 65 72 65 20 61 72 65 20 61 6e 79 20 63 75 72 here are any cur
3d370 72 65 6e 74 6c 79 20 65 78 65 63 75 74 69 6e 67 rently executing
3d380 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e SELECT statemen
3d390 74 73 0a 2a 2a 20 74 68 61 74 20 62 65 6c 6f 6e ts.** that belon
3d3a0 67 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f g to the same co
3d3b0 6e 6e 65 63 74 69 6f 6e 2e 20 49 66 20 74 68 65 nnection. If the
3d3c0 72 65 20 61 72 65 2c 20 53 51 4c 49 54 45 5f 4c re are, SQLITE_L
3d3d0 4f 43 4b 45 44 20 69 73 0a 2a 2a 20 72 65 74 75 OCKED is.** retu
3d3e0 72 6e 65 64 2e 20 49 6e 20 74 68 69 73 20 63 61 rned. In this ca
3d3f0 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 22 se there is no "
3d400 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 blocking connect
3d410 69 6f 6e 22 2c 20 73 6f 20 69 6e 76 6f 6b 69 6e ion", so invokin
3d420 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 6e 6c g.** sqlite3_unl
3d430 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 72 65 73 ock_notify() res
3d440 75 6c 74 73 20 69 6e 20 74 68 65 20 75 6e 6c 6f ults in the unlo
3d450 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 ck-notify callba
3d460 63 6b 20 62 65 69 6e 67 0a 2a 2a 20 69 6e 76 6f ck being.** invo
3d470 6b 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e ked immediately.
3d480 20 49 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 If the applicat
3d490 69 6f 6e 20 74 68 65 6e 20 72 65 2d 61 74 74 65 ion then re-atte
3d4a0 6d 70 74 73 20 74 68 65 20 22 44 52 4f 50 20 54 mpts the "DROP T
3d4b0 41 42 4c 45 22 0a 2a 2a 20 6f 72 20 22 44 52 4f ABLE".** or "DRO
3d4c0 50 20 49 4e 44 45 58 22 20 71 75 65 72 79 2c 20 P INDEX" query,
3d4d0 61 6e 20 69 6e 66 69 6e 69 74 65 20 6c 6f 6f 70 an infinite loop
3d4e0 20 6d 69 67 68 74 20 62 65 20 74 68 65 20 72 65 might be the re
3d4f0 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 sult..**.** One
3d500 77 61 79 20 61 72 6f 75 6e 64 20 74 68 69 73 20 way around this
3d510 70 72 6f 62 6c 65 6d 20 69 73 20 74 6f 20 63 68 problem is to ch
3d520 65 63 6b 20 74 68 65 20 65 78 74 65 6e 64 65 64 eck the extended
3d530 20 65 72 72 6f 72 20 63 6f 64 65 20 72 65 74 75 error code retu
3d540 72 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 73 71 rned.** by an sq
3d550 6c 69 74 65 33 5f 73 74 65 70 28 29 20 63 61 6c lite3_step() cal
3d560 6c 2e 20 49 66 20 74 68 65 72 65 20 69 73 20 61 l. If there is a
3d570 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 blocking connec
3d580 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 0a 2a tion, then the.*
3d590 2a 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 * extended error
3d5a0 20 63 6f 64 65 20 69 73 20 73 65 74 20 74 6f 20 code is set to
3d5b0 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 SQLITE_LOCKED_SH
3d5c0 41 52 45 44 43 41 43 48 45 2e 20 4f 74 68 65 72 AREDCACHE. Other
3d5d0 77 69 73 65 2c 20 69 6e 0a 2a 2a 20 74 68 65 20 wise, in.** the
3d5e0 73 70 65 63 69 61 6c 20 22 44 52 4f 50 20 54 41 special "DROP TA
3d5f0 42 4c 45 2f 49 4e 44 45 58 22 20 63 61 73 65 2c BLE/INDEX" case,
3d600 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 65 72 the extended er
3d610 72 6f 72 20 63 6f 64 65 20 69 73 20 6a 75 73 74 ror code is just
3d620 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4c 4f 43 4b .** SQLITE_LOCK
3d630 45 44 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ED..*/.int sqlit
3d640 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 e3_unlock_notify
3d650 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 70 42 6c (. sqlite3 *pBl
3d660 6f 63 6b 65 64 2c 20 20 20 20 20 20 20 20 20 20 ocked,
3d670 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3d680 2f 2a 20 57 61 69 74 69 6e 67 20 63 6f 6e 6e 65 /* Waiting conne
3d690 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 ction */. void
3d6a0 28 2a 78 4e 6f 74 69 66 79 29 28 76 6f 69 64 20 (*xNotify)(void
3d6b0 2a 2a 61 70 41 72 67 2c 20 69 6e 74 20 6e 41 72 **apArg, int nAr
3d6c0 67 29 2c 20 20 20 20 2f 2a 20 43 61 6c 6c 62 61 g), /* Callba
3d6d0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 ck function to i
3d6e0 6e 76 6f 6b 65 20 2a 2f 0a 20 20 76 6f 69 64 20 nvoke */. void
3d6f0 2a 70 4e 6f 74 69 66 79 41 72 67 20 20 20 20 20 *pNotifyArg
3d700 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3d710 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 /* Argume
3d720 6e 74 20 74 6f 20 70 61 73 73 20 74 6f 20 78 4e nt to pass to xN
3d730 6f 74 69 66 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a otify */.);../*.
3d740 2a 2a 20 55 6e 64 6f 20 74 68 65 20 68 61 63 6b ** Undo the hack
3d750 20 74 68 61 74 20 63 6f 6e 76 65 72 74 73 20 66 that converts f
3d760 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 loating point ty
3d770 70 65 73 20 74 6f 20 69 6e 74 65 67 65 72 20 66 pes to integer f
3d780 6f 72 0a 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 or.** builds on
3d790 70 72 6f 63 65 73 73 6f 72 73 20 77 69 74 68 6f processors witho
3d7a0 75 74 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e ut floating poin
3d7b0 74 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 t support..*/.#i
3d7c0 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 fdef SQLITE_OMIT
3d7d0 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a _FLOATING_POINT.
3d7e0 23 20 75 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 # undef double.#
3d7f0 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f endif..#ifdef __
3d800 63 70 6c 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 cplusplus.} /*
3d810 45 6e 64 20 6f 66 20 74 68 65 20 27 65 78 74 65 End of the 'exte
3d820 72 6e 20 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f rn "C"' block */
3d830 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a .#endif.#endif.