0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 ms copyright to
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a . In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d sing:.**.** M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 nd not evil..**
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 May you find
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 forgiveness for
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 give others..**
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 aking more than
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43 rograms. If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69 ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 s file, then it
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20 ite, is subject
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53 grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74 e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 erimental". Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64 s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20 to SQLite. We
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 e changes.** to
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65 erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20 r changes if.**
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20 experience from
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64 use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63 " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65 hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67 ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74 e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69 ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68 m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66 is file. This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65 ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61 suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 me of this file
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74 under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69 ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65 .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69 r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20 s file (such as
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65 inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29 version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73 and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65 name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20 3.h" as.** part
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29 cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e 69 $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 34 34 30 20 32 30 30 39 2f 30 n,v 1.440 2009/0
05f0: 34 2f 30 36 20 31 35 3a 35 35 3a 30 34 20 64 72 4/06 15:55:04 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 33 "3.6.13
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 33 0a 0a 2f 2a 0a 2a 2a 20 3006013../*.**
0ec0: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 CAPI3REF: Run-Ti
0ed0: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 me Library Versi
0ee0: 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 on Numbers {H100
0ef0: 32 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 20 20} <S60100>.**
0f00: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 KEYWORDS: sqlite
0f10: 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3_version.**.**
0f20: 54 68 65 73 65 20 66 65 61 74 75 72 65 73 20 70 These features p
0f30: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 rovide the same
0f40: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 information as t
0f50: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 he [SQLITE_VERSI
0f60: 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 ON].** and [SQLI
0f70: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
0f80: 52 5d 20 23 64 65 66 69 6e 65 73 20 69 6e 20 74 R] #defines in t
0f90: 68 65 20 68 65 61 64 65 72 2c 20 62 75 74 20 61 he header, but a
0fa0: 72 65 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a re associated.**
0fb0: 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 with the librar
0fc0: 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 y instead of the
0fd0: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 43 header file. C
0fe0: 61 75 74 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d autious programm
0ff0: 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63 ers might.** inc
1000: 6c 75 64 65 20 61 20 63 68 65 63 6b 20 69 6e 20 lude a check in
1010: 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f their applicatio
1020: 6e 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 n to verify that
1030: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 .** sqlite3_libv
1040: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 ersion_number()
1050: 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 always returns t
1060: 68 65 20 76 61 6c 75 65 0a 2a 2a 20 5b 53 51 4c he value.** [SQL
1070: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
1080: 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ER]..**.** The s
1090: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
10a0: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 n() function ret
10b0: 75 72 6e 73 20 74 68 65 20 73 61 6d 65 20 69 6e urns the same in
10c0: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a formation as is.
10d0: 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 ** in the sqlite
10e0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 3_version[] stri
10f0: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 ng constant. Th
1100: 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 e function is pr
1110: 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73 ovided.** for us
1120: 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 e in DLLs since
1130: 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c DLL users usuall
1140: 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 64 69 y do not have di
1150: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 rect access to s
1160: 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e tring.** constan
1170: 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c ts within the DL
1180: 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 L..**.** Require
1190: 6d 65 6e 74 73 3a 20 5b 48 31 30 30 32 31 5d 20 ments: [H10021]
11a0: 5b 48 31 30 30 32 32 5d 20 5b 48 31 30 30 32 33 [H10022] [H10023
11b0: 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 ].*/.SQLITE_EXTE
11c0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 RN const char sq
11d0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b lite3_version[];
11e0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
11f0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
1200: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 void);.int sqlit
1210: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 e3_libversion_nu
1220: 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a mber(void);../*.
1230: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 ** CAPI3REF: Tes
1240: 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 t To See If The
1250: 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 65 61 Library Is Threa
1260: 64 73 61 66 65 20 7b 48 31 30 31 30 30 7d 20 3c dsafe {H10100} <
1270: 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 S60100>.**.** SQ
1280: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 Lite can be comp
1290: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 iled with or wit
12a0: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 hout mutexes. W
12b0: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 hen.** the [SQLI
12c0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 TE_THREADSAFE] C
12d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
12e0: 63 72 6f 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 cro 1 or 2, mute
12f0: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c xes.** are enabl
1300: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 ed and SQLite is
1310: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 threadsafe. Wh
1320: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 en the.** [SQLIT
1330: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 E_THREADSAFE] ma
1340: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 cro is 0, .** th
1350: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d e mutexes are om
1360: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 itted. Without
1370: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 the mutexes, it
1380: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 is not safe.** t
1390: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e o use SQLite con
13a0: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d currently from m
13b0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 ore than one thr
13c0: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c ead..**.** Enabl
13d0: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 ing mutexes incu
13e0: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 rs a measurable
13f0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 performance pena
1400: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 lty..** So if sp
1410: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 eed is of utmost
1420: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 importance, it
1430: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 makes sense to d
1440: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 isable.** the mu
1450: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 texes. But for
1460: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 maximum safety,
1470: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 mutexes should b
1480: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 e enabled..** Th
1490: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 e default behavi
14a0: 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 or is for mutexe
14b0: 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e s to be enabled.
14c0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
14d0: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
14e0: 64 20 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74 d by a program t
14f0: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 o make sure that
1500: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 the.** version
1510: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 of SQLite that i
1520: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 t is linking aga
1530: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 inst was compile
1540: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 d with.** the de
1550: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 sired setting of
1560: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
1570: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a EADSAFE] macro..
1580: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
1590: 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 face only report
15a0: 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 s on the compile
15b0: 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 -time mutex sett
15c0: 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 ing.** of the [S
15d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
15e0: 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 ] flag. If SQLi
15f0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
1600: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 ith.** SQLITE_TH
1610: 52 45 41 44 53 41 46 45 3d 31 20 74 68 65 6e 20 READSAFE=1 then
1620: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 mutexes are enab
1630: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 led by default b
1640: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c ut.** can be ful
1650: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 ly or partially
1660: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 disabled using a
1670: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
1680: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 3_config()].** w
1690: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 ith the verbs [S
16a0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
16b0: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c GLETHREAD], [SQL
16c0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
16d0: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b THREAD],.** or [
16e0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
16f0: 54 45 58 5d 2e 20 20 54 68 65 20 72 65 74 75 72 TEX]. The retur
1700: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 n value of this
1710: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a function shows.*
1720: 2a 20 6f 6e 6c 79 20 74 68 65 20 64 65 66 61 75 * only the defau
1730: 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 lt compile-time
1740: 73 65 74 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79 setting, not any
1750: 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 run-time change
1760: 73 0a 2a 2a 20 74 6f 20 74 68 61 74 20 73 65 74 s.** to that set
1770: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 ting..**.** See
1780: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d the [threading m
1790: 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 ode] documentati
17a0: 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 on for additiona
17b0: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
17c0: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
17d0: 73 3a 20 5b 48 31 30 31 30 31 5d 20 5b 48 31 30 s: [H10101] [H10
17e0: 31 30 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 102].*/.int sqli
17f0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 te3_threadsafe(v
1800: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 oid);../*.** CAP
1810: 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 I3REF: Database
1820: 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c Connection Handl
1830: 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 30 32 e {H12000} <S402
1840: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 00>.** KEYWORDS:
1850: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 {database conne
1860: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 ction} {database
1870: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a connections}.**
1880: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 .** Each open SQ
1890: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 Lite database is
18a0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
18b0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
18c0: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 instance of.** t
18d0: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 he opaque struct
18e0: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 ure named "sqlit
18f0: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 e3". It is usef
1900: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 ul to think of a
1910: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 n sqlite3.** poi
1920: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 nter as an objec
1930: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 t. The [sqlite3
1940: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
1950: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e e3_open16()], an
1960: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 d.** [sqlite3_op
1970: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 en_v2()] interfa
1980: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 ces are its cons
1990: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 tructors, and [s
19a0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a qlite3_close()].
19b0: 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 72 75 ** is its destru
19c0: 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65 ctor. There are
19d0: 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 many other inte
19e0: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a rfaces (such as.
19f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
1a00: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
1a10: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
1a20: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b ion()], and.** [
1a30: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
1a40: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 eout()] to name
1a50: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 but three) that
1a60: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 are methods on a
1a70: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a n.** sqlite3 obj
1a80: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ect..*/.typedef
1a90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 struct sqlite3 s
1aa0: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 qlite3;../*.** C
1ab0: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 API3REF: 64-Bit
1ac0: 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b 48 Integer Types {H
1ad0: 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 10200} <S10110>.
1ae0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
1af0: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 ite_int64 sqlite
1b00: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 _uint64.**.** Be
1b10: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e cause there is n
1b20: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d o cross-platform
1b30: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 way to specify
1b40: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 64-bit integer t
1b50: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 ypes.** SQLite i
1b60: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 ncludes typedefs
1b70: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e for 64-bit sign
1b80: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 ed and unsigned
1b90: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 integers..**.**
1ba0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 The sqlite3_int6
1bb0: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 4 and sqlite3_ui
1bc0: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65 nt64 are the pre
1bd0: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69 ferred type defi
1be0: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 nitions..** The
1bf0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 sqlite_int64 and
1c00: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 sqlite_uint64 t
1c10: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 ypes are support
1c20: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ed for backwards
1c30: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 .** compatibilit
1c40: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 y only..**.** Re
1c50: 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 quirements: [H10
1c60: 32 30 31 5d 20 5b 48 31 30 32 30 32 5d 0a 2a 2f 201] [H10202].*/
1c70: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 .#ifdef SQLITE_I
1c80: 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 NT64_TYPE. type
1c90: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 def SQLITE_INT64
1ca0: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 _TYPE sqlite_int
1cb0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 64;. typedef un
1cc0: 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e signed SQLITE_IN
1cd0: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f T64_TYPE sqlite_
1ce0: 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 uint64;.#elif de
1cf0: 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 fined(_MSC_VER)
1d00: 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 || defined(__BOR
1d10: 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 LANDC__). typed
1d20: 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 ef __int64 sqlit
1d30: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 e_int64;. typed
1d40: 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e ef unsigned __in
1d50: 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 t64 sqlite_uint6
1d60: 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 4;.#else. typed
1d70: 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 ef long long int
1d80: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 sqlite_int64;.
1d90: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 typedef unsigne
1da0: 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 d long long int
1db0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 sqlite_uint64;.#
1dc0: 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 endif.typedef sq
1dd0: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 lite_int64 sqlit
1de0: 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 e3_int64;.typede
1df0: 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 f sqlite_uint64
1e00: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a sqlite3_uint64;.
1e10: 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c ./*.** If compil
1e20: 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 ing for a proces
1e30: 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 sor that lacks f
1e40: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 loating point su
1e50: 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 pport,.** substi
1e60: 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 tute integer for
1e70: 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e floating-point.
1e80: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 .*/.#ifdef SQLIT
1e90: 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f E_OMIT_FLOATING_
1ea0: 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 POINT.# define d
1eb0: 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e ouble sqlite3_in
1ec0: 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a t64.#endif../*.*
1ed0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 * CAPI3REF: Clos
1ee0: 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 ing A Database C
1ef0: 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 onnection {H1201
1f00: 30 7d 20 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 0} <S30100><S402
1f10: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 00>.**.** This r
1f20: 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64 65 outine is the de
1f30: 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 structor for the
1f40: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
1f50: 74 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 t..**.** Applica
1f60: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 tions should [sq
1f70: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c lite3_finalize |
1f80: 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b finalize] all [
1f90: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1fa0: 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c nts].** and [sql
1fb0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 ite3_blob_close
1fc0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c | close] all [BL
1fd0: 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f OB handles] asso
1fe0: 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 ciated with.** t
1ff0: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a he [sqlite3] obj
2000: 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 ect prior to att
2010: 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 empting to close
2020: 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 the object..**
2030: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 The [sqlite3_nex
2040: 74 5f 73 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 t_stmt()] interf
2050: 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ace can be used
2060: 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a to locate all.**
2070: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2080: 6d 65 6e 74 73 5d 20 61 73 73 6f 63 69 61 74 65 ments] associate
2090: 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 d with a [databa
20a0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
20b0: 66 20 64 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 f desired..** Ty
20c0: 70 69 63 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 pical code might
20d0: 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a look like this:
20e0: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
20f0: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 te><pre>.** sqli
2100: 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b te3_stmt *pStmt;
2110: 0a 2a 2a 20 77 68 69 6c 65 28 20 28 70 53 74 6d .** while( (pStm
2120: 74 20 3d 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 t = sqlite3_next
2130: 5f 73 74 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 _stmt(db, 0))!=0
2140: 20 29 7b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 ){.**
2150: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2160: 28 70 53 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a (pStmt);.** }.**
2170: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
2180: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 ote>.**.** If [s
2190: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 qlite3_close()]
21a0: 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 is invoked while
21b0: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
21c0: 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 s open,.** the t
21d0: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 ransaction is au
21e0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c tomatically roll
21f0: 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 ed back..**.** T
2200: 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 he C parameter t
2210: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 o [sqlite3_close
2220: 28 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 (C)] must be eit
2230: 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f her a NULL.** po
2240: 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c inter or an [sql
2250: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 ite3] object poi
2260: 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a nter obtained.**
2270: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f from [sqlite3_o
2280: 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
2290: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a _open16()], or.*
22a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f * [sqlite3_open_
22b0: 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 v2()], and not p
22c0: 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 reviously closed
22d0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
22e0: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 30 31 31 ents:.** [H12011
22f0: 5d 20 5b 48 31 32 30 31 32 5d 20 5b 48 31 32 30 ] [H12012] [H120
2300: 31 33 5d 20 5b 48 31 32 30 31 34 5d 20 5b 48 31 13] [H12014] [H1
2310: 32 30 31 35 5d 20 5b 48 31 32 30 31 39 5d 0a 2a 2015] [H12019].*
2320: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c /.int sqlite3_cl
2330: 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a ose(sqlite3 *);.
2340: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 ./*.** The type
2350: 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 for a callback f
2360: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 unction..** This
2370: 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 is legacy and d
2380: 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 eprecated. It i
2390: 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 s included for h
23a0: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d istorical.** com
23b0: 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 patibility and i
23c0: 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 s not documented
23d0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 ..*/.typedef int
23e0: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 (*sqlite3_callb
23f0: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 ack)(void*,int,c
2400: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a har**, char**);.
2410: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2420: 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 One-Step Query
2430: 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 Execution Interf
2440: 61 63 65 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 ace {H12100} <S1
2450: 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0000>.**.** The
2460: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
2470: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f nterface is a co
2480: 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 nvenient way of
2490: 72 75 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d running one or m
24a0: 6f 72 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ore.** SQL state
24b0: 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20 68 61 ments without ha
24c0: 76 69 6e 67 20 74 6f 20 77 72 69 74 65 20 61 20 ving to write a
24d0: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 lot of C code.
24e0: 54 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 The UTF-8 encode
24f0: 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 d.** SQL stateme
2500: 6e 74 73 20 61 72 65 20 70 61 73 73 65 64 20 69 nts are passed i
2510: 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 n as the second
2520: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
2530: 69 74 65 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 ite3_exec()..**
2540: 54 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 61 The statements a
2550: 72 65 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 re evaluated one
2560: 20 62 79 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 by one until ei
2570: 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 ther an error or
2580: 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 72 75 70 74 .** an interrupt
2590: 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c is encountered,
25a0: 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 79 20 61 or until they a
25b0: 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 re all done. Th
25c0: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 0a e 3rd parameter.
25d0: 2a 2a 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 ** is an optiona
25e0: 6c 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 l callback that
25f0: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 is invoked once
2600: 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 for each row of
2610: 61 6e 79 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 any query.** res
2620: 75 6c 74 73 20 70 72 6f 64 75 63 65 64 20 62 79 ults produced by
2630: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
2640: 6e 74 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 nts. The 5th pa
2650: 72 61 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 rameter tells wh
2660: 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 ere.** to write
2670: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 any error messag
2680: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 es..**.** The er
2690: 72 6f 72 20 6d 65 73 73 61 67 65 20 70 61 73 73 ror message pass
26a0: 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 ed back through
26b0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 the 5th paramete
26c0: 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 r is held.** in
26d0: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
26e0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
26f0: 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f lloc()]. To avo
2700: 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b id a memory leak
2710: 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 ,.** the calling
2720: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
2730: 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 uld call [sqlite
2740: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 3_free()] on any
2750: 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 error.** messag
2760: 65 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 e returned throu
2770: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d gh the 5th param
2780: 65 74 65 72 20 77 68 65 6e 20 69 74 20 68 61 73 eter when it has
2790: 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a finished using.
27a0: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 ** the error mes
27b0: 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 sage..**.** If t
27c0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
27d0: 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 in the 2nd para
27e0: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 meter is NULL or
27f0: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
2800: 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20 .** or a string
2810: 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 containing only
2820: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 20 63 whitespace and c
2830: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f omments, then no
2840: 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e SQL.** statemen
2850: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 ts are evaluated
2860: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 and the databas
2870: 65 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 e is not changed
2880: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
2890: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 te3_exec() inter
28a0: 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e face is implemen
28b0: 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a ted in terms of.
28c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
28d0: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
28e0: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 te3_step()], and
28f0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
2900: 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 ze()]..** The sq
2910: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72 6f 75 lite3_exec() rou
2920: 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e tine does nothin
2930: 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 g to the databas
2940: 65 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 e that cannot be
2950: 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c done.** by [sql
2960: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2970: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 )], [sqlite3_ste
2980: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 p()], and [sqlit
2990: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a e3_finalize()]..
29a0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
29b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
29c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6d 75 lite3_exec()] mu
29d0: 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64 20 61 st be an valid a
29e0: 6e 64 20 6f 70 65 6e 0a 2a 2a 20 5b 64 61 74 61 nd open.** [data
29f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
2a00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 61 74 61 ..**.** The data
2a10: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2a20: 6d 75 73 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 must not be clos
2a30: 65 64 20 77 68 69 6c 65 0a 2a 2a 20 5b 73 71 6c ed while.** [sql
2a40: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 ite3_exec()] is
2a50: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 running..**.** T
2a60: 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 he calling funct
2a70: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 5b ion should use [
2a80: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
2a90: 74 6f 20 66 72 65 65 0a 2a 2a 20 74 68 65 20 6d to free.** the m
2aa0: 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d emory that *errm
2ab0: 73 67 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 sg is left point
2ac0: 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 ing at once the
2ad0: 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 error.** message
2ae0: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 is no longer ne
2af0: 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eded..**.** The
2b00: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 SQL statement te
2b10: 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 xt in the 2nd pa
2b20: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
2b30: 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 6d te3_exec()].** m
2b40: 75 73 74 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 ust remain uncha
2b50: 6e 67 65 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 nged while [sqli
2b60: 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 te3_exec()] is r
2b70: 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 unning..**.** Re
2b80: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
2b90: 48 31 32 31 30 31 5d 20 5b 48 31 32 31 30 32 5d H12101] [H12102]
2ba0: 20 5b 48 31 32 31 30 34 5d 20 5b 48 31 32 31 30 [H12104] [H1210
2bb0: 35 5d 20 5b 48 31 32 31 30 37 5d 20 5b 48 31 32 5] [H12107] [H12
2bc0: 31 31 30 5d 20 5b 48 31 32 31 31 33 5d 20 5b 48 110] [H12113] [H
2bd0: 31 32 31 31 36 5d 0a 2a 2a 20 5b 48 31 32 31 31 12116].** [H1211
2be0: 39 5d 20 5b 48 31 32 31 32 32 5d 20 5b 48 31 32 9] [H12122] [H12
2bf0: 31 32 35 5d 20 5b 48 31 32 31 33 31 5d 20 5b 48 125] [H12131] [H
2c00: 31 32 31 33 34 5d 20 5b 48 31 32 31 33 37 5d 20 12134] [H12137]
2c10: 5b 48 31 32 31 33 38 5d 0a 2a 2f 0a 69 6e 74 20 [H12138].*/.int
2c20: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 sqlite3_exec(.
2c30: 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 sqlite3*,
2c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2c50: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e /* An
2c60: 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a open database *
2c70: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
2c80: 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 sql,
2c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
2ca0: 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c * SQL to be eval
2cb0: 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 uated */. int (
2cc0: 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a *callback)(void*
2cd0: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 ,int,char**,char
2ce0: 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 **), /* Callbac
2cf0: 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 k function */.
2d00: 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 void *,
2d10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2d20: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 /* 1s
2d30: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 t argument to ca
2d40: 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 llback */. char
2d50: 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 **errmsg
2d60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2d70: 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 /* Error
2d80: 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 msg written here
2d90: 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
2da0: 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 PI3REF: Result C
2db0: 6f 64 65 73 20 7b 48 31 30 32 31 30 7d 20 3c 53 odes {H10210} <S
2dc0: 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 10700>.** KEYWOR
2dd0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 DS: SQLITE_OK {e
2de0: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f rror code} {erro
2df0: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 r codes}.** KEYW
2e00: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f ORDS: {result co
2e10: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 de} {result code
2e20: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 s}.**.** Many SQ
2e30: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 Lite functions r
2e40: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 eturn an integer
2e50: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f result code fro
2e60: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a m the set shown.
2e70: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72 ** here in order
2e80: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75 to indicates su
2e90: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 ccess or failure
2ea0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f ..**.** New erro
2eb0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 r codes may be a
2ec0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 dded in future v
2ed0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
2ee0: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 e..**.** See als
2ef0: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 o: [SQLITE_IOERR
2f00: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 _READ | extended
2f10: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a result codes].*
2f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2f30: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 _OK 0
2f40: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 /* Successful
2f50: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 result */./* beg
2f60: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d inning-of-error-
2f70: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 codes */.#define
2f80: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 SQLITE_ERROR
2f90: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 1 /* SQL
2fa0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 error or missing
2fb0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 database */.#de
2fc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
2fd0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 RNAL 2 /*
2fe0: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 Internal logic e
2ff0: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a rror in SQLite *
3000: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3010: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 _PERM 3
3020: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d /* Access perm
3030: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f ission denied */
3040: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3050: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 ABORT 4
3060: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 /* Callback rou
3070: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 tine requested a
3080: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 n abort */.#defi
3090: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 ne SQLITE_BUSY
30a0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 5 /* Th
30b0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
30c0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 is locked */.#de
30d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
30e0: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 ED 6 /*
30f0: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 A table in the d
3100: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 atabase is locke
3110: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
3120: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 ITE_NOMEM
3130: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 7 /* A malloc
3140: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 () failed */.#de
3150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
3160: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 ONLY 8 /*
3170: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 Attempt to write
3180: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 a readonly data
3190: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 base */.#define
31a0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
31b0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 9 /* Opera
31c0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 tion terminated
31d0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 by sqlite3_inter
31e0: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 rupt()*/.#define
31f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 SQLITE_IOERR
3200: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 10 /* Some
3210: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f kind of disk I/
3220: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 O error occurred
3230: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
3240: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 TE_CORRUPT 1
3250: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 1 /* The datab
3260: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 ase disk image i
3270: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 s malformed */.#
3280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
3290: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f TFOUND 12 /
32a0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c * NOT USED. Tabl
32b0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 e or record not
32c0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 found */.#define
32d0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 SQLITE_FULL
32e0: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 13 /* Inse
32f0: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 rtion failed bec
3300: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 ause database is
3310: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 full */.#define
3320: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e SQLITE_CANTOPEN
3330: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 14 /* Unab
3340: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 le to open the d
3350: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a atabase file */.
3360: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 #define SQLITE_P
3370: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 ROTOCOL 15
3380: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 /* NOT USED. Dat
3390: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f abase lock proto
33a0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 col error */.#de
33b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 fine SQLITE_EMPT
33c0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 Y 16 /*
33d0: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 Database is empt
33e0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
33f0: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 ITE_SCHEMA
3400: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 17 /* The data
3410: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e base schema chan
3420: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ged */.#define S
3430: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 QLITE_TOOBIG
3440: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 18 /* String
3450: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 or BLOB exceeds
3460: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 size limit */.#
3470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
3480: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f NSTRAINT 19 /
3490: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 * Abort due to c
34a0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 onstraint violat
34b0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ion */.#define S
34c0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 QLITE_MISMATCH
34d0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 20 /* Data t
34e0: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a ype mismatch */.
34f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
3500: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 ISUSE 21
3510: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 /* Library used
3520: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 incorrectly */.#
3530: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
3540: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f LFS 22 /
3550: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 * Uses OS featur
3560: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 es not supported
3570: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 on host */.#def
3580: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 ine SQLITE_AUTH
3590: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 23 /* A
35a0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e uthorization den
35b0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ied */.#define S
35c0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 QLITE_FORMAT
35d0: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 24 /* Auxili
35e0: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 ary database for
35f0: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 mat error */.#de
3600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 fine SQLITE_RANG
3610: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 E 25 /*
3620: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 2nd parameter to
3630: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 sqlite3_bind ou
3640: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 t of range */.#d
3650: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 efine SQLITE_NOT
3660: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a ADB 26 /*
3670: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 File opened tha
3680: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 t is not a datab
3690: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 ase file */.#def
36a0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 ine SQLITE_ROW
36b0: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 100 /* s
36c0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 qlite3_step() ha
36d0: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 s another row re
36e0: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ady */.#define S
36f0: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 QLITE_DONE
3700: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 101 /* sqlite
3710: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 3_step() has fin
3720: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 ished executing
3730: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 */./* end-of-err
3740: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a or-codes */../*.
3750: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 ** CAPI3REF: Ext
3760: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 ended Result Cod
3770: 65 73 20 7b 48 31 30 32 32 30 7d 20 3c 53 31 30 es {H10220} <S10
3780: 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 700>.** KEYWORDS
3790: 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f : {extended erro
37a0: 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 r code} {extende
37b0: 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a d error codes}.*
37c0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 * KEYWORDS: {ext
37d0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
37e0: 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 e} {extended res
37f0: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a ult codes}.**.**
3800: 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 In its default
3810: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 configuration, S
3820: 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e QLite API routin
3830: 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 es return one of
3840: 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 26 integer.** [
3850: 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 SQLITE_OK | resu
3860: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 lt codes]. Howe
3870: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 ver, experience
3880: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d has shown that m
3890: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 any of.** these
38a0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
38b0: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 too coarse-grai
38c0: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f ned. They do no
38d0: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 t provide as.**
38e0: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e much information
38f0: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 about problems
3900: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d as programmers m
3910: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 ight like. In a
3920: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 n effort to.** a
3930: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 ddress this, new
3940: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 er versions of S
3950: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 QLite (version 3
3960: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 .3.8 and later)
3970: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f include.** suppo
3980: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 rt for additiona
3990: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 l result codes t
39a0: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 hat provide more
39b0: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d detailed inform
39c0: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 ation.** about e
39d0: 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e rrors. The exten
39e0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
39f0: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 are enabled or
3a00: 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 disabled.** on a
3a10: 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f per database co
3a20: 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 nnection basis u
3a30: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c sing the.** [sql
3a40: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 ite3_extended_re
3a50: 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 sult_codes()] AP
3a60: 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 I..**.** Some of
3a70: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 the available e
3a80: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
3a90: 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 odes are listed
3aa0: 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 here..** One may
3ab0: 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 expect the numb
3ac0: 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 er of extended r
3ad0: 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c esult codes will
3ae0: 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 be expand.** ov
3af0: 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 er time. Softwa
3b00: 72 65 20 74 68 61 74 20 75 73 65 73 20 65 78 74 re that uses ext
3b10: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
3b20: 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 es should expect
3b30: 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 .** to see new r
3b40: 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 esult codes in f
3b50: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
3b60: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
3b70: 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 The SQLITE_OK re
3b80: 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e sult code will n
3b90: 65 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 ever be extended
3ba0: 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 . It will alway
3bb0: 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 s.** be exactly
3bc0: 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 zero..*/.#define
3bd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 SQLITE_IOERR_RE
3be0: 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AD
3bf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
3c00: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
3c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f SQLITE_IOERR_SHO
3c20: 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 RT_READ (
3c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
3c40: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
3c50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 QLITE_IOERR_WRIT
3c60: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 E (S
3c70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 QLITE_IOERR | (3
3c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
3c90: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 LITE_IOERR_FSYNC
3ca0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
3cb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c LITE_IOERR | (4<
3cc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
3cd0: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 ITE_IOERR_DIR_FS
3ce0: 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c YNC (SQL
3cf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c ITE_IOERR | (5<<
3d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
3d10: 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 TE_IOERR_TRUNCAT
3d20: 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 E (SQLI
3d30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 TE_IOERR | (6<<8
3d40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
3d50: 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 E_IOERR_FSTAT
3d60: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
3d70: 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 E_IOERR | (7<<8)
3d80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
3d90: 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 _IOERR_UNLOCK
3da0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
3db0: 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 _IOERR | (8<<8))
3dc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3dd0: 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 IOERR_RDLOCK
3de0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
3df0: 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a IOERR | (9<<8)).
3e00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3e10: 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 OERR_DELETE
3e20: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3e30: 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a OERR | (10<<8)).
3e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3e50: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 OERR_BLOCKED
3e60: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3e70: 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a OERR | (11<<8)).
3e80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3e90: 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 OERR_NOMEM
3ea0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3eb0: 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a OERR | (12<<8)).
3ec0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3ed0: 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 OERR_ACCESS
3ee0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3ef0: 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a OERR | (13<<8)).
3f00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3f10: 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 OERR_CHECKRESERV
3f20: 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 EDLOCK (SQLITE_I
3f30: 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a OERR | (14<<8)).
3f40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3f50: 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 OERR_LOCK
3f60: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3f70: 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a OERR | (15<<8)).
3f80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3f90: 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 OERR_CLOSE
3fa0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3fb0: 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a OERR | (16<<8)).
3fc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3fd0: 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 OERR_DIR_CLOSE
3fe0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3ff0: 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a OERR | (17<<8)).
4000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
4010: 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 OCKED_SHAREDCACH
4020: 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c E (SQLITE_L
4030: 4f 43 4b 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 OCKED | (1<<8) )
4040: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
4050: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 : Flags For File
4060: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 Open Operations
4070: 20 7b 48 31 30 32 33 30 7d 20 3c 48 31 31 31 32 {H10230} <H1112
4080: 30 3e 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 0> <H12700>.**.*
4090: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 * These bit valu
40a0: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 es are intended
40b0: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a for use in the.*
40c0: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 * 3rd parameter
40d0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
40e0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 open_v2()] inter
40f0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 face and.** in t
4100: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
4110: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 to the xOpen me
4120: 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b thod of the.** [
4130: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
4140: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ect..*/.#define
4150: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
4160: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 ONLY 0x0
4170: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 0000001.#define
4180: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
4190: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 WRITE 0x0
41a0: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 0000002.#define
41b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
41c0: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 TE 0x0
41d0: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 0000004.#define
41e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
41f0: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 TEONCLOSE 0x0
4200: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 0000008.#define
4210: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
4220: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 USIVE 0x0
4230: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 0000010.#define
4240: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e SQLITE_OPEN_MAIN
4250: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 _DB 0x0
4260: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 0000100.#define
4270: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
4280: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 _DB 0x0
4290: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 0000200.#define
42a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e SQLITE_OPEN_TRAN
42b0: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 SIENT_DB 0x0
42c0: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 0000400.#define
42d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e SQLITE_OPEN_MAIN
42e0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 _JOURNAL 0x0
42f0: 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 0000800.#define
4300: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
4310: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 _JOURNAL 0x0
4320: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 0001000.#define
4330: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a SQLITE_OPEN_SUBJ
4340: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 OURNAL 0x0
4350: 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 0002000.#define
4360: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 SQLITE_OPEN_MAST
4370: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 ER_JOURNAL 0x0
4380: 30 30 30 34 30 30 30 0a 23 64 65 66 69 6e 65 20 0004000.#define
4390: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
43a0: 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 TEX 0x0
43b0: 30 30 30 38 30 30 30 0a 23 64 65 66 69 6e 65 20 0008000.#define
43c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c SQLITE_OPEN_FULL
43d0: 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 MUTEX 0x0
43e0: 30 30 31 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 0010000../*.** C
43f0: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 API3REF: Device
4400: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 Characteristics
4410: 7b 48 31 30 32 34 30 7d 20 3c 48 31 31 31 32 30 {H10240} <H11120
4420: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 >.**.** The xDev
4430: 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 iceCapabilities
4440: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 method of the [s
4450: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
4460: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 s].** object ret
4470: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 urns an integer
4480: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f which is a vecto
4490: 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a r of the these.*
44a0: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 * bit values exp
44b0: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 ressing I/O char
44c0: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 acteristics of t
44d0: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a he mass storage.
44e0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 ** device that h
44f0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 olds the file th
4500: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f at the [sqlite3_
4510: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 io_methods].** r
4520: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 efers to..**.**
4530: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
4540: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
4550: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 means that all
4560: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 writes of.** any
4570: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 size are atomic
4580: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
4590: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 CAP_ATOMICnnn va
45a0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 lues.** mean tha
45b0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 t writes of bloc
45c0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 ks that are nnn
45d0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e bytes in size an
45e0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 d.** are aligned
45f0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 to an address w
4600: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 hich is an integ
4610: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a er multiple of.*
4620: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 * nnn are atomic
4630: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
4640: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
4650: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 value means.** t
4660: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 hat when data is
4670: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 appended to a f
4680: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 ile, the data is
4690: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 appended.** fir
46a0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 st then the size
46b0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 of the file is
46c0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 extended, never
46d0: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 the other.** way
46e0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 around. The SQ
46f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
4700: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d NTIAL property m
4710: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 eans that.** inf
4720: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 ormation is writ
4730: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 ten to disk in t
4740: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 he same order as
4750: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 calls.** to xWr
4760: 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e ite()..*/.#defin
4770: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4780: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 TOMIC 0
4790: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e x00000001.#defin
47a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
47b0: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 TOMIC512 0
47c0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e x00000002.#defin
47d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
47e0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 TOMIC1K 0
47f0: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e x00000004.#defin
4800: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4810: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 TOMIC2K 0
4820: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e x00000008.#defin
4830: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4840: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 TOMIC4K 0
4850: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e x00000010.#defin
4860: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4870: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 TOMIC8K 0
4880: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e x00000020.#defin
4890: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
48a0: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 TOMIC16K 0
48b0: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e x00000040.#defin
48c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
48d0: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 TOMIC32K 0
48e0: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e x00000080.#defin
48f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4900: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 TOMIC64K 0
4910: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e x00000100.#defin
4920: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
4930: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 AFE_APPEND 0
4940: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e x00000200.#defin
4950: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
4960: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 EQUENTIAL 0
4970: 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a x00000400../*.**
4980: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 CAPI3REF: File
4990: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b Locking Levels {
49a0: 48 31 30 32 35 30 7d 20 3c 48 31 31 31 32 30 3e H10250} <H11120>
49b0: 20 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 <H11310>.**.**
49c0: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 SQLite uses one
49d0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 of these integer
49e0: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 values as the s
49f0: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e econd.** argumen
4a00: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 t to calls it ma
4a10: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b kes to the xLock
4a20: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 () and xUnlock()
4a30: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 methods.** of a
4a40: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 n [sqlite3_io_me
4a50: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a thods] object..*
4a60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4a70: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 _LOCK_NONE
4a80: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
4a90: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
4aa0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
4ab0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 e SQLITE_LOCK_RE
4ac0: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 SERVED 2.#d
4ad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
4ae0: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 K_PENDING
4af0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
4b00: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 _LOCK_EXCLUSIVE
4b10: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 4../*.** CAP
4b20: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 I3REF: Synchroni
4b30: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 zation Type Flag
4b40: 73 20 7b 48 31 30 32 36 30 7d 20 3c 48 31 31 31 s {H10260} <H111
4b50: 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 20>.**.** When S
4b60: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 QLite invokes th
4b70: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 e xSync() method
4b80: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 of an.** [sqlit
4b90: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
4ba0: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 bject it uses a
4bb0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a combination of.*
4bc0: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 * these integer
4bd0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 values as the se
4be0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a cond argument..*
4bf0: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 *.** When the SQ
4c00: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e LITE_SYNC_DATAON
4c10: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c LY flag is used,
4c20: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 it means that t
4c30: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 he.** sync opera
4c40: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 tion only needs
4c50: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f to flush data to
4c60: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 mass storage.
4c70: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 Inode.** informa
4c80: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 tion need not be
4c90: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 flushed. If the
4ca0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 lower four bits
4cb0: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 of the flag.**
4cc0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e equal SQLITE_SYN
4cd0: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d C_NORMAL, that m
4ce0: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d eans to use norm
4cf0: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e al fsync() seman
4d00: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 tics..** If the
4d10: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 lower four bits
4d20: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e equal SQLITE_SYN
4d30: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 C_FULL, that mea
4d40: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 ns.** to use Mac
4d50: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c OS X style full
4d60: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 sync instead of
4d70: 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 fsync()..*/.#def
4d80: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ine SQLITE_SYNC_
4d90: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 NORMAL 0x
4da0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 00002.#define SQ
4db0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 LITE_SYNC_FULL
4dc0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 0x00003.
4dd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
4de0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 YNC_DATAONLY
4df0: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 0x00010../*.**
4e00: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e CAPI3REF: OS In
4e10: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c terface Open Fil
4e20: 65 20 48 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 e Handle {H11110
4e30: 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a } <S20110>.**.**
4e40: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c An [sqlite3_fil
4e50: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 e] object repres
4e60: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c ents an open fil
4e70: 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 e in the OS.** i
4e80: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20 nterface layer.
4e90: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 Individual OS i
4ea0: 6e 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 nterface impleme
4eb0: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a ntations will.**
4ec0: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 want to subclas
4ed0: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 s this object by
4ee0: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 appending addit
4ef0: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 ional fields.**
4f00: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 for their own us
4f10: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 e. The pMethods
4f20: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e entry is a poin
4f30: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 ter to an.** [sq
4f40: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
4f50: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 ] object that de
4f60: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f fines methods fo
4f70: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 r performing.**
4f80: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f I/O operations o
4f90: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e n the open file.
4fa0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
4fb0: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 ct sqlite3_file
4fc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 sqlite3_file;.st
4fd0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c ruct sqlite3_fil
4fe0: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 e {. const stru
4ff0: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ct sqlite3_io_me
5000: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b thods *pMethods;
5010: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 /* Methods for
5020: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f an open file */
5030: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
5040: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
5050: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d e File Virtual M
5060: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 ethods Object {H
5070: 31 31 31 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 11120} <S20110>.
5080: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 **.** Every file
5090: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b opened by the [
50a0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 sqlite3_vfs] xOp
50b0: 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 en method popula
50c0: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 tes an.** [sqlit
50d0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 e3_file] object
50e0: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e (or, more common
50f0: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f ly, a subclass o
5100: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
5110: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 3_file] object)
5120: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 with a pointer t
5130: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
5140: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a this object..**
5150: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 This object def
5160: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 ines the methods
5170: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d used to perform
5180: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 various operati
5190: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 ons.** against t
51a0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 he open file rep
51b0: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 resented by the
51c0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
51d0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 bject..**.** The
51e0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
51f0: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 to xSync may be
5200: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 one of [SQLITE_S
5210: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a YNC_NORMAL] or.*
5220: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 * [SQLITE_SYNC_F
5230: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 ULL]. The first
5240: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e choice is the n
5250: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a ormal fsync()..*
5260: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f * The second cho
5270: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 ice is a Mac OS
5280: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 X style fullsync
5290: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 . The [SQLITE_S
52a0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a YNC_DATAONLY].**
52b0: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 flag may be ORe
52c0: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 d in to indicate
52d0: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 that only the d
52e0: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a ata of the file.
52f0: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 ** and not its i
5300: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 node needs to be
5310: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 synced..**.** T
5320: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 he integer value
5330: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 s to xLock() and
5340: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f xUnlock() are o
5350: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a ne of.** <ul>.**
5360: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
5370: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 CK_NONE],.** <li
5380: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 > [SQLITE_LOCK_S
5390: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 HARED],.** <li>
53a0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 [SQLITE_LOCK_RES
53b0: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 ERVED],.** <li>
53c0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e [SQLITE_LOCK_PEN
53d0: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 DING], or.** <li
53e0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 > [SQLITE_LOCK_E
53f0: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f XCLUSIVE]..** </
5400: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 ul>.** xLock() i
5410: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 ncreases the loc
5420: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 k. xUnlock() dec
5430: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e reases the lock.
5440: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 .** The xCheckRe
5450: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 servedLock() met
5460: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 hod checks wheth
5470: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 er any database
5480: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 connection,.** e
5490: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 ither in this pr
54a0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 ocess or in some
54b0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 other process,
54c0: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 is holding a RES
54d0: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e ERVED,.** PENDIN
54e0: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 G, or EXCLUSIVE
54f0: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 lock on the file
5500: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 . It returns tr
5510: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 ue.** if such a
5520: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 lock exists and
5530: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e false otherwise.
5540: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 .**.** The xFile
5550: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 Control() method
5560: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e is a generic in
5570: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c terface that all
5580: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 ows custom.** VF
5590: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
55a0: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f s to directly co
55b0: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 ntrol an open fi
55c0: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 le using the.**
55d0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
55e0: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 ntrol()] interfa
55f0: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ce. The second
5600: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 "op" argument is
5610: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f an.** integer o
5620: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 pcode. The thir
5630: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 d argument is a
5640: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 generic pointer
5650: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 intended to.** p
5660: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 oint to a struct
5670: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e ure that may con
5680: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f tain arguments o
5690: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 r space in which
56a0: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 to.** write ret
56b0: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 urn values. Pot
56c0: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 ential uses for
56d0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d xFileControl() m
56e0: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 ight be.** funct
56f0: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 ions to enable b
5700: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 locking locks wi
5710: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 th timeouts, to
5720: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f change the.** lo
5730: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 cking strategy (
5740: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 for example to u
5750: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b se dot-file lock
5760: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a s), to inquire.*
5770: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 * about the stat
5780: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 us of a lock, or
5790: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 to break stale
57a0: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 locks. The SQLi
57b0: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 te.** core reser
57c0: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 ves all opcodes
57d0: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f less than 100 fo
57e0: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a r its own use..*
57f0: 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 * A [SQLITE_FCNT
5800: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 L_LOCKSTATE | li
5810: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c st of opcodes] l
5820: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 ess than 100 is
5830: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 available..** Ap
5840: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
5850: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 define a custom
5860: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
5870: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f hod should use o
5880: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 pcodes.** greate
5890: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 r than 100 to av
58a0: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a oid conflicts..*
58b0: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 *.** The xSector
58c0: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 Size() method re
58d0: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 turns the sector
58e0: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 size of the.**
58f0: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 device that unde
5900: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 rlies the file.
5910: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 The sector size
5920: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d is the.** minim
5930: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 um write that ca
5940: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 n be performed w
5950: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e ithout disturbin
5960: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 g.** other bytes
5970: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 in the file. T
5980: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 he xDeviceCharac
5990: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d teristics().** m
59a0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 ethod returns a
59b0: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 bit vector descr
59c0: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 ibing behaviors
59d0: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c of the.** underl
59e0: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a ying device:.**.
59f0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
5a00: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
5a10: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 OMIC].** <li> [S
5a20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5a30: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC512].** <li> [
5a40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5a50: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC1K].** <li> [
5a60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5a70: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC2K].** <li> [
5a80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5a90: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC4K].** <li> [
5aa0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5ab0: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC8K].** <li> [
5ac0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5ad0: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC16K].** <li>
5ae0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
5af0: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e OMIC32K].** <li>
5b00: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
5b10: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 TOMIC64K].** <li
5b20: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
5b30: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 SAFE_APPEND].**
5b40: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
5b50: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a AP_SEQUENTIAL].*
5b60: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 * </ul>.**.** Th
5b70: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
5b80: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d TOMIC property m
5b90: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 eans that all wr
5ba0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 ites of.** any s
5bb0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 ize are atomic.
5bc0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
5bd0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 P_ATOMICnnn valu
5be0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 es.** mean that
5bf0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 writes of blocks
5c00: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 that are nnn by
5c10: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a tes in size and.
5c20: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 ** are aligned t
5c30: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 o an address whi
5c40: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ch is an integer
5c50: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 multiple of.**
5c60: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 nnn are atomic.
5c70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
5c80: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 P_SAFE_APPEND va
5c90: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 lue means.** tha
5ca0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 t when data is a
5cb0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c ppended to a fil
5cc0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 e, the data is a
5cd0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 ppended.** first
5ce0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f then the size o
5cf0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 f the file is ex
5d00: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 tended, never th
5d10: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 e other.** way a
5d20: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 round. The SQLI
5d30: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
5d40: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 IAL property mea
5d50: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 ns that.** infor
5d60: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 mation is writte
5d70: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 n to disk in the
5d80: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 same order as c
5d90: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 alls.** to xWrit
5da0: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 e()..**.** If xR
5db0: 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 ead() returns SQ
5dc0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 LITE_IOERR_SHORT
5dd0: 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c _READ it must al
5de0: 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 so fill.** in th
5df0: 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e e unread portion
5e00: 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 s of the buffer
5e10: 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 with zeros. A V
5e20: 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 FS that.** fails
5e30: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 to zero-fill sh
5e40: 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 ort reads might
5e50: 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 seem to work. H
5e60: 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 owever,.** failu
5e70: 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 re to zero-fill
5e80: 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c short reads will
5e90: 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 eventually lead
5ea0: 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 to.** database
5eb0: 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 corruption..*/.t
5ec0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
5ed0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
5ee0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 sqlite3_io_meth
5ef0: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ods;.struct sqli
5f00: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b te3_io_methods {
5f10: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b . int iVersion;
5f20: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 . int (*xClose)
5f30: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
5f40: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 . int (*xRead)(
5f50: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 sqlite3_file*, v
5f60: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 oid*, int iAmt,
5f70: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f sqlite3_int64 iO
5f80: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 fst);. int (*xW
5f90: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 rite)(sqlite3_fi
5fa0: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a le*, const void*
5fb0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 , int iAmt, sqli
5fc0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 te3_int64 iOfst)
5fd0: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 ;. int (*xTrunc
5fe0: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ate)(sqlite3_fil
5ff0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
6000: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 4 size);. int (
6010: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f *xSync)(sqlite3_
6020: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 file*, int flags
6030: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 );. int (*xFile
6040: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 Size)(sqlite3_fi
6050: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 le*, sqlite3_int
6060: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 64 *pSize);. in
6070: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 t (*xLock)(sqlit
6080: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a e3_file*, int);.
6090: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 int (*xUnlock)
60a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
60b0: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 int);. int (*xC
60c0: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b heckReservedLock
60d0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
60e0: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a int *pResOut);.
60f0: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e int (*xFileCon
6100: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 trol)(sqlite3_fi
6110: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 le*, int op, voi
6120: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 d *pArg);. int
6130: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 (*xSectorSize)(s
6140: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
6150: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 int (*xDeviceCh
6160: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 aracteristics)(s
6170: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
6180: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d /* Additional m
6190: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 ethods may be ad
61a0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
61b0: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a leases */.};../*
61c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 .** CAPI3REF: St
61d0: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 andard File Cont
61e0: 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b 48 31 31 rol Opcodes {H11
61f0: 33 31 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 310} <S30800>.**
6200: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 .** These intege
6210: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 r constants are
6220: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 opcodes for the
6230: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
6240: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 hod.** of the [s
6250: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
6260: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f s] object and fo
6270: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 r the [sqlite3_f
6280: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a ile_control()].*
6290: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a * interface..**.
62a0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
62b0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 CNTL_LOCKSTATE]
62c0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 opcode is used f
62d0: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 or debugging. T
62e0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 his.** opcode ca
62f0: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f uses the xFileCo
6300: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 ntrol method to
6310: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e write the curren
6320: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 t state of.** th
6330: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b e lock (one of [
6340: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 SQLITE_LOCK_NONE
6350: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ], [SQLITE_LOCK_
6360: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c SHARED],.** [SQL
6370: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 ITE_LOCK_RESERVE
6380: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b D], [SQLITE_LOCK
6390: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 _PENDING], or [S
63a0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
63b0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 SIVE]).** into a
63c0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 n integer that t
63d0: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 he pArg argument
63e0: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 points to. This
63f0: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 capability.** i
6400: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 s used during te
6410: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e sting and only n
6420: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f eeds to be suppo
6430: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 rted when SQLITE
6440: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 _TEST.** is defi
6450: 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ned..*/.#define
6460: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 SQLITE_FCNTL_LOC
6470: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31 0a KSTATE 1.
6480: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 #define SQLITE_G
6490: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 ET_LOCKPROXYFILE
64a0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
64b0: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 SQLITE_SET_LOCKP
64c0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33 0a ROXYFILE 3.
64d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
64e0: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 AST_ERRNO
64f0: 20 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 4../*.** C
6500: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 API3REF: Mutex H
6510: 61 6e 64 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c andle {H17110} <
6520: 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S20130>.**.** Th
6530: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 e mutex module w
6540: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 ithin SQLite def
6550: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 ines [sqlite3_mu
6560: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a tex] to be an.**
6570: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 abstract type f
6580: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 or a mutex objec
6590: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 t. The SQLite c
65a0: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a ore never looks.
65b0: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e ** at the intern
65c0: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f al representatio
65d0: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 n of an [sqlite3
65e0: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c _mutex]. It onl
65f0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 y.** deals with
6600: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 pointers to the
6610: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 [sqlite3_mutex]
6620: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 object..**.** Mu
6630: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 texes are create
6640: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
6650: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e _mutex_alloc()].
6660: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
6670: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ct sqlite3_mutex
6680: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a sqlite3_mutex;.
6690: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
66a0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 OS Interface Ob
66b0: 6a 65 63 74 20 7b 48 31 31 31 34 30 7d 20 3c 53 ject {H11140} <S
66c0: 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 20100>.**.** An
66d0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
66e0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 sqlite3_vfs obje
66f0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 ct defines the i
6700: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e nterface between
6710: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 .** the SQLite c
6720: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 ore and the unde
6730: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 rlying operating
6740: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 system. The "v
6750: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 fs".** in the na
6760: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 me of the object
6770: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 stands for "vir
6780: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d tual file system
6790: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c "..**.** The val
67a0: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 ue of the iVersi
67b0: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 on field is init
67c0: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 ially 1 but may
67d0: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 be larger in.**
67e0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 future versions
67f0: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 of SQLite. Addi
6800: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 tional fields ma
6810: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f y be appended to
6820: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 this.** object
6830: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f when the iVersio
6840: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 n value is incre
6850: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 ased. Note that
6860: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a the structure.*
6870: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 * of the sqlite3
6880: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e _vfs object chan
6890: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 ges in the trans
68a0: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a action between.*
68b0: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e * SQLite version
68c0: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 3.5.9 and 3.6.0
68d0: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 and yet the iVe
68e0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 rsion field was
68f0: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e not.** modified.
6900: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 .**.** The szOsF
6910: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 ile field is the
6920: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 size of the sub
6930: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 classed [sqlite3
6940: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 _file].** struct
6950: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 ure used by this
6960: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d VFS. mxPathnam
6970: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d e is the maximum
6980: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 length of.** a
6990: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 pathname in this
69a0: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 VFS..**.** Regi
69b0: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 stered sqlite3_v
69c0: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b fs objects are k
69d0: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 ept on a linked
69e0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a list formed by.*
69f0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e * the pNext poin
6a00: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ter. The [sqlit
6a10: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 e3_vfs_register(
6a20: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 )].** and [sqlit
6a30: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 e3_vfs_unregiste
6a40: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 r()] interfaces
6a50: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 manage this list
6a60: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d .** in a thread-
6a70: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b safe way. The [
6a80: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 sqlite3_vfs_find
6a90: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a ()] interface.**
6aa0: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 searches the li
6ab0: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 st. Neither the
6ac0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 application cod
6ad0: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a e nor the VFS.**
6ae0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
6af0: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 should use the p
6b00: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a Next pointer..**
6b10: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 .** The pNext fi
6b20: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 eld is the only
6b30: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c field in the sql
6b40: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 ite3_vfs.** stru
6b50: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 cture that SQLit
6b60: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 e will ever modi
6b70: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c fy. SQLite will
6b80: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 only access.**
6b90: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 or modify this f
6ba0: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 ield while holdi
6bb0: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 ng a particular
6bc0: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a static mutex..**
6bd0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
6be0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f should never mo
6bf0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 dify anything wi
6c00: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 thin the sqlite3
6c10: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f _vfs.** object o
6c20: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 nce the object h
6c30: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 as been register
6c40: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e ed..**.** The zN
6c50: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 ame field holds
6c60: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
6c70: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 VFS module. The
6c80: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 name must.** be
6c90: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 unique across a
6ca0: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a ll VFS modules..
6cb0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c **.** SQLite wil
6cc0: 6c 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 l guarantee that
6cd0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 the zFilename p
6ce0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 arameter to xOpe
6cf0: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 n.** is either a
6d00: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 NULL pointer or
6d10: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 string obtained
6d20: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 .** from xFullPa
6d30: 74 68 6e 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 thname(). SQLit
6d40: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e e further guaran
6d50: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 tees that.** the
6d60: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 string will be
6d70: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e valid and unchan
6d80: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 ged until xClose
6d90: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e () is.** called.
6da0: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 Because of the
6db0: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 73 previous sentens
6dc0: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 e,.** the [sqlit
6dd0: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 e3_file] can saf
6de0: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e ely store a poin
6df0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 ter to the.** fi
6e00: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 lename if it nee
6e10: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 ds to remember t
6e20: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 he filename for
6e30: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 some reason..**
6e40: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 If the zFilename
6e50: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 78 4f parameter is xO
6e60: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f pen is a NULL po
6e70: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e inter then xOpen
6e80: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 69 74 65 20 .** must invite
6e90: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 its own temporar
6ea0: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 y name for the f
6eb0: 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 72 20 74 ile. Whenever t
6ec0: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 he .** xFilename
6ed0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 parameter is NU
6ee0: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 LL it will also
6ef0: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
6f00: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 the.** flags pa
6f10: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 rameter will inc
6f20: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 lude [SQLITE_OPE
6f30: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
6f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
6f50: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f s argument to xO
6f60: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 pen() includes a
6f70: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a ll bits set in.*
6f80: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 * the flags argu
6f90: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
6fa0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 _open_v2()]. Or
6fb0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 if [sqlite3_ope
6fc0: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 n()].** or [sqli
6fd0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 te3_open16()] is
6fe0: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 used, then flag
6ff0: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 s includes at le
7000: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f ast.** [SQLITE_O
7010: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c PEN_READWRITE] |
7020: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
7030: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f EATE]. .** If xO
7040: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 pen() opens a fi
7050: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 le read-only the
7060: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 n it sets *pOutF
7070: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 lags to.** inclu
7080: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f de [SQLITE_OPEN_
7090: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 READONLY]. Othe
70a0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 r bits in *pOutF
70b0: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e lags may be set.
70c0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 .**.** SQLite wi
70d0: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 ll also add one
70e0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
70f0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f flags to the xO
7100: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 pen().** call, d
7110: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
7120: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 object being ope
7130: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ned:.**.** <ul>.
7140: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
7150: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a _OPEN_MAIN_DB].*
7160: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
7170: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
7180: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
7190: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 ITE_OPEN_TEMP_DB
71a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
71b0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 TE_OPEN_TEMP_JOU
71c0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
71d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e SQLITE_OPEN_TRAN
71e0: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 SIENT_DB].** <li
71f0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
7200: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c SUBJOURNAL].** <
7210: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
7220: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c N_MASTER_JOURNAL
7230: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a ].** </ul>.**.**
7240: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d The file I/O im
7250: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e plementation can
7260: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 use the object
7270: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a type flags to.**
7280: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 change the way
7290: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 it deals with fi
72a0: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c les. For exampl
72b0: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f e, an applicatio
72c0: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e n.** that does n
72d0: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 ot care about cr
72e0: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 ash recovery or
72f0: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d rollback might m
7300: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 ake.** the open
7310: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c of a journal fil
7320: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 e a no-op. Writ
7330: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e es to this journ
7340: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f al would.** also
7350: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 be no-ops, and
7360: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 any attempt to r
7370: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 ead the journal
7380: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 would return.**
7390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f SQLITE_IOERR. O
73a0: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 r the implementa
73b0: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 tion might recog
73c0: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 nize that a data
73d0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c base.** file wil
73e0: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d l be doing page-
73f0: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 aligned sector r
7400: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 eads and writes
7410: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f in a random.** o
7420: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 rder and set up
7430: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 its I/O subsyste
7440: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a m accordingly..*
7450: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 *.** SQLite migh
7460: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f t also add one o
7470: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
7480: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 flags to the xOp
7490: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a en method:.**.**
74a0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 <ul>.** <li> [S
74b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
74c0: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 EONCLOSE].** <li
74d0: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 > [SQLITE_OPEN_E
74e0: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 XCLUSIVE].** </u
74f0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 l>.**.** The [SQ
7500: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
7510: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 ONCLOSE] flag me
7520: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f ans the file sho
7530: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 uld be.** delete
7540: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f d when it is clo
7550: 73 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 sed. The [SQLIT
7560: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
7570: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 LOSE].** will be
7580: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64 set for TEMP d
7590: 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 atabases, journa
75a0: 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f ls and for subjo
75b0: 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 urnals..**.** Th
75c0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 e [SQLITE_OPEN_E
75d0: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 6d XCLUSIVE] flag m
75e0: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 eans the file sh
75f0: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a ould be opened.*
7600: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 * for exclusive
7610: 61 63 63 65 73 73 2e 20 20 54 68 69 73 20 66 6c access. This fl
7620: 61 67 20 69 73 20 73 65 74 20 66 6f 72 20 61 6c ag is set for al
7630: 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74 0a 2a l files except.*
7640: 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 * for the main d
7650: 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a atabase file..**
7660: 0a 2a 2a 20 41 74 20 6c 65 61 73 74 20 73 7a 4f .** At least szO
7670: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d sFile bytes of m
7680: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 emory are alloca
7690: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a ted by SQLite.**
76a0: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 to hold the [s
76b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 qlite3_file] str
76c0: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 ucture passed as
76d0: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 the third.** ar
76e0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e gument to xOpen.
76f0: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 The xOpen meth
7700: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 od does not have
7710: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 to.** allocate
7720: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 the structure; i
7730: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 t should just fi
7740: 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 0a 2a 2a 20 ll it in..**.**
7750: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 The flags argume
7760: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 nt to xAccess()
7770: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 may be [SQLITE_A
7780: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a CCESS_EXISTS].**
7790: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 to test for the
77a0: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 existence of a
77b0: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 file, or [SQLITE
77c0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
77d0: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 E] to.** test wh
77e0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 ether a file is
77f0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 readable and wri
7800: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 table, or [SQLIT
7810: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a E_ACCESS_READ].*
7820: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 * to test whethe
7830: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c r a file is at l
7840: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 east readable.
7850: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 The file can be
7860: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e a.** directory.
7870: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 .**.** SQLite wi
7880: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 ll always alloca
7890: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 te at least mxPa
78a0: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 thname+1 bytes f
78b0: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 or the.** output
78c0: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 buffer xFullPat
78d0: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 hname. The exac
78e0: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 t size of the ou
78f0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 tput buffer.** i
7900: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 s also passed as
7910: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 a parameter to
7920: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 both methods. I
7930: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 f the output buf
7940: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 fer.** is not la
7950: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c rge enough, [SQL
7960: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 ITE_CANTOPEN] sh
7970: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 ould be returned
7980: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a . Since this is.
7990: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 ** handled as a
79a0: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 fatal error by S
79b0: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 QLite, vfs imple
79c0: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c mentations shoul
79d0: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f d endeavor.** to
79e0: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 prevent this by
79f0: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e setting mxPathn
7a00: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 ame to a suffici
7a10: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 ently large valu
7a20: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 e..**.** The xRa
7a30: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 ndomness(), xSle
7a40: 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 ep(), and xCurre
7a50: 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 ntTime() interfa
7a60: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 ces.** are not s
7a70: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f trictly a part o
7a80: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d f the filesystem
7a90: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a , but they are.*
7aa0: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 * included in th
7ab0: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 e VFS structure
7ac0: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 for completeness
7ad0: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d ..** The xRandom
7ae0: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 ness() function
7af0: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 attempts to retu
7b00: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a rn nBytes bytes.
7b10: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 ** of good-quali
7b20: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e ty randomness in
7b30: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 to zOut. The re
7b40: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a turn value is.**
7b50: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 the actual numb
7b60: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 er of bytes of r
7b70: 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e andomness obtain
7b80: 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 ed..** The xSlee
7b90: 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 p() method cause
7ba0: 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 s the calling th
7bb0: 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f read to sleep fo
7bc0: 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 r at.** least th
7bd0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 e number of micr
7be0: 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 oseconds given.
7bf0: 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d The xCurrentTim
7c00: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 e().** method re
7c10: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 turns a Julian D
7c20: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 ay Number for th
7c30: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 e current date a
7c40: 6e 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74 nd time..**.*/.t
7c50: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
7c60: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 lite3_vfs sqlite
7c70: 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71 3_vfs;.struct sq
7c80: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e lite3_vfs {. in
7c90: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 t iVersion;
7ca0: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 /* Struct
7cb0: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 ure version numb
7cc0: 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 er */. int szOs
7cd0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 File;
7ce0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 /* Size of subc
7cf0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 lassed sqlite3_f
7d00: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 ile */. int mxP
7d10: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 athname;
7d20: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c /* Maximum fil
7d30: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 e pathname lengt
7d40: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 h */. sqlite3_v
7d50: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 fs *pNext;
7d60: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 /* Next register
7d70: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 ed VFS */. cons
7d80: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 t char *zName;
7d90: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 /* Name of
7da0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c this virtual fil
7db0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f e system */. vo
7dc0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 id *pAppData;
7dd0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 /* Pointe
7de0: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e r to application
7df0: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a -specific data *
7e00: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 /. int (*xOpen)
7e10: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
7e20: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
7e30: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c , sqlite3_file*,
7e40: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
7e50: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a int flags, int *
7e60: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e pOutFlags);. in
7e70: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c t (*xDelete)(sql
7e80: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
7e90: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
7ea0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e t syncDir);. in
7eb0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c t (*xAccess)(sql
7ec0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
7ed0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
7ee0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 t flags, int *pR
7ef0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a esOut);. int (*
7f00: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 xFullPathname)(s
7f10: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
7f20: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
7f30: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a int nOut, char *
7f40: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 zOut);. void *(
7f50: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 *xDlOpen)(sqlite
7f60: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
7f70: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a ar *zFilename);.
7f80: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f void (*xDlErro
7f90: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c r)(sqlite3_vfs*,
7fa0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 int nByte, char
7fb0: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f *zErrMsg);. vo
7fc0: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 id (*(*xDlSym)(s
7fd0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 qlite3_vfs*,void
7fe0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
7ff0: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a Symbol))(void);.
8000: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 void (*xDlClos
8010: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
8020: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 void*);. int (
8030: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 *xRandomness)(sq
8040: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 lite3_vfs*, int
8050: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 nByte, char *zOu
8060: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 t);. int (*xSle
8070: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ep)(sqlite3_vfs*
8080: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e , int microsecon
8090: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 ds);. int (*xCu
80a0: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 rrentTime)(sqlit
80b0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a e3_vfs*, double*
80c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c );. int (*xGetL
80d0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 astError)(sqlite
80e0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 3_vfs*, int, cha
80f0: 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 r *);. /* New f
8100: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 ields may be app
8110: 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 ended in figure
8120: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 versions. The i
8130: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c Version. ** val
8140: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e ue will incremen
8150: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 t whenever this
8160: 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a happens. */.};..
8170: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
8180: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 Flags for the xA
8190: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 ccess VFS method
81a0: 20 7b 48 31 31 31 39 30 7d 20 3c 48 31 31 31 34 {H11190} <H1114
81b0: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 0>.**.** These i
81c0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
81d0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 can be used as
81e0: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
81f0: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 ter to.** the xA
8200: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 ccess method of
8210: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d an [sqlite3_vfs]
8220: 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20 object. {END}
8230: 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a They determine.*
8240: 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 * what kind of p
8250: 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 ermissions the x
8260: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 Access method is
8270: 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a looking for..**
8280: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 With SQLITE_ACC
8290: 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 ESS_EXISTS, the
82a0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a xAccess method.*
82b0: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 * simply checks
82c0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 whether the file
82d0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 exists..** With
82e0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
82f0: 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 EADWRITE, the xA
8300: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 ccess method.**
8310: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 checks whether t
8320: 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68 20 he file is both
8330: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 readable and wri
8340: 74 61 62 6c 65 2e 0a 2a 2a 20 57 69 74 68 20 53 table..** With S
8350: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
8360: 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d D, the xAccess m
8370: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 ethod.** checks
8380: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 whether the file
8390: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f is readable..*/
83a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
83b0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 ACCESS_EXISTS
83c0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
83d0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 E_ACCESS_READWRI
83e0: 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c TE 1.#define SQL
83f0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 ITE_ACCESS_READ
8400: 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 2../*.** CA
8410: 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 PI3REF: Initiali
8420: 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 ze The SQLite Li
8430: 62 72 61 72 79 20 7b 48 31 30 31 33 30 7d 20 3c brary {H10130} <
8440: 53 32 30 30 30 30 3e 3c 53 33 30 31 30 30 3e 0a S20000><S30100>.
8450: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
8460: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 3_initialize() r
8470: 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a outine initializ
8480: 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 es the.** SQLite
8490: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 library. The s
84a0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
84b0: 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 ) routine.** dea
84c0: 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 llocates any res
84d0: 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 ources that were
84e0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 allocated by sq
84f0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
8500: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c ()..**.** A call
8510: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 to sqlite3_init
8520: 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 ialize() is an "
8530: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 effective" call
8540: 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 if it is.** the
8550: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 first time sqlit
8560: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
8570: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e is invoked durin
8580: 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f g the lifetime o
8590: 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 f.** the process
85a0: 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 , or if it is th
85b0: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c e first time sql
85c0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
85d0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 ) is invoked.**
85e0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c following a call
85f0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 to sqlite3_shut
8600: 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20 61 6e down(). Only an
8610: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a effective call.
8620: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e ** of sqlite3_in
8630: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 itialize() does
8640: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 any initializati
8650: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 on. All other c
8660: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d alls.** are harm
8670: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a less no-ops..**.
8680: 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 ** Among other t
8690: 68 69 6e 67 73 2c 20 73 71 6c 69 74 65 33 5f 69 hings, sqlite3_i
86a0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 68 61 6c nitialize() shal
86b0: 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 l invoke.** sqli
86c0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 te3_os_init().
86d0: 53 69 6d 69 6c 61 72 6c 79 2c 20 73 71 6c 69 74 Similarly, sqlit
86e0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a e3_shutdown().**
86f0: 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 shall invoke sq
8700: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a lite3_os_end()..
8710: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
8720: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 3_initialize() r
8730: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b outine returns [
8740: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 SQLITE_OK] on su
8750: 63 63 65 73 73 2e 0a 2a 2a 20 49 66 20 66 6f 72 ccess..** If for
8760: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 some reason, sq
8770: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
8780: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 () is unable to
8790: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 initialize.** th
87a0: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 e library (perha
87b0: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 ps it is unable
87c0: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 to allocate a ne
87d0: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 eded resource su
87e0: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 ch.** as a mutex
87f0: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 ) it returns an
8800: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 [error code] oth
8810: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
8820: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 OK]..**.** The s
8830: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
8840: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 e() routine is c
8850: 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 alled internally
8860: 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a by many other.*
8870: 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 * SQLite interfa
8880: 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 ces so that an a
8890: 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c pplication usual
88a0: 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 ly does not need
88b0: 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 to.** invoke sq
88c0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
88d0: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f () directly. Fo
88e0: 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 r example, [sqli
88f0: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 te3_open()].** c
8900: 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 alls sqlite3_ini
8910: 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 tialize() so the
8920: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 SQLite library
8930: 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 will be automati
8940: 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c cally.** initial
8950: 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 ized when [sqlit
8960: 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 e3_open()] is ca
8970: 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e lled if it has n
8980: 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 ot be initialize
8990: 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 48 d.** already. H
89a0: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 owever, if SQLit
89b0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
89c0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f th the [SQLITE_O
89d0: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a MIT_AUTOINIT].**
89e0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
89f0: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 tion, then the a
8a00: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 utomatic calls t
8a10: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 o sqlite3_initia
8a20: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d lize().** are om
8a30: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 itted and the ap
8a40: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 plication must c
8a50: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 all sqlite3_init
8a60: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c ialize() directl
8a70: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 y.** prior to us
8a80: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 ing any other SQ
8a90: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 Lite interface.
8aa0: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 For maximum por
8ab0: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 tability,.** it
8ac0: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 is recommended t
8ad0: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 hat applications
8ae0: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 always invoke s
8af0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
8b00: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 e().** directly
8b10: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 prior to using a
8b20: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ny other SQLite
8b30: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 interface. Futu
8b40: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f re releases.** o
8b50: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 f SQLite may req
8b60: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f uire this. In o
8b70: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
8b80: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 behavior exhibit
8b90: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 ed.** when SQLit
8ba0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
8bb0: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f th [SQLITE_OMIT_
8bc0: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 AUTOINIT] might
8bd0: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 become the.** de
8be0: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 fault behavior i
8bf0: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 n some future re
8c00: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e lease of SQLite.
8c10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
8c20: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 e3_os_init() rou
8c30: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 tine does operat
8c40: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 ing-system speci
8c50: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a fic.** initializ
8c60: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c ation of the SQL
8c70: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 ite library. Th
8c80: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 e sqlite3_os_end
8c90: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e ().** routine un
8ca0: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 does the effect
8cb0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e of sqlite3_os_in
8cc0: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 it(). Typical t
8cd0: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 asks.** performe
8ce0: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 d by these routi
8cf0: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f nes include allo
8d00: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f cation or deallo
8d10: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 cation.** of sta
8d20: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 tic resources, i
8d30: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 nitialization of
8d40: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 global variable
8d50: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 s,.** setting up
8d60: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 a default [sqli
8d70: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c te3_vfs] module,
8d80: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a or setting up.*
8d90: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 * a default conf
8da0: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 iguration using
8db0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
8dc0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 )]..**.** The ap
8dd0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
8de0: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 never invoke ei
8df0: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f ther sqlite3_os_
8e00: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c init().** or sql
8e10: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 ite3_os_end() di
8e20: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 rectly. The app
8e30: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
8e40: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 only invoke.** s
8e50: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
8e60: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f e() and sqlite3_
8e70: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 shutdown(). The
8e80: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
8e90: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
8ea0: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 is called automa
8eb0: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 tically by sqlit
8ec0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
8ed0: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f and.** sqlite3_o
8ee0: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 s_end() is calle
8ef0: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 d by sqlite3_shu
8f00: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 tdown(). Approp
8f10: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 riate.** impleme
8f20: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c ntations for sql
8f30: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 ite3_os_init() a
8f40: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e nd sqlite3_os_en
8f50: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 d().** are built
8f60: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 into SQLite whe
8f70: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 n it is compiled
8f80: 20 66 6f 72 20 75 6e 69 78 2c 20 77 69 6e 64 6f for unix, windo
8f90: 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 ws, or os/2..**
8fa0: 57 68 65 6e 20 62 75 69 6c 74 20 66 6f 72 20 6f When built for o
8fb0: 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 20 28 ther platforms (
8fc0: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 using the [SQLIT
8fd0: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f E_OS_OTHER=1] co
8fe0: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 mpile-time.** op
8ff0: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 tion) the applic
9000: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c ation must suppl
9010: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 y a suitable imp
9020: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a lementation for.
9030: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e ** sqlite3_os_in
9040: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 it() and sqlite3
9050: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 _os_end(). An a
9060: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c pplication-suppl
9070: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 ied.** implement
9080: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 ation of sqlite3
9090: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 _os_init() or sq
90a0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
90b0: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 * must return [S
90c0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
90d0: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 cess and some ot
90e0: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d her [error code]
90f0: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 upon.** failure
9100: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
9110: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 _initialize(void
9120: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 );.int sqlite3_s
9130: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 hutdown(void);.i
9140: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e nt sqlite3_os_in
9150: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 it(void);.int sq
9160: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 lite3_os_end(voi
9170: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 d);../*.** CAPI3
9180: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 REF: Configuring
9190: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 The SQLite Libr
91a0: 61 72 79 20 7b 48 31 34 31 30 30 7d 20 3c 53 32 ary {H14100} <S2
91b0: 30 30 30 30 3e 3c 53 33 30 32 30 30 3e 0a 2a 2a 0000><S30200>.**
91c0: 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
91d0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
91e0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 config() interfa
91f0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 ce is used to ma
9200: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 ke global config
9210: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 uration.** chang
9220: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 es to SQLite in
9230: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 order to tune SQ
9240: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 Lite to the spec
9250: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a ific needs of.**
9260: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
9270: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 . The default c
9280: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 onfiguration is
9290: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
92a0: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 most.** applicat
92b0: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 ions and so this
92c0: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 routine is usua
92d0: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 lly not necessar
92e0: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f y. It is.** pro
92f0: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 vided to support
9300: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f rare applicatio
9310: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 ns with unusual
9320: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 needs..**.** The
9330: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
9340: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e ) interface is n
9350: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 ot threadsafe.
9360: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a The application.
9370: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 ** must insure t
9380: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c hat no other SQL
9390: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 ite interfaces a
93a0: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 re invoked by ot
93b0: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 her.** threads w
93c0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e hile sqlite3_con
93d0: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 fig() is running
93e0: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 . Furthermore,
93f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
9400: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 .** may only be
9410: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f invoked prior to
9420: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c library initial
9430: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a ization using.**
9440: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
9450: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 lize()] or after
9460: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 shutdown by [sq
9470: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
9480: 5d 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 ]..** Note, howe
9490: 76 65 72 2c 20 74 68 61 74 20 73 71 6c 69 74 65 ver, that sqlite
94a0: 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 3_config() can b
94b0: 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 e called as part
94c0: 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 of the.** imple
94d0: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 mentation of an
94e0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
94f0: 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f ned [sqlite3_os_
9500: 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 init()]..**.** T
9510: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
9520: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e t to sqlite3_con
9530: 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 fig() is an inte
9540: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 ger.** [SQLITE_C
9550: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
9560: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 AD | configurati
9570: 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 on option] that
9580: 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 determines.** wh
9590: 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 at property of S
95a0: 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 QLite is to be c
95b0: 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 onfigured. Subs
95c0: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 equent arguments
95d0: 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 .** vary dependi
95e0: 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 ng on the [SQLIT
95f0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
9600: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 HREAD | configur
9610: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a ation option].**
9620: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
9630: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 gument..**.** Wh
9640: 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 en a configurati
9650: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 on option is set
9660: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 , sqlite3_config
9670: 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 () returns [SQLI
9680: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 49 66 20 74 68 TE_OK]..** If th
9690: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e e option is unkn
96a0: 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 own or SQLite is
96b0: 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 unable to set t
96c0: 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 he option.** the
96d0: 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 n this routine r
96e0: 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 eturns a non-zer
96f0: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a o [error code]..
9700: 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
9710: 74 73 3a 0a 2a 2a 20 5b 48 31 34 31 30 33 5d 20 ts:.** [H14103]
9720: 5b 48 31 34 31 30 36 5d 20 5b 48 31 34 31 32 30 [H14106] [H14120
9730: 5d 20 5b 48 31 34 31 32 33 5d 20 5b 48 31 34 31 ] [H14123] [H141
9740: 32 36 5d 20 5b 48 31 34 31 32 39 5d 20 5b 48 31 26] [H14129] [H1
9750: 34 31 33 32 5d 20 5b 48 31 34 31 33 35 5d 0a 2a 4132] [H14135].*
9760: 2a 20 5b 48 31 34 31 33 38 5d 20 5b 48 31 34 31 * [H14138] [H141
9770: 34 31 5d 20 5b 48 31 34 31 34 34 5d 20 5b 48 31 41] [H14144] [H1
9780: 34 31 34 37 5d 20 5b 48 31 34 31 35 30 5d 20 5b 4147] [H14150] [
9790: 48 31 34 31 35 33 5d 20 5b 48 31 34 31 35 36 5d H14153] [H14156]
97a0: 20 5b 48 31 34 31 35 39 5d 0a 2a 2a 20 5b 48 31 [H14159].** [H1
97b0: 34 31 36 32 5d 20 5b 48 31 34 31 36 35 5d 20 5b 4162] [H14165] [
97c0: 48 31 34 31 36 38 5d 0a 2a 2f 0a 53 51 4c 49 54 H14168].*/.SQLIT
97d0: 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 E_EXPERIMENTAL i
97e0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 nt sqlite3_confi
97f0: 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a g(int, ...);../*
9800: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
9810: 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 nfigure database
9820: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 20 7b 48 connections {H
9830: 31 34 32 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 14200} <S20000>.
9840: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
9850: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
9860: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 3_db_config() in
9870: 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
9880: 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 to make configur
9890: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 ation.** changes
98a0: 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 to a [database
98b0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 connection]. Th
98c0: 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 e interface is s
98d0: 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 imilar to.** [sq
98e0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
98f0: 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 except that the
9900: 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f changes apply to
9910: 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 a single.** [da
9920: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
9930: 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e n] (specified in
9940: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
9950: 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 ent). The.** sq
9960: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
9970: 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 ) interface can
9980: 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69 6d 6d only be used imm
9990: 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 0a 2a ediately after.*
99a0: 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
99b0: 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 72 65 onnection is cre
99c0: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ated using [sqli
99d0: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 te3_open()],.**
99e0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
99f0: 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f )], or [sqlite3_
9a00: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a open_v2()]. .**
9a10: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 .** The second a
9a20: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
9a30: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 e3_db_config(D,V
9a40: 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a ,...) is the.**
9a50: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 configuration v
9a60: 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 erb - an integer
9a70: 20 63 6f 64 65 20 74 68 61 74 20 69 6e 64 69 63 code that indic
9a80: 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 ates what.** asp
9a90: 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 ect of the [data
9aa0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
9ab0: 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 is being config
9ac0: 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c ured..** The onl
9ad0: 79 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 69 y choice for thi
9ae0: 73 20 76 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 s value is [SQLI
9af0: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
9b00: 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 ASIDE]..** New v
9b10: 65 72 62 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 erbs are likely
9b20: 74 6f 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 to be added in f
9b30: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
9b40: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 f SQLite..** Add
9b50: 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 itional argument
9b60: 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 s depend on the
9b70: 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 verb..**.** Requ
9b80: 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
9b90: 34 32 30 33 5d 20 5b 48 31 34 32 30 36 5d 20 5b 4203] [H14206] [
9ba0: 48 31 34 32 30 39 5d 20 5b 48 31 34 32 31 32 5d H14209] [H14212]
9bb0: 20 5b 48 31 34 32 31 35 5d 0a 2a 2f 0a 53 51 4c [H14215].*/.SQL
9bc0: 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c ITE_EXPERIMENTAL
9bd0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f int sqlite3_db_
9be0: 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c config(sqlite3*,
9bf0: 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a int op, ...);..
9c00: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
9c10: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f Memory Allocatio
9c20: 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31 30 31 n Routines {H101
9c30: 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 2a 2a 20 55} <S20120>.**
9c40: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
9c50: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f ** An instance o
9c60: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 f this object de
9c70: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 fines the interf
9c80: 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 ace between SQLi
9c90: 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 te.** and low-le
9ca0: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 vel memory alloc
9cb0: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a ation routines..
9cc0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 **.** This objec
9cd0: 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c t is used in onl
9ce0: 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 y one place in t
9cf0: 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 he SQLite interf
9d00: 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 ace..** A pointe
9d10: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 r to an instance
9d20: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 of this object
9d30: 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 is the argument
9d40: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
9d50: 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 onfig()] when th
9d60: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 e configuration
9d70: 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 option is.** [SQ
9d80: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
9d90: 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 74 69 6e OC]. By creatin
9da0: 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 g an instance of
9db0: 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 this object.**
9dc0: 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 and passing it t
9dd0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 o [sqlite3_confi
9de0: 67 28 29 5d 20 64 75 72 69 6e 67 20 63 6f 6e 66 g()] during conf
9df0: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 0a 2a 2a iguration, an.**
9e00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e application can
9e10: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 specify an alte
9e20: 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 20 61 rnative memory a
9e30: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 llocation subsys
9e40: 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c 69 74 tem.** for SQLit
9e50: 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c e to use for all
9e60: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 of its dynamic
9e70: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a memory needs..**
9e80: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 .** Note that SQ
9e90: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 Lite comes with
9ea0: 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 a built-in memor
9eb0: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 y allocator that
9ec0: 20 69 73 0a 2a 2a 20 70 65 72 66 65 63 74 6c 79 is.** perfectly
9ed0: 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 adequate for th
9ee0: 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d e overwhelming m
9ef0: 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 ajority of appli
9f00: 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 cations.** and t
9f10: 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 hat this object
9f20: 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 is only useful t
9f30: 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 o a tiny minorit
9f40: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e y of application
9f50: 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 s.** with specia
9f60: 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c lized memory all
9f70: 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d ocation requirem
9f80: 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 ents. This obje
9f90: 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 ct is.** also us
9fa0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e ed during testin
9fb0: 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f g of SQLite in o
9fc0: 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 rder to specify
9fd0: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a an alternative.*
9fe0: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
9ff0: 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 or that simulate
a000: 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d s memory out-of-
a010: 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e memory condition
a020: 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f s in.** order to
a030: 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c verify that SQL
a040: 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 ite recovers gra
a050: 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 cefully from suc
a060: 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e h.** conditions.
a070: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c .**.** The xMall
a080: 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e 64 20 78 oc, xFree, and x
a090: 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 73 20 Realloc methods
a0a0: 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 must work like t
a0b0: 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 he.** malloc(),
a0c0: 66 72 65 65 28 29 2c 20 61 6e 64 20 72 65 61 6c free(), and real
a0d0: 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 loc() functions
a0e0: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 from the standar
a0f0: 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a d library..**.**
a100: 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 xSize should re
a110: 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 turn the allocat
a120: 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d ed size of a mem
a130: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ory allocation.*
a140: 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 * previously obt
a150: 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c ained from xMall
a160: 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 oc or xRealloc.
a170: 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 The allocated s
a180: 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 ize.** is always
a190: 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 at least as big
a1a0: 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 as the requeste
a1b0: 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 d size but may b
a1c0: 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 e larger..**.**
a1d0: 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 The xRoundup met
a1e0: 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 hod returns what
a1f0: 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c would be the al
a200: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a located size of.
a210: 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ** a memory allo
a220: 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 cation given a p
a230: 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 articular reques
a240: 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 ted size. Most
a250: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
a260: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 tors round up me
a270: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 mory allocations
a280: 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 at least to the
a290: 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a next multiple.*
a2a0: 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c * of 8. Some al
a2b0: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 locators round u
a2c0: 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 p to a larger mu
a2d0: 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 ltiple or to a p
a2e0: 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a 2a 2a ower of 2..**.**
a2f0: 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f The xInit metho
a300: 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 d initializes th
a310: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
a320: 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c or. (For exampl
a330: 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 e,.** it might a
a340: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 llocate any requ
a350: 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 ire mutexes or i
a360: 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e nitialize intern
a370: 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 al data.** struc
a380: 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 tures. The xShu
a390: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 tdown method is
a3a0: 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 invoked (indirec
a3b0: 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 tly) by.** [sqli
a3c0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 te3_shutdown()]
a3d0: 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c and should deall
a3e0: 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 ocate any resour
a3f0: 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 ces acquired.**
a400: 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 by xInit. The p
a410: 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 AppData pointer
a420: 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f is used as the o
a430: 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f nly parameter to
a440: 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 .** xInit and xS
a450: 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79 70 65 hutdown..*/.type
a460: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
a470: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 e3_mem_methods s
a480: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
a490: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 ds;.struct sqlit
a4a0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b e3_mem_methods {
a4b0: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c . void *(*xMall
a4c0: 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 oc)(int);
a4d0: 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f /* Memory allo
a4e0: 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 cation function
a4f0: 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 */. void (*xFre
a500: 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 e)(void*);
a510: 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 /* Free a pr
a520: 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a ior allocation *
a530: 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 /. void *(*xRea
a540: 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 lloc)(void*,int)
a550: 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 ; /* Resize an
a560: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 allocation */.
a570: 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 int (*xSize)(voi
a580: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f d*); /
a590: 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a * Return the siz
a5a0: 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 e of an allocati
a5b0: 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 on */. int (*xR
a5c0: 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 oundup)(int);
a5d0: 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 /* Round
a5e0: 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 up request size
a5f0: 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 to allocation si
a600: 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 ze */. int (*xI
a610: 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 nit)(void*);
a620: 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 /* Initia
a630: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 lize the memory
a640: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 allocator */. v
a650: 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 oid (*xShutdown)
a660: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a (void*); /*
a670: 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 Deinitialize th
a680: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
a690: 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 or */. void *pA
a6a0: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 ppData;
a6b0: 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 /* Argume
a6c0: 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e nt to xInit() an
a6d0: 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f d xShutdown() */
a6e0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
a6f0: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 REF: Configurati
a700: 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 on Options {H101
a710: 36 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 60} <S20000>.**
a720: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
a730: 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
a740: 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c ts are the avail
a750: 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e able integer con
a760: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
a770: 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 ns that.** can b
a780: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
a790: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
a7a0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 o the [sqlite3_c
a7b0: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 onfig()] interfa
a7c0: 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f ce..**.** New co
a7d0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
a7e0: 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 ons may be added
a7f0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
a800: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ses of SQLite..*
a810: 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 * Existing confi
a820: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
a830: 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e might be discon
a840: 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 tinued. Applica
a850: 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 tions.** should
a860: 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e check the return
a870: 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 code from [sqli
a880: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f te3_config()] to
a890: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a make sure that.
a8a0: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b ** the call work
a8b0: 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 ed. The [sqlite
a8c0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 3_config()] inte
a8d0: 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 rface will retur
a8e0: 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 n a.** non-zero
a8f0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 [error code] if
a900: 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f a discontinued o
a910: 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f r unsupported co
a920: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
a930: 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 on.** is invoked
a940: 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 ..**.** <dl>.**
a950: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
a960: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f G_SINGLETHREAD</
a970: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 dt>.** <dd>There
a980: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 are no argument
a990: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
a9a0: 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 . This option d
a9b0: 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d isables.** all m
a9c0: 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 utexing and puts
a9d0: 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d SQLite into a m
a9e0: 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e ode where it can
a9f0: 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a only be used.**
aa00: 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 by a single thr
aa10: 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ead.</dd>.**.**
aa20: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
aa30: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 G_MULTITHREAD</d
aa40: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 t>.** <dd>There
aa50: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 are no arguments
aa60: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e to this option.
aa70: 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 This option di
aa80: 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 sables.** mutexi
aa90: 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 ng on [database
aaa0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 connection] and
aab0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
aac0: 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a ent] objects..**
aad0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
aae0: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
aaf0: 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 for serializing
ab00: 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 access to.** [da
ab10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
ab20: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 ns] and [prepare
ab30: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 d statements].
ab40: 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 But other mutexe
ab50: 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 s.** are enabled
ab60: 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 so that SQLite
ab70: 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 will be safe to
ab80: 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 use in a multi-t
ab90: 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 hreaded.** envir
aba0: 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 onment as long a
abb0: 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 s no two threads
abc0: 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 attempt to use
abd0: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 the same.** [dat
abe0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
abf0: 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 ] at the same ti
ac00: 6d 65 2e 20 20 53 65 65 20 74 68 65 20 5b 74 68 me. See the [th
ac10: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 0a 2a 2a reading mode].**
ac20: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 documentation f
ac30: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e or additional in
ac40: 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a formation.</dd>.
ac50: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
ac60: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a _CONFIG_SERIALIZ
ac70: 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ED</dt>.** <dd>T
ac80: 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 here are no argu
ac90: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 ments to this op
aca0: 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 tion. This opti
acb0: 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c on enables.** al
acc0: 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 l mutexes includ
acd0: 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 ing the recursiv
ace0: 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 e.** mutexes on
acf0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
ad00: 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 tion] and [prepa
ad10: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f red statement] o
ad20: 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 bjects..** In th
ad30: 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 is mode (which i
ad40: 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 s the default wh
ad50: 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d en SQLite is com
ad60: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 piled with.** [S
ad70: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
ad80: 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 =1]) the SQLite
ad90: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 library will its
ada0: 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 elf serialize ac
adb0: 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 cess.** to [data
adc0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
add0: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 ] and [prepared
ade0: 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 statements] so t
adf0: 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 hat the.** appli
ae00: 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 cation is free t
ae10: 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b o use the same [
ae20: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
ae30: 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 ion] or the.** s
ae40: 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 ame [prepared st
ae50: 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 atement] in diff
ae60: 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 erent threads at
ae70: 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a the same time..
ae80: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 ** See the [thre
ae90: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 ading mode] docu
aea0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 mentation for ad
aeb0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
aec0: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a tion.</dd>.**.**
aed0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
aee0: 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a IG_MALLOC</dt>.*
aef0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f * <dd>This optio
af00: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
af10: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
af20: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
af30: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f an.** instance o
af40: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
af50: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
af60: 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 cture. The argu
af70: 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a ment specifies.*
af80: 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f * alternative lo
af90: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 w-level memory a
afa0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
afb0: 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e es to be used in
afc0: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 place of.** the
afd0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
afe0: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c on routines buil
aff0: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f t into SQLite.</
b000: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
b010: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
b020: 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ALLOC</dt>.** <d
b030: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 d>This option ta
b040: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
b050: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
b060: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a pointer to an.*
b070: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 * instance of th
b080: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d e [sqlite3_mem_m
b090: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
b0a0: 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 e. The [sqlite3
b0b0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a _mem_methods].**
b0c0: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 structure is fi
b0d0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 lled with the cu
b0e0: 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 rrently defined
b0f0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
b100: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 n routines..** T
b110: 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 his option can b
b120: 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f e used to overlo
b130: 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d ad the default m
b140: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
b150: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 .** routines wit
b160: 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 h a wrapper that
b170: 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d simulations mem
b180: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
b190: 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 ailure or.** tra
b1a0: 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 cks memory usage
b1b0: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f , for example.</
b1c0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
b1d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
b1e0: 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 TATUS</dt>.** <d
b1f0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 d>This option ta
b200: 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d kes single argum
b210: 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c ent of type int,
b220: 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
b230: 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 a .** boolean, w
b240: 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 hich enables or
b250: 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c disables the col
b260: 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 lection of memor
b270: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a y allocation .**
b280: 20 73 74 61 74 69 73 74 69 63 73 2e 20 57 68 65 statistics. Whe
b290: 6e 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 n disabled, the
b2a0: 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 following SQLite
b2b0: 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f interfaces beco
b2c0: 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 me .** non-opera
b2d0: 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c tional:.** <ul
b2e0: 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c >.** <li> [sql
b2f0: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
b300: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
b310: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
b320: 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 ghwater()].**
b330: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f <li> [sqlite3_so
b340: 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d ft_heap_limit()]
b350: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 .** <li> [sqli
b360: 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a te3_status()].**
b370: 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 </ul>.** </dd
b380: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
b390: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
b3a0: 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
b3b0: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 is option specif
b3c0: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d ies a static mem
b3d0: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 ory buffer that
b3e0: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 SQLite can use f
b3f0: 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 or.** scratch me
b400: 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 mory. There are
b410: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 three arguments
b420: 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 : A pointer to
b430: 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 0a the memory, the.
b440: 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 ** size of each
b450: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 28 scratch buffer (
b460: 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d sz), and the num
b470: 62 65 72 20 6f 66 20 62 75 66 66 65 72 73 20 28 ber of buffers (
b480: 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 N). The sz.** a
b490: 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 rgument must be
b4a0: 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 a multiple of 16
b4b0: 2e 20 54 68 65 20 73 7a 20 70 61 72 61 6d 65 74 . The sz paramet
b4c0: 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 66 er should be a f
b4d0: 65 77 20 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 ew bytes.** larg
b4e0: 65 72 20 74 68 61 6e 20 74 68 65 20 61 63 74 75 er than the actu
b4f0: 61 6c 20 73 63 72 61 74 63 68 20 73 70 61 63 65 al scratch space
b500: 20 72 65 71 75 69 72 65 64 20 64 75 65 20 69 6e required due in
b510: 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e ternal overhead.
b520: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 0a 2a 2a .** The first.**
b530: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 argument should
b540: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c point to an all
b550: 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 ocation of at le
b560: 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f ast sz*N bytes o
b570: 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c f memory..** SQL
b580: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 ite will use no
b590: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 more than one sc
b5a0: 72 61 74 63 68 20 62 75 66 66 65 72 20 61 74 20 ratch buffer at
b5b0: 6f 6e 63 65 20 70 65 72 20 74 68 72 65 61 64 2c once per thread,
b5c0: 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 so.** N should
b5d0: 62 65 20 73 65 74 20 74 6f 20 74 68 65 20 65 78 be set to the ex
b5e0: 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e pected maximum n
b5f0: 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 umber of threads
b600: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72 . The sz.** par
b610: 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 ameter should be
b620: 20 36 20 74 69 6d 65 73 20 74 68 65 20 73 69 7a 6 times the siz
b630: 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 e of the largest
b640: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 database page s
b650: 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20 ize..** Scratch
b660: 62 75 66 66 65 72 73 20 61 72 65 20 75 73 65 64 buffers are used
b670: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 as part of the
b680: 62 74 72 65 65 20 62 61 6c 61 6e 63 65 20 6f 70 btree balance op
b690: 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 eration. If.**
b6a0: 54 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 The btree balanc
b6b0: 65 72 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f er needs additio
b6c0: 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e nal memory beyon
b6d0: 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 d what is provid
b6e0: 65 64 20 62 79 0a 2a 2a 20 73 63 72 61 74 63 68 ed by.** scratch
b6f0: 20 62 75 66 66 65 72 73 20 6f 72 20 69 66 20 6e buffers or if n
b700: 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 o scratch buffer
b710: 20 73 70 61 63 65 20 69 73 20 73 70 65 63 69 66 space is specif
b720: 69 65 64 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ied, then SQLite
b730: 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c .** goes to [sql
b740: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 ite3_malloc()] t
b750: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d o obtain the mem
b760: 6f 72 79 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64 ory it needs.</d
b770: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
b780: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
b790: 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ACHE</dt>.** <dd
b7a0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 >This option spe
b7b0: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 cifies a static
b7c0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 memory buffer th
b7d0: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 at SQLite can us
b7e0: 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 e for.** the dat
b7f0: 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 abase page cache
b800: 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c with the defaul
b810: 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 t page cache imp
b820: 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a lemenation. .**
b830: 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 This configurat
b840: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 ion should not b
b850: 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 e used if an app
b860: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 lication-define
b870: 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d page.** cache im
b880: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 plementation is
b890: 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 loaded using the
b8a0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
b8b0: 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a CACHE option..**
b8c0: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 There are three
b8d0: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
b8e0: 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 is option: A poi
b8f0: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 6d nter to the.** m
b900: 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 emory, the size
b910: 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 of each page buf
b920: 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 fer (sz), and th
b930: 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 e number of page
b940: 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a s (N)..** The sz
b950: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 argument must b
b960: 65 20 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f e a power of two
b970: 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 between 512 and
b980: 20 33 32 37 36 38 2e 20 20 54 68 65 20 66 69 72 32768. The fir
b990: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 st.** argument s
b9a0: 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 hould point to a
b9b0: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 n allocation of
b9c0: 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 at least sz*N by
b9d0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a tes of memory..*
b9e0: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 * SQLite will us
b9f0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f e the memory pro
ba00: 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 vided by the fir
ba10: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 st argument to s
ba20: 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 atisfy its.** me
ba30: 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 mory needs for t
ba40: 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 he first N pages
ba50: 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f that it adds to
ba60: 20 63 61 63 68 65 2e 20 20 49 66 20 61 64 64 69 cache. If addi
ba70: 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 tional.** page c
ba80: 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e ache memory is n
ba90: 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 eeded beyond wha
baa0: 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 t is provided by
bab0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 this option, th
bac0: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 en.** SQLite goe
bad0: 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 s to [sqlite3_ma
bae0: 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 lloc()] for the
baf0: 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 additional stora
bb00: 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 ge space..** The
bb10: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
bb20: 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 might use one or
bb30: 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62 more of the N b
bb40: 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a uffers to hold .
bb50: 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e ** memory accoun
bb60: 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e ting information
bb70: 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 . </dd>.**.** <d
bb80: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
bb90: 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 HEAP</dt>.** <dd
bba0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 >This option spe
bbb0: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 cifies a static
bbc0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 memory buffer th
bbd0: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 at SQLite will u
bbe0: 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 se.** for all of
bbf0: 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d its dynamic mem
bc00: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e ory allocation n
bc10: 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 eeds beyond thos
bc20: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f e provided.** fo
bc30: 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e r by [SQLITE_CON
bc40: 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 FIG_SCRATCH] and
bc50: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
bc60: 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 PAGECACHE]..** T
bc70: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 here are three a
bc80: 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e rguments: A poin
bc90: 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 ter to the memor
bca0: 79 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 y, the number of
bcb0: 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 .** bytes in the
bcc0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 memory buffer,
bcd0: 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 and the minimum
bce0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e allocation size.
bcf0: 20 20 49 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 If.** the firs
bd00: 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d t pointer (the m
bd10: 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 emory pointer) i
bd20: 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c s NULL, then SQL
bd30: 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 ite reverts.** t
bd40: 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 o using its defa
bd50: 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ult memory alloc
bd60: 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d ator (the system
bd70: 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d malloc() implem
bd80: 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e entation),.** un
bd90: 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 doing any prior
bda0: 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 invocation of [S
bdb0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
bdc0: 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a 2a 2a LOC]. If the.**
bdd0: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 memory pointer
bde0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 is not NULL and
bdf0: 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 either [SQLITE_E
be00: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f NABLE_MEMSYS3] o
be10: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 r.** [SQLITE_ENA
be20: 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 BLE_MEMSYS5] are
be30: 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 defined, then t
be40: 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d he alternative m
be50: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
be60: 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f or is engaged to
be70: 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 handle all of S
be80: 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c QLites memory al
be90: 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 3c location needs.<
bea0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
beb0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
bec0: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 EX</dt>.** <dd>T
bed0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
bee0: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
bef0: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f nt which is a po
bf00: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 inter to an.** i
bf10: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
bf20: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
bf30: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
bf40: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 . The argument
bf50: 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 specifies.** alt
bf60: 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 ernative low-lev
bf70: 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 el mutex routine
bf80: 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 s to be used in
bf90: 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 place.** the mut
bfa0: 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c ex routines buil
bfb0: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f t into SQLite.</
bfc0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
bfd0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
bfe0: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 UTEX</dt>.** <dd
bff0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b >This option tak
c000: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
c010: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
c020: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
c030: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
c040: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
c050: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
c060: 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c re. The.** [sql
c070: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
c080: 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 ds].** structure
c090: 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 is filled with
c0a0: 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 the currently de
c0b0: 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 fined mutex rout
c0c0: 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 ines..** This op
c0d0: 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 tion can be used
c0e0: 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 to overload the
c0f0: 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 default mutex a
c100: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 llocation.** rou
c110: 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 tines with a wra
c120: 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 pper used to tra
c130: 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 ck mutex usage f
c140: 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a or performance.*
c150: 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 * profiling or t
c160: 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d esting, for exam
c170: 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ple.</dd>.**.**
c180: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
c190: 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e G_LOOKASIDE</dt>
c1a0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
c1b0: 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 ion takes two ar
c1c0: 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 guments that det
c1d0: 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 ermine the defau
c1e0: 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c lt.** memory all
c1f0: 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 cation lookaside
c200: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 optimization.
c210: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
c220: 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a nt is the.** siz
c230: 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 e of each lookas
c240: 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 ide buffer slot
c250: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 and the second i
c260: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a s the number of.
c270: 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 ** slots allocat
c280: 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 ed to each datab
c290: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c ase connection.<
c2a0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
c2b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
c2c0: 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e CHE</dt>.** <dd>
c2d0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
c2e0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
c2f0: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
c300: 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 ointer to.** an
c310: 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
c320: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e methods] object.
c330: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 This object sp
c340: 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 ecifies the inte
c350: 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 rface.** to a cu
c360: 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 stom page cache
c370: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 implementation.
c380: 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 SQLite makes a
c390: 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f copy of the.** o
c3a0: 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 bject and uses i
c3b0: 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 t for page cache
c3c0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
c3d0: 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ons.</dd>.**.**
c3e0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
c3f0: 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74 3e G_GETPCACHE</dt>
c400: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
c410: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
c420: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
c430: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 h is a pointer t
c440: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 o an.** [sqlite3
c450: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d _pcache_methods]
c460: 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 object. SQLite
c470: 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 copies of the c
c480: 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 urrent.** page c
c490: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
c4a0: 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 ion into that ob
c4b0: 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ject.</dd>.**.**
c4c0: 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </dl>.*/.#defin
c4d0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
c4e0: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 SINGLETHREAD 1
c4f0: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
c500: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
c510: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 _MULTITHREAD 2
c520: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
c530: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
c540: 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 G_SERIALIZED
c550: 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 3 /* nil */.#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 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 IG_MALLOC
c580: 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 4 /* 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 47 45 54 4d 41 4c 4c 4f 43 20 20 NFIG_GETMALLOC
c5c0: 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5 /* sqlite3
c5d0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f _mem_methods* */
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 53 43 52 41 54 43 48 20 20 CONFIG_SCRATCH
c600: 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 6 /* 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 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
c640: 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 HE 7 /* voi
c650: 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 d*, int sz, int
c660: 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c N */.#define SQL
c670: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 ITE_CONFIG_HEAP
c680: 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 8 /* v
c690: 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c oid*, int nByte,
c6a0: 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 int min */.#def
c6b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
c6c0: 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 G_MEMSTATUS
c6d0: 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 9 /* boolean */
c6e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c6f0: 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 CONFIG_MUTEX
c700: 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 10 /* sqlit
c710: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
c720: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
c730: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
c740: 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 TEX 11 /* s
c750: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
c760: 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 hods* */./* prev
c770: 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f iously SQLITE_CO
c780: 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 NFIG_CHUNKALLOC
c790: 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 12 which is now
c7a0: 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 unused. */ .#def
c7b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
c7c0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 G_LOOKASIDE 1
c7d0: 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 3 /* int int */
c7e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c7f0: 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 CONFIG_PCACHE
c800: 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 14 /* sqlit
c810: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
c820: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
c830: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
c840: 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 CACHE 15 /*
c850: 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d sqlite3_pcache_m
c860: 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a ethods* */../*.*
c870: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
c880: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e iguration Option
c890: 73 20 7b 48 31 30 31 37 30 7d 20 3c 53 32 30 30 s {H10170} <S200
c8a0: 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 00>.** EXPERIMEN
c8b0: 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TAL.**.** These
c8c0: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 constants are th
c8d0: 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 e available inte
c8e0: 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ger configuratio
c8f0: 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a n options that.*
c900: 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 * can be passed
c910: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 as the second ar
c920: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 gument to the [s
c930: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
c940: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
c950: 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 *.** New configu
c960: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
c970: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
c980: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
c990: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 f SQLite..** Exi
c9a0: 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 sting configurat
c9b0: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 ion options migh
c9c0: 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 t be discontinue
c9d0: 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 d. Applications
c9e0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b .** should check
c9f0: 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 the return code
ca00: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 from [sqlite3_d
ca10: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d b_config()] to m
ca20: 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a ake sure that.**
ca30: 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 the call worked
ca40: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
ca50: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 db_config()] int
ca60: 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 erface will retu
ca70: 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f rn a.** non-zero
ca80: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
ca90: 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 a discontinued
caa0: 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 or unsupported c
cab0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
cac0: 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 ion.** is invoke
cad0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a d..**.** <dl>.**
cae0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
caf0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f NFIG_LOOKASIDE</
cb00: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
cb10: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 option takes thr
cb20: 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 ee additional ar
cb30: 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 guments that det
cb40: 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b ermine the .** [
cb50: 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
cb60: 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 allocator] conf
cb70: 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 iguration for th
cb80: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
cb90: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 ection]..** The
cba0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 first argument (
cbb0: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
cbc0: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
cbd0: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 db_config()] is
cbe0: 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 a.** pointer to
cbf0: 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 a memory buffer
cc00: 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 to use for looka
cc10: 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20 20 54 68 side memory. Th
cc20: 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d e first.** argum
cc30: 65 6e 74 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 ent may be NULL
cc40: 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 in which case SQ
cc50: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 Lite will alloca
cc60: 74 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 te the lookaside
cc70: 0a 2a 2a 20 62 75 66 66 65 72 20 69 74 73 65 6c .** buffer itsel
cc80: 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 f using [sqlite3
cc90: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 _malloc()]. The
cca0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
ccb0: 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 is the.** size
ccc0: 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 of each lookasid
ccd0: 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e e buffer slot an
cce0: 64 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 d the third argu
ccf0: 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 ment is the numb
cd00: 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 er of.** slots.
cd10: 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 The size of the
cd20: 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 buffer in the f
cd30: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 irst argument mu
cd40: 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 st be greater th
cd50: 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 an.** or equal t
cd60: 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 o the product of
cd70: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 the second and
cd80: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e third arguments.
cd90: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c </dd>.**.** </dl
cda0: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c >.*/.#define SQL
cdb0: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
cdc0: 4b 41 53 49 44 45 20 20 20 20 31 30 30 31 20 20 KASIDE 1001
cdd0: 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 /* void* int int
cde0: 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 */.../*.** CAPI
cdf0: 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 3REF: Enable Or
ce00: 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 Disable Extended
ce10: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 Result Codes {H
ce20: 31 32 32 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 12200} <S10700>.
ce30: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
ce40: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 3_extended_resul
ce50: 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e t_codes() routin
ce60: 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 e enables or dis
ce70: 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 ables the.** [ex
ce80: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
ce90: 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 des] feature of
cea0: 53 51 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65 SQLite. The exte
ceb0: 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 nded result.** c
cec0: 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 odes are disable
ced0: 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 d by default for
cee0: 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 historical comp
cef0: 61 74 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 atibility consid
cf00: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 erations..**.**
cf10: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
cf20: 20 5b 48 31 32 32 30 31 5d 20 5b 48 31 32 32 30 [H12201] [H1220
cf30: 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 2].*/.int sqlite
cf40: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 3_extended_resul
cf50: 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a t_codes(sqlite3*
cf60: 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f , int onoff);../
cf70: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c *.** CAPI3REF: L
cf80: 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 ast Insert Rowid
cf90: 20 7b 48 31 32 32 32 30 7d 20 3c 53 31 30 37 30 {H12220} <S1070
cfa0: 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 0>.**.** Each en
cfb0: 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 try in an SQLite
cfc0: 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 table has a uni
cfd0: 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 que 64-bit signe
cfe0: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 d.** integer key
cff0: 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 called the [ROW
d000: 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 54 ID | "rowid"]. T
d010: 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 he rowid is alwa
d020: 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 ys available.**
d030: 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 as an undeclared
d040: 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f column named RO
d050: 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f WID, OID, or _RO
d060: 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 WID_ as long as
d070: 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 those.** names a
d080: 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 re not also used
d090: 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 by explicitly d
d0a0: 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e eclared columns.
d0b0: 20 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 If.** the table
d0c0: 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 has a column of
d0d0: 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 type [INTEGER P
d0e0: 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e RIMARY KEY] then
d0f0: 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 that column.**
d100: 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 is another alias
d110: 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a for the rowid..
d120: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
d130: 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b ne returns the [
d140: 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f rowid] of the mo
d150: 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 st recent.** suc
d160: 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d cessful [INSERT]
d170: 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 into the databa
d180: 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 se from the [dat
d190: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
d1a0: 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 ].** in the firs
d1b0: 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 t argument. If
d1c0: 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 no successful [I
d1d0: 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 NSERT]s.** have
d1e0: 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e ever occurred on
d1f0: 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63 that database c
d200: 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 onnection, zero
d210: 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
d220: 2a 2a 20 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 ** If an [INSERT
d230: 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 ] occurs within
d240: 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 a trigger, then
d250: 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 the [rowid] of t
d260: 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 he inserted.** r
d270: 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 ow is returned b
d280: 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 y this routine a
d290: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 s long as the tr
d2a0: 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 igger is running
d2b0: 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 ..** But once th
d2c0: 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e e trigger termin
d2d0: 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 ates, the value
d2e0: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 returned by this
d2f0: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 routine.** reve
d300: 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 rts to the last
d310: 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 value inserted b
d320: 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 efore the trigge
d330: 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 r fired..**.** A
d340: 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 n [INSERT] that
d350: 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 fails due to a c
d360: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 onstraint violat
d370: 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 ion is not a.**
d380: 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 successful [INSE
d390: 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 RT] and does not
d3a0: 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 change the valu
d3b0: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 e returned by th
d3c0: 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 is.** routine.
d3d0: 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 Thus INSERT OR F
d3e0: 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 AIL, INSERT OR I
d3f0: 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 GNORE, INSERT OR
d400: 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e ROLLBACK,.** an
d410: 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 d INSERT OR ABOR
d420: 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 T make no change
d430: 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 s to the return
d440: 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a value of this.**
d450: 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 routine when th
d460: 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 eir insertion fa
d470: 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 ils. When INSER
d480: 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 T OR REPLACE.**
d490: 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e encounters a con
d4a0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f straint violatio
d4b0: 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 n, it does not f
d4c0: 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 ail. The.** INS
d4d0: 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f ERT continues to
d4e0: 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 completion afte
d4f0: 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 r deleting rows
d500: 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 that caused.** t
d510: 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 he constraint pr
d520: 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 oblem so INSERT
d530: 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 OR REPLACE will
d540: 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a always change.**
d550: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
d560: 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 e of this interf
d570: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 ace..**.** For t
d580: 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 he purposes of t
d590: 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 his routine, an
d5a0: 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 [INSERT] is cons
d5b0: 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 idered to.** be
d5c0: 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 successful even
d5d0: 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 if it is subsequ
d5e0: 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 ently rolled bac
d5f0: 6b 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 k..**.** Require
d600: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 32 ments:.** [H1222
d610: 31 5d 20 5b 48 31 32 32 32 33 5d 0a 2a 2a 0a 2a 1] [H12223].**.*
d620: 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 * If a separate
d630: 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 thread performs
d640: 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f a new [INSERT] o
d650: 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 n the same.** da
d660: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
d670: 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c n while the [sql
d680: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
d690: 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e _rowid()].** fun
d6a0: 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
d6b0: 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 and thus change
d6c0: 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 s the last inser
d6d0: 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 t [rowid],.** th
d6e0: 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 en the value ret
d6f0: 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
d700: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 3_last_insert_ro
d710: 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 wid()] is.** unp
d720: 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d redictable and m
d730: 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 ight not equal e
d740: 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 ither the old or
d750: 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 the new.** last
d760: 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e insert [rowid].
d770: 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 .*/.sqlite3_int6
d780: 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 4 sqlite3_last_i
d790: 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 nsert_rowid(sqli
d7a0: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
d7b0: 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 PI3REF: Count Th
d7c0: 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 e Number Of Rows
d7d0: 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34 Modified {H1224
d7e0: 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 0} <S10600>.**.*
d7f0: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
d800: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
d810: 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 er of database r
d820: 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68 ows that were ch
d830: 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 anged.** or inse
d840: 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 rted or deleted
d850: 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 by the most rece
d860: 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 ntly completed S
d870: 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 QL statement.**
d880: 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 on the [database
d890: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 connection] spe
d8a0: 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 cified by the fi
d8b0: 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a rst parameter..*
d8c0: 2a 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 * Only changes t
d8d0: 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 hat are directly
d8e0: 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
d8f0: 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 e [INSERT], [UPD
d900: 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c ATE],.** or [DEL
d910: 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 ETE] statement a
d920: 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 re counted. Aux
d930: 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 iliary changes c
d940: 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 aused by.** trig
d950: 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 gers are not cou
d960: 6e 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 nted. Use the [s
d970: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
d980: 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e nges()] function
d990: 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 .** to find the
d9a0: 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 total number of
d9b0: 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e changes includin
d9c0: 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 g changes caused
d9d0: 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a by triggers..**
d9e0: 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 .** A "row chang
d9f0: 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 e" is a change t
da00: 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f o a single row o
da10: 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 f a single table
da20: 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e .** caused by an
da30: 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c INSERT, DELETE,
da40: 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 or UPDATE state
da50: 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 ment. Rows that
da60: 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 .** are changed
da70: 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 as side effects
da80: 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 of REPLACE const
da90: 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e raint resolution
daa0: 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 ,.** rollback, A
dab0: 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c BORT processing,
dac0: 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20 DROP TABLE, or
dad0: 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 by any other.**
dae0: 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f mechanisms do no
daf0: 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 t count as direc
db00: 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a t row changes..*
db10: 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 *.** A "trigger
db20: 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 context" is a sc
db30: 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e ope of execution
db40: 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 that begins and
db50: 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 .** ends with th
db60: 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 74 72 e script of a tr
db70: 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c igger. Most SQL
db80: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a statements are.
db90: 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 ** evaluated out
dba0: 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 side of any trig
dbb0: 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 ger. This is th
dbc0: 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a e "top level".**
dbd0: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 trigger context
dbe0: 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 . If a trigger
dbf0: 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 fires from the t
dc00: 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e op level, a.** n
dc10: 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 ew trigger conte
dc20: 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f xt is entered fo
dc30: 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f r the duration o
dc40: 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 f that one.** tr
dc50: 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 igger. Subtrigg
dc60: 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f ers create subco
dc70: 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 ntexts for their
dc80: 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a duration..**.**
dc90: 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 Calling [sqlite
dca0: 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 3_exec()] or [sq
dcb0: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 lite3_step()] re
dcc0: 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a cursively does.*
dcd0: 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e * not create a n
dce0: 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 ew trigger conte
dcf0: 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 xt..**.** This f
dd00: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
dd10: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 the number of di
dd20: 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 rect row changes
dd30: 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 in the.** most
dd40: 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 recent INSERT, U
dd50: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 PDATE, or DELETE
dd60: 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 statement withi
dd70: 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 n the same.** tr
dd80: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a igger context..*
dd90: 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e 20 *.** Thus, when
dda0: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
ddb0: 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 top level, this
ddc0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
ddd0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
dde0: 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 f changes in the
ddf0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 most recent INS
de00: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 ERT, UPDATE, or
de10: 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 DELETE.** that a
de20: 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 lso occurred at
de30: 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 the top level.
de40: 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 Within the body
de50: 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a of a trigger,.**
de60: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 the sqlite3_cha
de70: 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 nges() interface
de80: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 can be called t
de90: 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 o find the numbe
dea0: 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 r of.** changes
deb0: 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 in the most rece
dec0: 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 ntly completed I
ded0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f NSERT, UPDATE, o
dee0: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 r DELETE.** stat
def0: 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 ement within the
df00: 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d body of the sam
df10: 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f e trigger..** Ho
df20: 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 wever, the numbe
df30: 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 r returned does
df40: 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e not include chan
df50: 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 ges.** caused by
df60: 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e subtriggers sin
df70: 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 ce those have th
df80: 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e eir own context.
df90: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d .**.** SQLite im
dfa0: 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d plements the com
dfb0: 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f mand "DELETE FRO
dfc0: 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 M table" without
dfd0: 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a a WHERE clause.
dfe0: 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 ** by dropping a
dff0: 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 nd recreating th
e000: 65 20 74 61 62 6c 65 2e 20 20 44 6f 69 6e 67 20 e table. Doing
e010: 73 6f 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 so is much faste
e020: 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 r than going.**
e030: 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 through and dele
e040: 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 ting individual
e050: 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 elements from th
e060: 65 20 74 61 62 6c 65 2e 20 20 42 65 63 61 75 73 e table. Becaus
e070: 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 e of this.** opt
e080: 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 imization, the d
e090: 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c eletions in "DEL
e0a0: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 ETE FROM table"
e0b0: 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e are not row chan
e0c0: 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 ges and.** will
e0d0: 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 not be counted b
e0e0: 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 y the sqlite3_ch
e0f0: 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 anges() or [sqli
e100: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
e110: 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e s()].** function
e120: 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 s, regardless of
e130: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 the number of e
e140: 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 lements that wer
e150: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 e originally.**
e160: 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 in the table. T
e170: 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 o get an accurat
e180: 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e e count of the n
e190: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 umber of rows de
e1a0: 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 leted, use.** "D
e1b0: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 ELETE FROM table
e1c0: 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 WHERE 1" instea
e1d0: 64 2e 20 20 4f 72 20 72 65 63 6f 6d 70 69 6c 65 d. Or recompile
e1e0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 using the.** [S
e1f0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 QLITE_OMIT_TRUNC
e200: 41 54 45 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e ATE_OPTIMIZATION
e210: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
e220: 70 74 69 6f 6e 20 74 6f 20 64 69 73 61 62 6c 65 ption to disable
e230: 20 74 68 65 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 the.** optimiza
e240: 74 69 6f 6e 20 6f 6e 20 61 6c 6c 20 71 75 65 72 tion on all quer
e250: 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ies..**.** Requi
e260: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 rements:.** [H12
e270: 32 34 31 5d 20 5b 48 31 32 32 34 33 5d 0a 2a 2a 241] [H12243].**
e280: 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
e290: 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 e thread makes c
e2a0: 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 hanges on the sa
e2b0: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
e2c0: 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 ection.** while
e2d0: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 [sqlite3_changes
e2e0: 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 ()] is running t
e2f0: 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 hen the value re
e300: 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 turned.** is unp
e310: 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e redictable and n
e320: 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a ot meaningful..*
e330: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 /.int sqlite3_ch
e340: 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b anges(sqlite3*);
e350: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
e360: 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f : Total Number O
e370: 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 f Rows Modified
e380: 7b 48 31 32 32 36 30 7d 20 3c 53 31 30 36 30 30 {H12260} <S10600
e390: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e >.**.** This fun
e3a0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
e3b0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 e number of row
e3c0: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 changes caused b
e3d0: 79 20 49 4e 53 45 52 54 2c 0a 2a 2a 20 55 50 44 y INSERT,.** UPD
e3e0: 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 ATE or DELETE st
e3f0: 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 atements since t
e400: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
e410: 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 nection] was ope
e420: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 6e ned..** The coun
e430: 74 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 t includes all c
e440: 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 hanges from all
e450: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 73 trigger contexts
e460: 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 . However,.** t
e470: 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f he count does no
e480: 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 t include change
e490: 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d s used to implem
e4a0: 65 6e 74 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 ent REPLACE cons
e4b0: 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 traints,.** do r
e4c0: 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 ollbacks or ABOR
e4d0: 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 T processing, or
e4e0: 20 44 52 4f 50 20 74 61 62 6c 65 20 70 72 6f 63 DROP table proc
e4f0: 65 73 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 essing..** The c
e500: 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 hanges are count
e510: 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 ed as soon as th
e520: 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 e statement that
e530: 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 0a 2a makes them is.*
e540: 2a 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 * completed (whe
e550: 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 n the statement
e560: 68 61 6e 64 6c 65 20 69 73 20 70 61 73 73 65 64 handle is passed
e570: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
e580: 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c et()] or.** [sql
e590: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
e5a0: 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 )..**.** SQLite
e5b0: 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 implements the c
e5c0: 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 ommand "DELETE F
e5d0: 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f ROM table" witho
e5e0: 75 74 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 ut a WHERE claus
e5f0: 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 e.** by dropping
e600: 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 and recreating
e610: 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 the table. (Thi
e620: 73 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 s is much faster
e630: 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 than going.** t
e640: 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 hrough and delet
e650: 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 ing individual e
e660: 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 lements from the
e670: 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 table.) Becaus
e680: 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 e of this.** opt
e690: 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 imization, the d
e6a0: 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c eletions in "DEL
e6b0: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 ETE FROM table"
e6c0: 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e are not row chan
e6d0: 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 ges and.** will
e6e0: 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 not be counted b
e6f0: 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 y the sqlite3_ch
e700: 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 anges() or [sqli
e710: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
e720: 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e s()].** function
e730: 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 s, regardless of
e740: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 the number of e
e750: 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 lements that wer
e760: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 e originally.**
e770: 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 in the table. T
e780: 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 o get an accurat
e790: 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e e count of the n
e7a0: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 umber of rows de
e7b0: 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 leted, use.** "D
e7c0: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 ELETE FROM table
e7d0: 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 WHERE 1" instea
e7e0: 64 2e 20 20 20 4f 72 20 72 65 63 6f 6d 70 69 6c d. Or recompil
e7f0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b e using the.** [
e800: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 55 4e SQLITE_OMIT_TRUN
e810: 43 41 54 45 5f 4f 50 54 49 4d 49 5a 41 54 49 4f CATE_OPTIMIZATIO
e820: 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 N] compile-time
e830: 6f 70 74 69 6f 6e 20 74 6f 20 64 69 73 61 62 6c option to disabl
e840: 65 20 74 68 65 0a 2a 2a 20 6f 70 74 69 6d 69 7a e the.** optimiz
e850: 61 74 69 6f 6e 20 6f 6e 20 61 6c 6c 20 71 75 65 ation on all que
e860: 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 ries..**.** See
e870: 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 also the [sqlite
e880: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 3_changes()] int
e890: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 erface..**.** Re
e8a0: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
e8b0: 48 31 32 32 36 31 5d 20 5b 48 31 32 32 36 33 5d H12261] [H12263]
e8c0: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 .**.** If a sepa
e8d0: 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 rate thread make
e8e0: 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 s changes on the
e8f0: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
e900: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 onnection.** whi
e910: 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 le [sqlite3_tota
e920: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 l_changes()] is
e930: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 running then the
e940: 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e value.** return
e950: 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 ed is unpredicta
e960: 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e ble and not mean
e970: 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 ingful..*/.int s
e980: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
e990: 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a nges(sqlite3*);.
e9a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
e9b0: 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e Interrupt A Lon
e9c0: 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 g-Running Query
e9d0: 7b 48 31 32 32 37 30 7d 20 3c 53 33 30 35 30 30 {H12270} <S30500
e9e0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e >.**.** This fun
e9f0: 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 ction causes any
ea00: 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 pending databas
ea10: 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 e operation to a
ea20: 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 bort and.** retu
ea30: 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 rn at its earlie
ea40: 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 st opportunity.
ea50: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 This routine is
ea60: 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c typically.** cal
ea70: 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 led in response
ea80: 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e to a user action
ea90: 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e such as pressin
eaa0: 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 g "Cancel".** or
eab0: 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 Ctrl-C where th
eac0: 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c e user wants a l
ead0: 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 ong query operat
eae0: 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 ion to halt.** i
eaf0: 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a mmediately..**.*
eb00: 2a 20 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 * It is safe to
eb10: 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e call this routin
eb20: 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 e from a thread
eb30: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 different from t
eb40: 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 he.** thread tha
eb50: 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 t is currently r
eb60: 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 unning the datab
eb70: 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 ase operation.
eb80: 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 But it.** is not
eb90: 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 safe to call th
eba0: 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 is routine with
ebb0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
ebc0: 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 ection] that.**
ebd0: 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 is closed or mig
ebe0: 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 ht close before
ebf0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
ec00: 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a t() returns..**.
ec10: 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 ** If an SQL ope
ec20: 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e ration is very n
ec30: 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 early finished a
ec40: 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a t the time when.
ec50: 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 ** sqlite3_inter
ec60: 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 rupt() is called
ec70: 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 , then it might
ec80: 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f not have an oppo
ec90: 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 rtunity.** to be
eca0: 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 interrupted and
ecb0: 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 might continue
ecc0: 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a to completion..*
ecd0: 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 *.** An SQL oper
ece0: 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e ation that is in
ecf0: 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 terrupted will r
ed00: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e eturn [SQLITE_IN
ed10: 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 TERRUPT]..** If
ed20: 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 the interrupted
ed30: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 SQL operation is
ed40: 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 an INSERT, UPDA
ed50: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a TE, or DELETE.**
ed60: 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 that is inside
ed70: 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e an explicit tran
ed80: 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 saction, then th
ed90: 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 e entire transac
eda0: 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 tion.** will be
edb0: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f rolled back auto
edc0: 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a matically..**.**
edd0: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 A call to sqlit
ede0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 68 e3_interrupt() h
edf0: 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 as no effect on
ee00: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
ee10: 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 * that are start
ee20: 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 ed after sqlite3
ee30: 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 _interrupt() ret
ee40: 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 urns..**.** Requ
ee50: 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
ee60: 32 32 37 31 5d 20 5b 48 31 32 32 37 32 5d 0a 2a 2271] [H12272].*
ee70: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 *.** If the data
ee80: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
ee90: 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 closes while [sq
eea0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
eeb0: 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 )].** is running
eec0: 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 then bad things
eed0: 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 will likely hap
eee0: 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c pen..*/.void sql
eef0: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 ite3_interrupt(s
ef00: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
ef10: 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 CAPI3REF: Deter
ef20: 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 mine If An SQL S
ef30: 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 tatement Is Comp
ef40: 6c 65 74 65 20 7b 48 31 30 35 31 30 7d 20 3c 53 lete {H10510} <S
ef50: 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 70200>.**.** The
ef60: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
ef70: 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 useful for comma
ef80: 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f nd-line input to
ef90: 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 determine if th
efa0: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 e.** currently e
efb0: 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d ntered text seem
efc0: 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 s to form comple
efd0: 74 65 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65 te a SQL stateme
efe0: 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 nt or.** if addi
eff0: 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 tional input is
f000: 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 needed before se
f010: 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 nding the text i
f020: 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f nto.** SQLite fo
f030: 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73 r parsing. Thes
f040: 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 e routines retur
f050: 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 69 6e n true if the in
f060: 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 put string.** ap
f070: 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f pears to be a co
f080: 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 mplete SQL state
f090: 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65 ment. A stateme
f0a0: 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 nt is judged to
f0b0: 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 be.** complete i
f0c0: 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 f it ends with a
f0d0: 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e semicolon token
f0e0: 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 66 72 and is not a fr
f0f0: 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 agment of a.** C
f100: 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 REATE TRIGGER st
f110: 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f atement. Semico
f120: 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d lons that are em
f130: 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a bedded within.**
f140: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 string literals
f150: 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 or quoted ident
f160: 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 ifier names or c
f170: 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a omments are not.
f180: 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 ** independent t
f190: 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 okens (they are
f1a0: 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 part of the toke
f1b0: 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 n in which they
f1c0: 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 are.** embedded)
f1d0: 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 and thus do not
f1e0: 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 count as a stat
f1f0: 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 ement terminator
f200: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
f210: 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 utines do not pa
f220: 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 rse the SQL stat
f230: 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 ements thus.** w
f240: 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 ill not detect s
f250: 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 yntactically inc
f260: 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a orrect SQL..**.*
f270: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 * Requirements:
f280: 5b 48 31 30 35 31 31 5d 20 5b 48 31 30 35 31 32 [H10511] [H10512
f290: 5d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 ].**.** The inpu
f2a0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f t to [sqlite3_co
f2b0: 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 mplete()] must b
f2c0: 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 e a zero-termina
f2d0: 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 ted.** UTF-8 str
f2e0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ing..**.** The i
f2f0: 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 nput to [sqlite3
f300: 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d _complete16()] m
f310: 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 ust be a zero-te
f320: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d rminated.** UTF-
f330: 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 16 string in nat
f340: 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a ive byte order..
f350: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
f360: 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 omplete(const ch
f370: 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 ar *sql);.int sq
f380: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
f390: 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c (const void *sql
f3a0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
f3b0: 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 EF: Register A C
f3c0: 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c allback To Handl
f3d0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 e SQLITE_BUSY Er
f3e0: 72 6f 72 73 20 7b 48 31 32 33 31 30 7d 20 3c 53 rors {H12310} <S
f3f0: 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 40400>.**.** Thi
f400: 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 s routine sets a
f410: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
f420: 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 on that might be
f430: 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 invoked wheneve
f440: 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 r.** an attempt
f450: 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 is made to open
f460: 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 a database table
f470: 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 that another th
f480: 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 read.** or proce
f490: 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a ss has locked..*
f4a0: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 *.** If the busy
f4b0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c callback is NUL
f4c0: 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f L, then [SQLITE_
f4d0: 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 BUSY] or [SQLITE
f4e0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a _IOERR_BLOCKED].
f4f0: 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 ** is returned i
f500: 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 mmediately upon
f510: 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 encountering the
f520: 20 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20 62 75 lock. If the bu
f530: 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 sy callback.** i
f540: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e s not NULL, then
f550: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 the callback wi
f560: 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 ll be invoked wi
f570: 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 th two arguments
f580: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
f590: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
f5a0: 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 e handler is a c
f5b0: 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a opy of the void*
f5c0: 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a pointer which.*
f5d0: 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 * is the third a
f5e0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
f5f0: 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
f600: 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 ). The second a
f610: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 rgument to.** th
f620: 65 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 e handler callba
f630: 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 ck is the number
f640: 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 of times that t
f650: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
f660: 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f has.** been invo
f670: 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 ked for this loc
f680: 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 49 66 20 king event. If
f690: 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c the.** busy call
f6a0: 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 back returns 0,
f6b0: 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e then no addition
f6c0: 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 al attempts are
f6d0: 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 made to.** acces
f6e0: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 s the database a
f6f0: 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d nd [SQLITE_BUSY]
f700: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 or [SQLITE_IOER
f710: 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 R_BLOCKED] is re
f720: 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 turned..** If th
f730: 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
f740: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 ns non-zero, the
f750: 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 n another attemp
f760: 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 t.** is made to
f770: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 open the databas
f780: 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e e for reading an
f790: 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 d the cycle repe
f7a0: 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 ats..**.** The p
f7b0: 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 resence of a bus
f7c0: 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e y handler does n
f7d0: 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 ot guarantee tha
f7e0: 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 t it will be inv
f7f0: 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 oked.** when the
f800: 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 re is lock conte
f810: 6e 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 ntion. If SQLite
f820: 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 determines that
f830: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 invoking the bu
f840: 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f sy.** handler co
f850: 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 uld result in a
f860: 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c deadlock, it wil
f870: 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 l go ahead and r
f880: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 eturn [SQLITE_BU
f890: 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 SY].** or [SQLIT
f8a0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
f8b0: 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f instead of invo
f8c0: 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 king the busy ha
f8d0: 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 ndler..** Consid
f8e0: 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 er a scenario wh
f8f0: 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 ere one process
f900: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 is holding a rea
f910: 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 d lock that.** i
f920: 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 t is trying to p
f930: 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 romote to a rese
f940: 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a rved lock and.**
f950: 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 a second proces
f960: 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 s is holding a r
f970: 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 eserved lock tha
f980: 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a t it is trying.*
f990: 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 * to promote to
f9a0: 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 an exclusive loc
f9b0: 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 k. The first pr
f9c0: 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f ocess cannot pro
f9d0: 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 ceed.** because
f9e0: 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 it is blocked by
f9f0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 the second and
fa00: 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 the second proce
fa10: 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f ss cannot.** pro
fa20: 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 ceed because it
fa30: 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 is blocked by th
fa40: 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 e first. If bot
fa50: 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 h processes.** i
fa60: 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 nvoke the busy h
fa70: 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 andlers, neither
fa80: 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 will make any p
fa90: 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 rogress. Theref
faa0: 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 ore,.** SQLite r
fab0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 eturns [SQLITE_B
fac0: 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 USY] for the fir
fad0: 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 st process, hopi
fae0: 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 ng that this.**
faf0: 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 will induce the
fb00: 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f first process to
fb10: 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 release its rea
fb20: 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 d lock and allow
fb30: 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 .** the second p
fb40: 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 rocess to procee
fb50: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 d..**.** The def
fb60: 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 ault busy callba
fb70: 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a ck is NULL..**.*
fb80: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 * The [SQLITE_BU
fb90: 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e SY] error is con
fba0: 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 verted to [SQLIT
fbb0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
fbc0: 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 .** when SQLite
fbd0: 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 is in the middle
fbe0: 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e of a large tran
fbf0: 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c saction where al
fc00: 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 l the.** changes
fc10: 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e will not fit in
fc20: 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 to the in-memory
fc30: 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 cache. SQLite
fc40: 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 will.** already
fc50: 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 hold a RESERVED
fc60: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 lock on the data
fc70: 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 base file, but i
fc80: 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 t needs.** to pr
fc90: 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 omote this lock
fca0: 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 to EXCLUSIVE so
fcb0: 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c that it can spil
fcc0: 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 l cache.** pages
fcd0: 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 into the databa
fce0: 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 se file without
fcf0: 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 harm to concurre
fd00: 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 nt.** readers.
fd10: 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 If it is unable
fd20: 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c to promote the l
fd30: 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e ock, then the in
fd40: 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 -memory.** cache
fd50: 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e will be left in
fd60: 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 an inconsistent
fd70: 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 state and so th
fd80: 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 e error.** code
fd90: 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d is promoted from
fda0: 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 the relatively
fdb0: 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 benign [SQLITE_B
fdc0: 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d USY] to.** the m
fdd0: 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 ore severe [SQLI
fde0: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
fdf0: 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 63 ]. This error c
fe00: 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a ode promotion.**
fe10: 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d forces an autom
fe20: 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 atic rollback of
fe30: 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 the changes. S
fe40: 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 ee the.** <a hre
fe50: 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 f="/cvstrac/wiki
fe60: 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c ?p=CorruptionFol
fe70: 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 lowingBusyError"
fe80: 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 >.** CorruptionF
fe90: 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f ollowingBusyErro
fea0: 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 r</a> wiki page
feb0: 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e for a discussion
fec0: 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 of why.** this
fed0: 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a is important..**
fee0: 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e .** There can on
fef0: 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 ly be a single b
ff00: 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 usy handler defi
ff10: 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 ned for each.**
ff20: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
ff30: 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 tion]. Setting
ff40: 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c a new busy handl
ff50: 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a er clears any.**
ff60: 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 previously set
ff70: 68 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 handler. Note t
ff80: 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c hat calling [sql
ff90: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
ffa0: 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 t()].** will als
ffb0: 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 o set or clear t
ffc0: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e he busy handler.
ffd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 .**.** The busy
ffe0: 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 callback should
fff0: 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 not take any act
10000 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 ions which modif
10010 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 y the.** databas
10020 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 e connection tha
10030 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 t invoked the bu
10040 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 sy handler. Any
10050 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a such actions.**
10060 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 result in undef
10070 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a ined behavior..*
10080 2a 20 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e * .** Requiremen
10090 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 31 31 5d 20 ts:.** [H12311]
100a0 5b 48 31 32 33 31 32 5d 20 5b 48 31 32 33 31 34 [H12312] [H12314
100b0 5d 20 5b 48 31 32 33 31 36 5d 20 5b 48 31 32 33 ] [H12316] [H123
100c0 31 38 5d 0a 2a 2a 0a 2a 2a 20 41 20 62 75 73 79 18].**.** A busy
100d0 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f handler must no
100e0 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 t close the data
100f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
10100 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 ** or [prepared
10110 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
10120 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 invoked the busy
10130 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 handler..*/.int
10140 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 sqlite3_busy_ha
10150 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 ndler(sqlite3*,
10160 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 int(*)(void*,int
10170 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a ), void*);../*.*
10180 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 * CAPI3REF: Set
10190 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 20 7b A Busy Timeout {
101a0 48 31 32 33 34 30 7d 20 3c 53 34 30 34 31 30 3e H12340} <S40410>
101b0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
101c0 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 ine sets a [sqli
101d0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
101e0 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d | busy handler]
101f0 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 that sleeps.**
10200 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 for a specified
10210 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 amount of time w
10220 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c hen a table is l
10230 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64 ocked. The hand
10240 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 ler.** will slee
10250 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 p multiple times
10260 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 until at least
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 0a 2a 2a s of sleeping.**
10290 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 have accumulate
102a0 64 2e 20 7b 48 31 32 33 34 33 7d 20 41 66 74 65 d. {H12343} Afte
102b0 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f r "ms" milliseco
102c0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c nds of sleeping,
102d0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 .** the handler
102e0 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 returns 0 which
102f0 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f causes [sqlite3_
10300 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 step()] to retur
10310 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 n.** [SQLITE_BUS
10320 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f Y] or [SQLITE_IO
10330 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a ERR_BLOCKED]..**
10340 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 .** Calling this
10350 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e routine with an
10360 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 argument less t
10370 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 han or equal to
10380 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 zero.** turns of
10390 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c f all busy handl
103a0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 ers..**.** There
103b0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 can only be a s
103c0 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c ingle busy handl
103d0 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 er for a particu
103e0 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 lar.** [database
103f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 connection] any
10400 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e any given momen
10410 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 t. If another b
10420 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 usy handler.** w
10430 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 as defined (usi
10440 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 ng [sqlite3_busy
10450 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 _handler()]) pri
10460 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a or to calling.**
10470 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 this routine, t
10480 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 hat other busy h
10490 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 andler is cleare
104a0 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 d..**.** Require
104b0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 34 ments:.** [H1234
104c0 31 5d 20 5b 48 31 32 33 34 33 5d 20 5b 48 31 32 1] [H12343] [H12
104d0 33 34 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 344].*/.int sqli
104e0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
104f0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d (sqlite3*, int m
10500 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 s);../*.** CAPI3
10510 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 REF: Convenience
10520 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 Routines For Ru
10530 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b 48 nning Queries {H
10540 31 32 33 37 30 7d 20 3c 53 31 30 30 30 30 3e 0a 12370} <S10000>.
10550 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e **.** Definition
10560 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 : A <b>result ta
10570 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 ble</b> is memor
10580 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 y data structure
10590 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a created by the.
105a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f ** [sqlite3_get_
105b0 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 table()] interfa
105c0 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 ce. A result ta
105d0 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a ble records the.
105e0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 ** complete quer
105f0 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f y results from o
10600 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 ne or more queri
10610 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 es..**.** The ta
10620 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 ble conceptually
10630 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 has a number of
10640 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e rows and column
10650 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 s. But.** these
10660 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 numbers are not
10670 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 part of the res
10680 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 ult table itself
10690 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 . These.** numb
106a0 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 ers are obtained
106b0 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 separately. Le
106c0 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 t N be the numbe
106d0 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 r of rows.** and
106e0 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 M be the number
106f0 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a of columns..**.
10700 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c ** A result tabl
10710 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 e is an array of
10720 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 pointers to zer
10730 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
10740 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 -8 strings..** T
10750 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d here are (N+1)*M
10760 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 elements in the
10770 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 array. The fir
10780 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f st M pointers po
10790 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 int.** to zero-t
107a0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 erminated string
107b0 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 s that contain
107c0 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 the names of the
107d0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 columns..** The
107e0 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 remaining entri
107f0 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 es all point to
10800 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 query results.
10810 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 NULL values resu
10820 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f lt.** in NULL po
10830 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 inters. All oth
10840 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e er values are in
10850 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 their UTF-8 zer
10860 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
10870 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 string represent
10880 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 ation as returne
10890 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f d by [sqlite3_co
108a0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a lumn_text()]..**
108b0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 .** A result tab
108c0 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 le might consist
108d0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 of one or more
108e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
108f0 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 ns..** It is not
10900 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 safe to pass a
10910 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 result table dir
10920 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 ectly to [sqlite
10930 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 3_free()]..** A
10940 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f result table sho
10950 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 uld be deallocat
10960 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
10970 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 3_free_table()].
10980 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 .**.** As an exa
10990 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 mple of the resu
109a0 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c lt table format,
109b0 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 suppose a query
109c0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 result.** is as
109d0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
109e0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
109f0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 >.** Name
10a00 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a | Age.**
10a10 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d --------
10a20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a ---------------.
10a30 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 ** Alice
10a40 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 | 43.**
10a50 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 Bob
10a60 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 | 28.**
10a70 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 Cindy | 21
10a80 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
10a90 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
10aa0 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 ere are two colu
10ab0 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 mn (M==2) and th
10ac0 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e ree rows (N==3).
10ad0 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 Thus the.** re
10ae0 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 sult table has 8
10af0 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f entries. Suppo
10b00 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 se the result ta
10b10 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a ble is stored.**
10b20 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d in an array nam
10b30 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 es azResult. Th
10b40 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 en azResult hold
10b50 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a s this content:.
10b60 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
10b70 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 e><pre>.**
10b80 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 azResult[0
10b90 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 ] = "Name";.**
10ba0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
10bb0 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 91;1] = "Age";.*
10bc0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
10bd0 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 t[2] = "Alic
10be0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a e";.** az
10bf0 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 Result[3] =
10c00 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 "43";.**
10c10 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 azResult[4]
10c20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 = "Bob";.**
10c30 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
10c40 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 5] = "28";.**
10c50 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
10c60 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 1;6] = "Cindy";.
10c70 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
10c80 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 lt[7] = "21"
10c90 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
10ca0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
10cb0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
10cc0 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 able() function
10cd0 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 evaluates one or
10ce0 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c more.** semicol
10cf0 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c on-separated SQL
10d00 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 statements in t
10d10 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 he zero-terminat
10d20 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 ed UTF-8.** stri
10d30 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 ng of its 2nd pa
10d40 72 61 6d 65 74 65 72 2e 20 20 49 74 20 72 65 74 rameter. It ret
10d50 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 urns a result ta
10d60 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f ble to the.** po
10d70 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 inter given in i
10d80 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 ts 3rd parameter
10d90 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 ..**.** After th
10da0 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 e calling functi
10db0 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 on has finished
10dc0 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 using the result
10dd0 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 , it should.** p
10de0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 ass the pointer
10df0 74 6f 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 to the result ta
10e00 62 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 ble to sqlite3_f
10e10 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f ree_table() in o
10e20 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 rder to.** relea
10e30 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 se the memory th
10e40 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e at was malloced.
10e50 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 Because of the
10e60 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c way the.** [sql
10e70 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 ite3_malloc()] h
10e80 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 appens within sq
10e90 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
10ea0 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a ), the calling.*
10eb0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 * function must
10ec0 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 not try to call
10ed0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
10ee0 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 directly. Only
10ef0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 .** [sqlite3_fre
10f00 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 e_table()] is ab
10f10 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 le to release th
10f20 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c e memory properl
10f30 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a y and safely..**
10f40 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
10f50 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 get_table() inte
10f60 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 rface is impleme
10f70 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 nted as a wrappe
10f80 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c r around.** [sql
10f90 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 ite3_exec()]. T
10fa0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
10fb0 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 able() routine d
10fc0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 oes not have acc
10fd0 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e ess.** to any in
10fe0 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 ternal data stru
10ff0 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 ctures of SQLite
11000 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 . It uses only
11010 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e the public.** in
11020 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 terface defined
11030 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 here. As a cons
11040 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 equence, errors
11050 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 that occur in th
11060 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 e.** wrapper lay
11070 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 er outside of th
11080 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 e internal [sqli
11090 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c te3_exec()] call
110a0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c are not.** refl
110b0 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 ected in subsequ
110c0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ent calls to [sq
110d0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
110e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 or [sqlite3_err
110f0 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 msg()]..**.** Re
11100 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
11110 48 31 32 33 37 31 5d 20 5b 48 31 32 33 37 33 5d H12371] [H12373]
11120 20 5b 48 31 32 33 37 34 5d 20 5b 48 31 32 33 37 [H12374] [H1237
11130 36 5d 20 5b 48 31 32 33 37 39 5d 20 5b 48 31 32 6] [H12379] [H12
11140 33 38 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 382].*/.int sqli
11150 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 te3_get_table(.
11160 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
11170 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 /* An ope
11180 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 n database */.
11190 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c const char *zSql
111a0 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 , /* SQL to
111b0 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a be evaluated */.
111c0 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 char ***pazRes
111d0 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c ult, /* Resul
111e0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 ts of the query
111f0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c */. int *pnRow,
11200 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 /* Nu
11210 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 mber of result r
11220 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 ows written here
11230 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c */. int *pnCol
11240 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e umn, /* N
11250 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 umber of result
11260 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 columns written
11270 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a here */. char *
11280 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 *pzErrmsg
11290 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 /* Error msg wri
112a0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a tten here */.);.
112b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 void sqlite3_fre
112c0 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 e_table(char **r
112d0 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 esult);../*.** C
112e0 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 API3REF: Formatt
112f0 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 ed String Printi
11300 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 ng Functions {H1
11310 37 34 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 7400} <S70000><S
11320 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20000>.**.** The
11330 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
11340 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 workalikes of th
11350 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d e "printf()" fam
11360 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 ily of functions
11370 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 .** from the sta
11380 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e ndard C library.
11390 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
113a0 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 e3_mprintf() and
113b0 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 sqlite3_vmprint
113c0 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 f() routines wri
113d0 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 te their.** resu
113e0 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 lts into memory
113f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
11400 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
11410 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 ..** The strings
11420 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
11430 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 se two routines
11440 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c should be.** rel
11450 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 eased by [sqlite
11460 33 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 3_free()]. Both
11470 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
11480 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 a.** NULL point
11490 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d er if [sqlite3_m
114a0 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 alloc()] is unab
114b0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 le to allocate e
114c0 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 nough.** memory
114d0 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 to hold the resu
114e0 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a lting string..**
114f0 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 .** In sqlite3_s
11500 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e nprintf() routin
11510 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 e is similar to
11520 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f "snprintf()" fro
11530 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 m.** the standar
11540 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 d C library. Th
11550 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 e result is writ
11560 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 ten into the.**
11570 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 buffer supplied
11580 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
11590 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 rameter whose si
115a0 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a ze is given by.*
115b0 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 * the first para
115c0 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 meter. Note that
115d0 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 the order of th
115e0 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 e.** first two p
115f0 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 arameters is rev
11600 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 ersed from snpri
11610 6e 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 ntf(). This is
11620 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c an.** historical
11630 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 accident that c
11640 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 annot be fixed w
11650 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a ithout breaking.
11660 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d ** backwards com
11670 70 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 patibility. Not
11680 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 e also that sqli
11690 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a te3_snprintf().*
116a0 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e * returns a poin
116b0 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 ter to its buffe
116c0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 r instead of the
116d0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 number of.** ch
116e0 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c aracters actuall
116f0 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 y written into t
11700 68 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 he buffer. We a
11710 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 dmit that.** the
11720 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 number of chara
11730 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f cters written wo
11740 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 uld be a more us
11750 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 eful return.** v
11760 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e alue but we cann
11770 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d ot change the im
11780 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
11790 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
117a0 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 ().** now withou
117b0 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 t breaking compa
117c0 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 tibility..**.**
117d0 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 As long as the b
117e0 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 uffer size is gr
117f0 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c eater than zero,
11800 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
11810 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 f().** guarantee
11820 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 s that the buffe
11830 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f r is always zero
11840 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 -terminated. Th
11850 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d e first.** param
11860 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 eter "n" is the
11870 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 total size of th
11880 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 e buffer, includ
11890 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a ing space for.**
118a0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e the zero termin
118b0 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f ator. So the lo
118c0 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 ngest string tha
118d0 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 t can be complet
118e0 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 ely.** written w
118f0 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 ill be n-1 chara
11900 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 cters..**.** The
11910 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 se routines all
11920 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 implement some a
11930 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 dditional format
11940 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 ting.** options
11950 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 that are useful
11960 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 for constructing
11970 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e SQL statements.
11980 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 .** All of the u
11990 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f sual printf() fo
119a0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 rmatting options
119b0 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 apply. In addi
119c0 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 tion, there.** i
119d0 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 s are "%q", "%Q"
119e0 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f , and "%z" optio
119f0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 ns..**.** The %q
11a00 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 option works li
11a10 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 ke %s in that it
11a20 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e substitutes a n
11a30 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ull-terminated.*
11a40 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 * string from th
11a50 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e e argument list.
11a60 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f But %q also do
11a70 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 ubles every '\''
11a80 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 character..** %
11a90 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f q is designed fo
11aa0 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 r use inside a s
11ab0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 tring literal.
11ac0 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 By doubling each
11ad0 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 '\''.** charact
11ae0 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 er it escapes th
11af0 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 at character and
11b00 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 allows it to be
11b10 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a inserted into.*
11b20 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a * the string..**
11b30 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c .** For example,
11b40 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 assume the stri
11b50 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 ng variable zTex
11b60 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 t contains text
11b70 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
11b80 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
11b90 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 re>.** char *zT
11ba0 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 ext = "It's a ha
11bb0 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f ppy day!";.** </
11bc0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
11bd0 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 >.**.** One can
11be0 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e use this text in
11bf0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
11c00 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a t as follows:.**
11c10 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
11c20 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a <pre>.** char *
11c30 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d zSQL = sqlite3_m
11c40 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 printf("INSERT I
11c50 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 NTO table VALUES
11c60 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b ('%q')", zText);
11c70 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 .** sqlite3_exe
11c80 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 c(db, zSQL, 0, 0
11c90 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 , 0);.** sqlite
11ca0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 3_free(zSQL);.**
11cb0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
11cc0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 ote>.**.** Becau
11cd0 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 se the %q format
11ce0 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c string is used,
11cf0 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 the '\'' charac
11d00 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 ter in zText.**
11d10 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 is escaped and t
11d20 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 he SQL generated
11d30 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a is as follows:.
11d40 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
11d50 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 e><pre>.** INSE
11d60 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 RT INTO table1 V
11d70 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 ALUES('It''s a h
11d80 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c appy day!').** <
11d90 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
11da0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 e>.**.** This is
11db0 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 correct. Had w
11dc0 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 e used %s instea
11dd0 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e d of %q, the gen
11de0 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f erated SQL.** wo
11df0 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 uld have looked
11e00 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a like this:.**.**
11e10 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
11e20 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e e>.** INSERT IN
11e30 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 TO table1 VALUES
11e40 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 ('It's a happy d
11e50 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e ay!');.** </pre>
11e60 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
11e70 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 .** This second
11e80 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 example is an SQ
11e90 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 L syntax error.
11ea0 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 As a general ru
11eb0 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a le you should.**
11ec0 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 always use %q i
11ed0 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 nstead of %s whe
11ee0 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 n inserting text
11ef0 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c into a string l
11f00 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 iteral..**.** Th
11f10 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b e %Q option work
11f20 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 s like %q except
11f30 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 it also adds si
11f40 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 ngle quotes arou
11f50 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 nd.** the outsid
11f60 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 e of the total s
11f70 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e tring. Addition
11f80 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 ally, if the par
11f90 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a ameter in the.**
11fa0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 argument list i
11fb0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
11fc0 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 , %Q substitutes
11fd0 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 the text "NULL"
11fe0 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e (without.** sin
11ff0 67 6c 65 20 71 75 6f 74 65 73 29 20 69 6e 20 70 gle quotes) in p
12000 6c 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f lace of the %Q o
12010 70 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 ption. So, for
12020 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 example, one cou
12030 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ld say:.**.** <b
12040 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
12050 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d ** char *zSQL =
12060 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 sqlite3_mprintf
12070 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 ("INSERT INTO ta
12080 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c ble VALUES(%Q)",
12090 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c zText);.** sql
120a0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 ite3_exec(db, zS
120b0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a QL, 0, 0, 0);.**
120c0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a sqlite3_free(z
120d0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c SQL);.** </pre><
120e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
120f0 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 ** The code abov
12100 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 e will render a
12110 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 correct SQL stat
12120 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 ement in the zSQ
12130 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 L.** variable ev
12140 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 en if the zText
12150 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 variable is a NU
12160 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
12170 2a 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 * The "%z" forma
12180 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 tting option wor
12190 6b 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 ks exactly like
121a0 22 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a "%s" with the.**
121b0 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 addition that a
121c0 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 fter the string
121d0 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e has been read an
121e0 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a d copied into.**
121f0 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 the result, [sq
12200 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 lite3_free()] is
12210 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 called on the i
12220 6e 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e nput string. {EN
12230 44 7d 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 D}.**.** Require
12240 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 34 30 ments:.** [H1740
12250 33 5d 20 5b 48 31 37 34 30 36 5d 20 5b 48 31 37 3] [H17406] [H17
12260 34 30 37 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 407].*/.char *sq
12270 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f lite3_mprintf(co
12280 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a nst char*,...);.
12290 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d char *sqlite3_vm
122a0 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 printf(const cha
122b0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 r*, va_list);.ch
122c0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 ar *sqlite3_snpr
122d0 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 intf(int,char*,c
122e0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 onst char*, ...)
122f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
12300 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 F: Memory Alloca
12310 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 7b tion Subsystem {
12320 48 31 37 33 30 30 7d 20 3c 53 32 30 30 30 30 3e H17300} <S20000>
12330 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 .**.** The SQLit
12340 65 20 63 6f 72 65 20 20 75 73 65 73 20 74 68 65 e core uses the
12350 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 se three routine
12360 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 s for all of its
12370 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c own.** internal
12380 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
12390 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 on needs. "Core"
123a0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 in the previous
123b0 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 sentence.** doe
123c0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 s not include op
123d0 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 erating-system s
123e0 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c pecific VFS impl
123f0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 ementation. The
12400 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 .** Windows VFS
12410 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c uses native mall
12420 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
12430 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 for some operati
12440 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ons..**.** The s
12450 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
12460 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
12470 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 a pointer to a b
12480 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 lock.** of memor
12490 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 y at least N byt
124a0 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 es in length, wh
124b0 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 ere N is the par
124c0 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 ameter..** If sq
124d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 lite3_malloc() i
124e0 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 s unable to obta
124f0 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 in sufficient fr
12500 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 ee.** memory, it
12510 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 returns a NULL
12520 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65 pointer. If the
12530 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a parameter N to.
12540 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f ** sqlite3_mallo
12550 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e c() is zero or n
12560 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c egative then sql
12570 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 ite3_malloc() re
12580 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 turns.** a NULL
12590 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 pointer..**.** C
125a0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 alling sqlite3_f
125b0 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 ree() with a poi
125c0 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 nter previously
125d0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 returned.** by s
125e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
125f0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c or sqlite3_reall
12600 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 oc() releases th
12610 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 at memory so.**
12620 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 that it might be
12630 20 72 65 75 73 65 64 2e 20 20 54 68 65 20 73 71 reused. The sq
12640 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 lite3_free() rou
12650 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d tine is.** a no-
12660 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 op if is called
12670 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e with a NULL poin
12680 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 ter. Passing a
12690 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
126a0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 to sqlite3_free(
126b0 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 ) is harmless.
126c0 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 After being free
126d0 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f d, memory.** sho
126e0 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 uld neither be r
126f0 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e ead nor written.
12700 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 Even reading p
12710 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a reviously freed.
12720 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 ** memory might
12730 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d result in a segm
12740 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f entation fault o
12750 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 r other severe e
12760 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 rror..** Memory
12770 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 corruption, a se
12780 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 gmentation fault
12790 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 , or other sever
127a0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 e error.** might
127b0 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 result if sqlit
127c0 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c e3_free() is cal
127d0 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e led with a non-N
127e0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 ULL pointer that
127f0 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 .** was not obta
12800 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 ined from sqlite
12810 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 3_malloc() or sq
12820 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e lite3_realloc().
12830 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
12840 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 e3_realloc() int
12850 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 erface attempts
12860 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 to resize a.** p
12870 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f rior memory allo
12880 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 cation to be at
12890 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 least N bytes, w
128a0 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a here N is the.**
128b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
128c0 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 r. The memory a
128d0 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 llocation to be
128e0 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 resized is the f
128f0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 irst.** paramete
12900 72 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74 r. If the first
12910 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
12920 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a lite3_realloc().
12930 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 ** is a NULL poi
12940 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 nter then its be
12950 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 havior is identi
12960 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a cal to calling.*
12970 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
12980 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 (N) where N is t
12990 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
129a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
129b0 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 ealloc()..** If
129c0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
129d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
129e0 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 realloc() is zer
129f0 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 o or.** negative
12a00 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
12a10 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 or is exactly th
12a20 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e e same as callin
12a30 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 g.** sqlite3_fre
12a40 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 e(P) where P is
12a50 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
12a60 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
12a70 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c ealloc()..** sql
12a80 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 ite3_realloc() r
12a90 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
12aa0 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c to a memory all
12ab0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 ocation.** of at
12ac0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 least N bytes i
12ad0 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 n size or NULL i
12ae0 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d f sufficient mem
12af0 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 ory is unavailab
12b00 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 le..** If M is t
12b10 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 he size of the p
12b20 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c rior allocation,
12b30 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 then min(N,M) b
12b40 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 ytes.** of the p
12b50 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
12b60 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 are copied into
12b70 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 the beginning of
12b80 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 buffer returned
12b90 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 .** by sqlite3_r
12ba0 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 ealloc() and the
12bb0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
12bc0 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 n is freed..** I
12bd0 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f f sqlite3_reallo
12be0 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c c() returns NULL
12bf0 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 , then the prior
12c00 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 allocation.** i
12c10 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a s not freed..**.
12c20 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 ** The memory re
12c30 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
12c40 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 3_malloc() and s
12c50 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
12c60 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c .** is always al
12c70 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 igned to at leas
12c80 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e t an 8 byte boun
12c90 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a dary. {END}.**.*
12ca0 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d * The default im
12cb0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
12cc0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 the memory alloc
12cd0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 ation subsystem
12ce0 75 73 65 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c uses.** the mall
12cf0 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 oc(), realloc()
12d00 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76 69 and free() provi
12d10 64 65 64 20 62 79 20 74 68 65 20 73 74 61 6e 64 ded by the stand
12d20 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a ard C library..*
12d30 2a 20 7b 48 31 37 33 38 32 7d 20 48 6f 77 65 76 * {H17382} Howev
12d40 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 er, if SQLite is
12d50 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
12d60 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d he.** SQLITE_MEM
12d70 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c ORY_SIZE=<i>NNN<
12d80 2f 69 3e 20 43 20 70 72 65 70 72 6f 63 65 73 73 /i> C preprocess
12d90 6f 72 20 6d 61 63 72 6f 20 28 77 68 65 72 65 20 or macro (where
12da0 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 <i>NNN</i>.** is
12db0 20 61 6e 20 69 6e 74 65 67 65 72 29 2c 20 74 68 an integer), th
12dc0 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74 65 en SQLite create
12dd0 20 61 20 73 74 61 74 69 63 20 61 72 72 61 79 20 a static array
12de0 6f 66 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c of at least.** <
12df0 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 i>NNN</i> bytes
12e00 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65 73 in size and uses
12e10 20 74 68 61 74 20 61 72 72 61 79 20 66 6f 72 20 that array for
12e20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d all of its dynam
12e30 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c ic.** memory all
12e40 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b ocation needs. {
12e50 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c END} Additional
12e60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
12e70 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 r options.** may
12e80 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
12e90 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a ure releases..**
12ea0 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 .** In SQLite ve
12eb0 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 rsion 3.5.0 and
12ec0 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 3.5.1, it was po
12ed0 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 ssible to define
12ee0 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f .** the SQLITE_O
12ef0 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 MIT_MEMORY_ALLOC
12f00 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c ATION which woul
12f10 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c d cause the buil
12f20 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e t-in.** implemen
12f30 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 tation of these
12f40 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f routines to be o
12f50 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 mitted. That ca
12f60 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e pability.** is n
12f70 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 o longer provide
12f80 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 d. Only built-i
12f90 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
12fa0 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e ors can be used.
12fb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f .**.** The Windo
12fc0 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 ws OS interface
12fd0 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 layer calls.** t
12fe0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 he system malloc
12ff0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 () and free() di
13000 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 rectly when conv
13010 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 erting.** filena
13020 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 mes between the
13030 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 UTF-8 encoding u
13040 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a sed by SQLite.**
13050 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 and whatever fi
13060 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 lename encoding
13070 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 is used by the p
13080 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 articular Window
13090 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f s.** installatio
130a0 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 n. Memory alloc
130b0 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 ation errors are
130c0 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a detected, but.*
130d0 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 * they are repor
130e0 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c ted back as [SQL
130f0 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 ITE_CANTOPEN] or
13100 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 .** [SQLITE_IOER
13110 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b R] rather than [
13120 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a SQLITE_NOMEM]..*
13130 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
13140 73 3a 0a 2a 2a 20 5b 48 31 37 33 30 33 5d 20 5b s:.** [H17303] [
13150 48 31 37 33 30 34 5d 20 5b 48 31 37 33 30 35 5d H17304] [H17305]
13160 20 5b 48 31 37 33 30 36 5d 20 5b 48 31 37 33 31 [H17306] [H1731
13170 30 5d 20 5b 48 31 37 33 31 32 5d 20 5b 48 31 37 0] [H17312] [H17
13180 33 31 35 5d 20 5b 48 31 37 33 31 38 5d 0a 2a 2a 315] [H17318].**
13190 20 5b 48 31 37 33 32 31 5d 20 5b 48 31 37 33 32 [H17321] [H1732
131a0 32 5d 20 5b 48 31 37 33 32 33 5d 0a 2a 2a 0a 2a 2] [H17323].**.*
131b0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 * The pointer ar
131c0 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 guments to [sqli
131d0 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 te3_free()] and
131e0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
131f0 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 ()].** must be e
13200 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c ither NULL or el
13210 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 se pointers obta
13220 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f ined from a prio
13230 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 r.** invocation
13240 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c of [sqlite3_mall
13250 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 oc()] or [sqlite
13260 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 3_realloc()] tha
13270 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 t have.** not ye
13280 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e t been released.
13290 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 .**.** The appli
132a0 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 cation must not
132b0 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e read or write an
132c0 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 y part of.** a b
132d0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 lock of memory a
132e0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e fter it has been
132f0 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a released using.
13300 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
13310 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
13320 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 realloc()]..*/.v
13330 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c oid *sqlite3_mal
13340 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a loc(int);.void *
13350 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
13360 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 void*, int);.voi
13370 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 d sqlite3_free(v
13380 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
13390 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 PI3REF: Memory A
133a0 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 llocator Statist
133b0 69 63 73 20 7b 48 31 37 33 37 30 7d 20 3c 53 33 ics {H17370} <S3
133c0 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 0210>.**.** SQLi
133d0 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 te provides thes
133e0 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 e two interfaces
133f0 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f for reporting o
13400 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 n the status.**
13410 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
13420 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 malloc()], [sqli
13430 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 te3_free()], and
13440 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
13450 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 c()].** routines
13460 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 , which form the
13470 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 built-in memory
13480 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 allocation subs
13490 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 ystem..**.** Req
134a0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
134b0 31 37 33 37 31 5d 20 5b 48 31 37 33 37 33 5d 20 17371] [H17373]
134c0 5b 48 31 37 33 37 34 5d 20 5b 48 31 37 33 37 35 [H17374] [H17375
134d0 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 ].*/.sqlite3_int
134e0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 64 sqlite3_memor
134f0 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 y_used(void);.sq
13500 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
13510 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
13520 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c ater(int resetFl
13530 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ag);../*.** CAPI
13540 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 3REF: Pseudo-Ran
13550 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 dom Number Gener
13560 61 74 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 ator {H17390} <S
13570 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 20000>.**.** SQL
13580 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 ite contains a h
13590 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 igh-quality pseu
135a0 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 do-random number
135b0 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 generator (PRNG
135c0 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c ) used to.** sel
135d0 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 ect random [ROWI
135e0 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e D | ROWIDs] when
135f0 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 inserting new r
13600 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 ecords into a ta
13610 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 ble that.** alre
13620 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 ady uses the lar
13630 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 gest possible [R
13640 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 OWID]. The PRNG
13650 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f is also used fo
13660 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 r.** the build-i
13670 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 n random() and r
13680 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 andomblob() SQL
13690 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 functions. This
136a0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 interface allow
136b0 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e s.** application
136c0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 s to access the
136d0 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 same PRNG for ot
136e0 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a her purposes..**
136f0 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 .** A call to th
13700 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 is routine store
13710 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e s N bytes of ran
13720 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 domness into buf
13730 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 fer P..**.** The
13740 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 first time this
13750 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f routine is invo
13760 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 ked (either inte
13770 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 rnally or by.**
13780 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 the application)
13790 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 the PRNG is see
137a0 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d ded using random
137b0 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a ness obtained.**
137c0 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f from the xRando
137d0 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 mness method of
137e0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c the default [sql
137f0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
13800 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 ..** On all subs
13810 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f equent invocatio
13820 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 ns, the pseudo-r
13830 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e andomness is gen
13840 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e erated.** intern
13850 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 ally and without
13860 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 recourse to the
13870 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 [sqlite3_vfs] x
13880 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 Randomness.** me
13890 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 thod..**.** Requ
138a0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
138b0 37 33 39 32 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 7392].*/.void sq
138c0 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 lite3_randomness
138d0 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 (int N, void *P)
138e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
138f0 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 F: Compile-Time
13900 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 Authorization Ca
13910 6c 6c 62 61 63 6b 73 20 7b 48 31 32 35 30 30 7d llbacks {H12500}
13920 20 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S70100>.**.**
13930 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 This routine reg
13940 69 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 isters a authori
13950 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 zer callback wit
13960 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a h a particular.*
13970 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
13980 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 ection], supplie
13990 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 d in the first a
139a0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 rgument..** The
139b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
139c0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 ack is invoked a
139d0 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 s SQL statements
139e0 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 are being compi
139f0 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 led.** by [sqlit
13a00 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
13a10 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 its variants [s
13a20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
13a30 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 2()],.** [sqlite
13a40 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 3_prepare16()] a
13a50 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
13a60 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 are16_v2()]. At
13a70 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e various.** poin
13a80 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f ts during the co
13a90 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 mpilation proces
13aa0 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 s, as logic is b
13ab0 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 eing created.**
13ac0 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f to perform vario
13ad0 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 us actions, the
13ae0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
13af0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 ack is invoked t
13b00 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 o.** see if thos
13b10 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c e actions are al
13b20 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74 68 lowed. The auth
13b30 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
13b40 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e should.** return
13b50 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 [SQLITE_OK] to
13b60 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e allow the action
13b70 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 , [SQLITE_IGNORE
13b80 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 ] to disallow th
13b90 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 e.** specific ac
13ba0 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 tion but allow t
13bb0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
13bc0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 to continue to
13bd0 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 be.** compiled,
13be0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d or [SQLITE_DENY]
13bf0 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e to cause the en
13c00 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 tire SQL stateme
13c10 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 nt to be.** reje
13c20 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 cted with an err
13c30 6f 72 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 or. If the auth
13c40 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
13c50 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 returns.** any v
13c60 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 alue other than
13c70 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c [SQLITE_IGNORE],
13c80 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 [SQLITE_OK], or
13c90 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a [SQLITE_DENY].*
13ca0 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 * then the [sqli
13cb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
13cc0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 ] or equivalent
13cd0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 call that trigge
13ce0 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f red.** the autho
13cf0 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 rizer will fail
13d00 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 with an error me
13d10 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 ssage..**.** Whe
13d20 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 n the callback r
13d30 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
13d40 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 K], that means t
13d50 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 he operation.**
13d60 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e requested is ok.
13d70 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 When the callb
13d80 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ack returns [SQL
13d90 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a ITE_DENY], the.*
13da0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
13db0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 re_v2()] or equi
13dc0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 valent call that
13dd0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a triggered the.*
13de0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c * authorizer wil
13df0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 l fail with an e
13e00 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 rror message exp
13e10 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 laining that.**
13e20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 access is denied
13e30 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 . If the author
13e40 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b 53 51 izer code is [SQ
13e50 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e LITE_READ].** an
13e60 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 d the callback r
13e70 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 eturns [SQLITE_I
13e80 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a GNORE] then the.
13e90 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
13ea0 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e tement] statemen
13eb0 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 t is constructed
13ec0 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a to substitute.*
13ed0 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 * a NULL value i
13ee0 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 n place of the t
13ef0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 able column that
13f00 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 would have.** b
13f10 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c een read if [SQL
13f20 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e ITE_OK] had been
13f30 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 returned. The
13f40 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a [SQLITE_IGNORE].
13f50 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 ** return can be
13f60 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e used to deny an
13f70 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 untrusted user
13f80 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 access to indivi
13f90 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 dual.** columns
13fa0 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a of a table..**.*
13fb0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 * The first para
13fc0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 meter to the aut
13fd0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
13fe0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 is a copy of th
13ff0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d e third.** param
14000 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
14010 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
14020 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 er() interface.
14030 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
14040 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 eter.** to the c
14050 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e allback is an in
14060 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f teger [SQLITE_CO
14070 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 PY | action code
14080 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 ] that specifies
14090 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c .** the particul
140a0 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 ar action to be
140b0 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 authorized. The
140c0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 third through si
140d0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a xth parameters.*
140e0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 * to the callbac
140f0 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 k are zero-termi
14100 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 nated strings th
14110 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 at contain addit
14120 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 ional.** details
14130 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f about the actio
14140 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a n to be authoriz
14150 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 ed..**.** An aut
14160 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 horizer is used
14170 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 when [sqlite3_pr
14180 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e epare | preparin
14190 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d g].** SQL statem
141a0 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 ents from an unt
141b0 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 rusted source, t
141c0 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 o ensure that th
141d0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
141e0 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 .** do not try t
141f0 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 o access data th
14200 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 ey are not allow
14210 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 ed to see, or th
14220 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a at they do not.*
14230 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 * try to execute
14240 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 malicious state
14250 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 ments that damag
14260 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 e the database.
14270 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c For.** example,
14280 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
14290 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 may allow a user
142a0 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 to enter arbitr
142b0 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 ary.** SQL queri
142c0 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f es for evaluatio
142d0 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e n by a database.
142e0 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 But the applic
142f0 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f ation does.** no
14300 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 t want the user
14310 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 to be able to ma
14320 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 ke arbitrary cha
14330 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 nges to the.** d
14340 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 atabase. An aut
14350 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 horizer could th
14360 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 en be put in pla
14370 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 ce while the.**
14380 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c user-entered SQL
14390 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 is being [sqlit
143a0 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 e3_prepare | pre
143b0 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 pared] that.** d
143c0 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 isallows everyth
143d0 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 ing except [SELE
143e0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a CT] statements..
143f0 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f **.** Applicatio
14400 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 ns that need to
14410 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d process SQL from
14420 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 untrusted sourc
14430 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f es.** might also
14440 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 consider loweri
14450 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 ng resource limi
14460 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ts using [sqlite
14470 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 3_limit()].** an
14480 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 d limiting datab
14490 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 ase size using t
144a0 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 he [max_page_cou
144b0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 nt] [PRAGMA].**
144c0 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 in addition to u
144d0 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a sing an authoriz
144e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 er..**.** Only a
144f0 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a single authoriz
14500 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 er can be in pla
14510 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 ce on a database
14520 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 connection.** a
14530 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 t a time. Each
14540 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
14550 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f set_authorizer o
14560 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 verrides the.**
14570 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 previous call.
14580 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 Disable the auth
14590 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c orizer by instal
145a0 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c ling a NULL call
145b0 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 back..** The aut
145c0 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 horizer is disab
145d0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a led by default..
145e0 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 **.** The author
145f0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 izer callback mu
14600 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 st not do anythi
14610 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 ng that will mod
14620 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 ify.** the datab
14630 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
14640 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
14650 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
14660 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ack..** Note tha
14670 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 t [sqlite3_prepa
14680 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
14690 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f lite3_step()] bo
146a0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a th modify their.
146b0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
146c0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 ections for the
146d0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 meaning of "modi
146e0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 fy" in this para
146f0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 graph..**.** Whe
14700 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 n [sqlite3_prepa
14710 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 re_v2()] is used
14720 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 to prepare a st
14730 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 atement, the.**
14740 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 statement might
14750 62 65 20 72 65 70 72 65 70 61 72 65 64 20 64 75 be reprepared du
14760 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 ring [sqlite3_st
14770 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a ep()] due to a .
14780 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 ** schema change
14790 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 . Hence, the ap
147a0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
147b0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 ensure that the
147c0 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 .** correct auth
147d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
147e0 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 remains in place
147f0 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c during the [sql
14800 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a ite3_step()]..**
14810 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 .** Note that th
14820 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
14830 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
14840 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 only during.**
14850 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
14860 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 ()] or its varia
14870 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 nts. Authorizat
14880 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 ion is not.** pe
14890 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 rformed during s
148a0 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 tatement evaluat
148b0 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f ion in [sqlite3_
148c0 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 step()]..**.** R
148d0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
148e0 5b 48 31 32 35 30 31 5d 20 5b 48 31 32 35 30 32 [H12501] [H12502
148f0 5d 20 5b 48 31 32 35 30 33 5d 20 5b 48 31 32 35 ] [H12503] [H125
14900 30 34 5d 20 5b 48 31 32 35 30 35 5d 20 5b 48 31 04] [H12505] [H1
14910 32 35 30 36 5d 20 5b 48 31 32 35 30 37 5d 20 5b 2506] [H12507] [
14920 48 31 32 35 31 30 5d 0a 2a 2a 20 5b 48 31 32 35 H12510].** [H125
14930 31 31 5d 20 5b 48 31 32 35 31 32 5d 20 5b 48 31 11] [H12512] [H1
14940 32 35 32 30 5d 20 5b 48 31 32 35 32 31 5d 20 5b 2520] [H12521] [
14950 48 31 32 35 32 32 5d 0a 2a 2f 0a 69 6e 74 20 73 H12522].*/.int s
14960 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
14970 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 rizer(. sqlite3
14980 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 *,. int (*xAuth
14990 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
149a0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
149b0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
149c0 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 const char*),.
149d0 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a void *pUserData.
149e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
149f0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 EF: Authorizer R
14a00 65 74 75 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 eturn Codes {H12
14a10 35 39 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 590} <H12500>.**
14a20 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
14a30 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
14a40 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c | authorizer cal
14a50 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 lback function]
14a60 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 must.** return e
14a70 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b ither [SQLITE_OK
14a80 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 ] or one of thes
14a90 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 e two constants
14aa0 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 in order.** to s
14ab0 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 ignal SQLite whe
14ac0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
14ad0 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 action is permit
14ae0 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a ted. See the.**
14af0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
14b00 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f thorizer | autho
14b10 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 rizer documentat
14b20 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f ion] for additio
14b30 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 nal.** informati
14b40 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 on..*/.#define S
14b50 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 QLITE_DENY 1
14b60 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 /* Abort the SQ
14b70 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 L statement with
14b80 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 an error */.#de
14b90 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f fine SQLITE_IGNO
14ba0 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 RE 2 /* Don't
14bb0 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 allow access, bu
14bc0 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 t don't generate
14bd0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a an error */../*
14be0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 .** CAPI3REF: Au
14bf0 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 thorizer Action
14c00 43 6f 64 65 73 20 7b 48 31 32 35 35 30 7d 20 3c Codes {H12550} <
14c10 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 H12500>.**.** Th
14c20 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 e [sqlite3_set_a
14c30 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 uthorizer()] int
14c40 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 erface registers
14c50 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 a callback func
14c60 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 tion.** that is
14c70 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f invoked to autho
14c80 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c rize certain SQL
14c90 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f statement actio
14ca0 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f ns. The.** seco
14cb0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
14cc0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 the callback is
14cd0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 an integer code
14ce0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a that specifies.*
14cf0 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 * what action is
14d00 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 being authorize
14d10 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 d. These are th
14d20 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e e integer action
14d30 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 codes that.** t
14d40 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
14d50 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 llback may be pa
14d60 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ssed..**.** Thes
14d70 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 e action code va
14d80 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 lues signify wha
14d90 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 t kind of operat
14da0 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 ion is to be.**
14db0 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 authorized. The
14dc0 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 3rd and 4th par
14dd0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 ameters to the a
14de0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 uthorization.**
14df0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
14e00 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 n will be parame
14e10 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 ters or NULL dep
14e20 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 ending on which
14e30 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 of these.** code
14e40 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 s is used as the
14e50 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
14e60 72 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 r. The 5th para
14e70 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 meter to the.**
14e80 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
14e90 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 ack is the name
14ea0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
14eb0 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c ("main", "temp",
14ec0 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 .** etc.) if app
14ed0 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 licable. The 6t
14ee0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
14ef0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
14f00 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 llback.** is the
14f10 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e name of the inn
14f20 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 er-most trigger
14f30 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 or view that is
14f40 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a responsible for.
14f50 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 ** the access at
14f60 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 tempt or NULL if
14f70 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 this access att
14f80 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 empt is directly
14f90 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 from.** top-lev
14fa0 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a el SQL code..**.
14fb0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
14fc0 0a 2a 2a 20 5b 48 31 32 35 35 31 5d 20 5b 48 31 .** [H12551] [H1
14fd0 32 35 35 32 5d 20 5b 48 31 32 35 35 33 5d 20 5b 2552] [H12553] [
14fe0 48 31 32 35 35 34 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a H12554].*/./****
14ff0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
15000 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
15010 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a ******* 3rd ****
15020 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a ******** 4th ***
15030 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e ********/.#defin
15040 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
15050 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 INDEX 1
15060 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
15070 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
15080 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
15090 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
150a0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 ABLE 2
150b0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
150c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
150d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
150e0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
150f0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 MP_INDEX 3
15100 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
15110 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
15120 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
15130 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
15140 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 P_TABLE 4
15150 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
15160 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
15170 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
15180 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
15190 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f _TRIGGER 5 /
151a0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
151b0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
151c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
151d0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
151e0 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a VIEW 6 /*
151f0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
15200 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
15210 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
15220 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 TE_CREATE_TRIGGE
15230 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 R 7 /*
15240 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
15250 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
15260 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
15270 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 E_CREATE_VIEW
15280 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 8 /* V
15290 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
152a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
152b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
152c0 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 _DELETE
152d0 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 9 /* Ta
152e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
152f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
15300 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
15310 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 DROP_INDEX
15320 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 10 /* Ind
15330 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
15340 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
15350 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
15360 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 ROP_TABLE
15370 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 11 /* Tabl
15380 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
15390 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
153a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
153b0 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 OP_TEMP_INDEX
153c0 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 12 /* Index
153d0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
153e0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
153f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
15400 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 P_TEMP_TABLE
15410 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 13 /* Table
15420 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
15430 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
15440 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
15450 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 _TEMP_TRIGGER
15460 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 14 /* Trigger
15470 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
15480 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
15490 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
154a0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 TEMP_VIEW
154b0 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 15 /* View Nam
154c0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
154d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
154e0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
154f0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 RIGGER 1
15500 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 6 /* Trigger N
15510 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
15520 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
15530 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 e SQLITE_DROP_VI
15540 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 EW 17
15550 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View Name
15560 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
15570 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
15580 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 SQLITE_INSERT
15590 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 18
155a0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
155b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
155c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
155d0 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 SQLITE_PRAGMA
155e0 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 19
155f0 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 /* Pragma Name
15600 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 1st arg or N
15610 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ULL */.#define S
15620 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 QLITE_READ
15630 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 20
15640 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
15650 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 Column Name
15660 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
15670 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 LITE_SELECT
15680 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 21 /
15690 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 * NULL
156a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
156b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
156c0 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 ITE_TRANSACTION
156d0 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 22 /*
156e0 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 Operation
156f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
15700 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
15710 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 TE_UPDATE
15720 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 23 /*
15730 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
15740 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 Column Name
15750 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
15760 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 E_ATTACH
15770 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 24 /* F
15780 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e ilename N
15790 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
157a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
157b0 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 _DETACH
157c0 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 25 /* Da
157d0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 tabase Name NU
157e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
157f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
15800 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 ALTER_TABLE
15810 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 26 /* Dat
15820 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 abase Name Tab
15830 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
15840 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
15850 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 EINDEX
15860 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 27 /* Inde
15870 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c x Name NULL
15880 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
15890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e define SQLITE_AN
158a0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 ALYZE
158b0 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 28 /* Table
158c0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
158d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
158e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
158f0 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 ATE_VTABLE
15900 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 29 /* Table
15910 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 Name Module
15920 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
15930 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
15940 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 _VTABLE
15950 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 30 /* Table N
15960 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 ame Module
15970 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
15980 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 ine SQLITE_FUNCT
15990 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 ION
159a0 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 31 /* NULL
159b0 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e Function
159c0 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 Name */.#defi
159d0 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f ne SQLITE_SAVEPO
159e0 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 INT 3
159f0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 2 /* Operation
15a00 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 Savepoint
15a10 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e Name */.#defin
15a20 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 e SQLITE_COPY
15a30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
15a40 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 /* No longer
15a50 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 used */../*.** C
15a60 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 API3REF: Tracing
15a70 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 And Profiling F
15a80 75 6e 63 74 69 6f 6e 73 20 7b 48 31 32 32 38 30 unctions {H12280
15a90 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 20 45 58 } <S60400>.** EX
15aa0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
15ab0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
15ac0 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 register callbac
15ad0 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 k functions that
15ae0 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 can be used for
15af0 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 .** tracing and
15b00 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 profiling the ex
15b10 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 ecution of SQL s
15b20 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a tatements..**.**
15b30 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 The callback fu
15b40 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 nction registere
15b50 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 d by sqlite3_tra
15b60 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 ce() is invoked
15b70 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 at.** various ti
15b80 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 mes when an SQL
15b90 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 statement is bei
15ba0 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 ng run by [sqlit
15bb0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 e3_step()]..** T
15bc0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
15bd0 72 6e 73 20 61 20 55 54 46 2d 38 20 72 65 6e 64 rns a UTF-8 rend
15be0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 53 51 4c ering of the SQL
15bf0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 0a statement text.
15c00 2a 2a 20 61 73 20 74 68 65 20 73 74 61 74 65 6d ** as the statem
15c10 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 ent first begins
15c20 20 65 78 65 63 75 74 69 6e 67 2e 20 20 41 64 64 executing. Add
15c30 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b itional callback
15c40 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 s occur.** as ea
15c50 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 ch triggered sub
15c60 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 program is enter
15c70 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 ed. The callbac
15c80 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a ks for triggers.
15c90 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 ** contain a UTF
15ca0 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 -8 SQL comment t
15cb0 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 hat identifies t
15cc0 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a he trigger..**.*
15cd0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 * The callback f
15ce0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
15cf0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 ed by sqlite3_pr
15d00 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b ofile() is invok
15d10 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 ed.** as each SQ
15d20 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 L statement fini
15d30 73 68 65 73 2e 20 20 54 68 65 20 70 72 6f 66 69 shes. The profi
15d40 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 le callback cont
15d50 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 ains.** the orig
15d60 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 inal statement t
15d70 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d ext and an estim
15d80 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 ate of wall-cloc
15d90 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 k time.** of how
15da0 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 long that state
15db0 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e ment took to run
15dc0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
15dd0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 38 31 ents:.** [H12281
15de0 5d 20 5b 48 31 32 32 38 32 5d 20 5b 48 31 32 32 ] [H12282] [H122
15df0 38 33 5d 20 5b 48 31 32 32 38 34 5d 20 5b 48 31 83] [H12284] [H1
15e00 32 32 38 35 5d 20 5b 48 31 32 32 38 37 5d 20 5b 2285] [H12287] [
15e10 48 31 32 32 38 38 5d 20 5b 48 31 32 32 38 39 5d H12288] [H12289]
15e20 0a 2a 2a 20 5b 48 31 32 32 39 30 5d 0a 2a 2f 0a .** [H12290].*/.
15e30 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e SQLITE_EXPERIMEN
15e40 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 TAL void *sqlite
15e50 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 3_trace(sqlite3*
15e60 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 , void(*xTrace)(
15e70 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 void*,const char
15e80 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 *), void*);.SQLI
15e90 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 TE_EXPERIMENTAL
15ea0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 void *sqlite3_pr
15eb0 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a ofile(sqlite3*,.
15ec0 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c void(*xProfil
15ed0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 e)(void*,const c
15ee0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e har*,sqlite3_uin
15ef0 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f t64), void*);../
15f00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 *.** CAPI3REF: Q
15f10 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 uery Progress Ca
15f20 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 31 30 7d llbacks {H12910}
15f30 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S60400>.**.**
15f40 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e This routine con
15f50 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 figures a callba
15f60 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 ck function - th
15f70 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 e.** progress ca
15f80 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 llback - that is
15f90 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 invoked periodi
15fa0 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e cally during lon
15fb0 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c g.** running cal
15fc0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 ls to [sqlite3_e
15fd0 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 xec()], [sqlite3
15fe0 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 _step()] and.**
15ff0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 [sqlite3_get_tab
16000 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 le()]. An examp
16010 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a le use for this.
16020 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
16030 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 to keep a GUI up
16040 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c dated during a l
16050 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a arge query..**.*
16060 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 * If the progres
16070 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 s callback retur
16080 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 ns non-zero, the
16090 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a operation is.**
160a0 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 interrupted. T
160b0 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 his feature can
160c0 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 be used to imple
160d0 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 ment a.** "Cance
160e0 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 l" button on a G
160f0 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c UI progress dial
16100 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 og box..**.** Th
16110 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
16120 65 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 er must not do a
16130 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c nything that wil
16140 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 l modify.** the
16150 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
16160 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 ion that invoked
16170 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 the progress ha
16180 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 ndler..** Note t
16190 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hat [sqlite3_pre
161a0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b pare_v2()] and [
161b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
161c0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 both modify thei
161d0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f r.** database co
161e0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 nnections for th
161f0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f e meaning of "mo
16200 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 dify" in this pa
16210 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 ragraph..**.** R
16220 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
16230 5b 48 31 32 39 31 31 5d 20 5b 48 31 32 39 31 32 [H12911] [H12912
16240 5d 20 5b 48 31 32 39 31 33 5d 20 5b 48 31 32 39 ] [H12913] [H129
16250 31 34 5d 20 5b 48 31 32 39 31 35 5d 20 5b 48 31 14] [H12915] [H1
16260 32 39 31 36 5d 20 5b 48 31 32 39 31 37 5d 20 5b 2916] [H12917] [
16270 48 31 32 39 31 38 5d 0a 2a 2a 0a 2a 2f 0a 76 6f H12918].**.*/.vo
16280 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 id sqlite3_progr
16290 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 ess_handler(sqli
162a0 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a te3*, int, int(*
162b0 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 )(void*), void*)
162c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
162d0 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 F: Opening A New
162e0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
162f0 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d 20 3c 53 tion {H12700} <S
16300 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 40200>.**.** The
16310 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e se routines open
16320 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 an SQLite datab
16330 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e ase file whose n
16340 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 ame is given by
16350 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 the.** filename
16360 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 66 69 argument. The fi
16370 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 lename argument
16380 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
16390 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 s UTF-8 for.** s
163a0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e qlite3_open() an
163b0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 d sqlite3_open_v
163c0 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 2() and as UTF-1
163d0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 6 in the native
163e0 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f byte.** order fo
163f0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 r sqlite3_open16
16400 28 29 2e 20 41 20 5b 64 61 74 61 62 61 73 65 20 (). A [database
16410 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 connection] hand
16420 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a le is usually.**
16430 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 returned in *pp
16440 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 Db, even if an e
16450 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 rror occurs. Th
16460 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e e only exception
16470 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 is that.** if S
16480 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 QLite is unable
16490 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f to allocate memo
164a0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b ry to hold the [
164b0 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c sqlite3] object,
164c0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 .** a NULL will
164d0 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 be written into
164e0 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 *ppDb instead of
164f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
16500 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f e [sqlite3].** o
16510 62 6a 65 63 74 2e 20 49 66 20 74 68 65 20 64 61 bject. If the da
16520 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
16530 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 (and/or created
16540 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 ) successfully,
16550 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f then.** [SQLITE_
16560 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e OK] is returned.
16570 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b Otherwise an [
16580 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
16590 65 74 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a eturned. The.**
165a0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
165b0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
165c0 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 errmsg16()] rout
165d0 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 ines can be used
165e0 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e to obtain.** an
165f0 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 English languag
16600 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 e description of
16610 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a the error..**.*
16620 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e * The default en
16630 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 coding for the d
16640 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 atabase will be
16650 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 UTF-8 if.** sqli
16660 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 te3_open() or sq
16670 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
16680 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a is called and.**
16690 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e UTF-16 in the n
166a0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
166b0 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e if sqlite3_open
166c0 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 16() is used..**
166d0 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e .** Whether or n
166e0 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 ot an error occu
166f0 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 rs when it is op
16700 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a ened, resources.
16710 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ** associated wi
16720 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 th the [database
16730 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e connection] han
16740 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 dle should be re
16750 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 leased by.** pas
16760 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 sing it to [sqli
16770 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 te3_close()] whe
16780 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 n it is no longe
16790 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a r required..**.*
167a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 * The sqlite3_op
167b0 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 en_v2() interfac
167c0 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c e works like sql
167d0 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 ite3_open().** e
167e0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 xcept that it ac
167f0 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 cepts two additi
16800 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 onal parameters
16810 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 for additional c
16820 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 ontrol.** over t
16830 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 he new database
16840 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 connection. The
16850 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
16860 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 can take one of
16870 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e .** the followin
16880 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 g three values,
16890 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 optionally combi
168a0 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a ned with the .**
168b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f [SQLITE_OPEN_NO
168c0 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 MUTEX] or [SQLIT
168d0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 E_OPEN_FULLMUTEX
168e0 5d 20 66 6c 61 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c ] flags:.**.** <
168f0 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 dl>.** <dt>[SQLI
16900 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
16910 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 ]</dt>.** <dd>Th
16920 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
16930 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c ened in read-onl
16940 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 y mode. If the
16950 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f database does no
16960 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 t.** already exi
16970 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 st, an error is
16980 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a returned.</dd>.*
16990 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 *.** <dt>[SQLITE
169a0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d _OPEN_READWRITE]
169b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
169c0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
169d0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 ned for reading
169e0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 and writing if p
169f0 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 ossible, or read
16a00 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 ing.** only if t
16a10 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 he file is write
16a20 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 protected by th
16a30 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
16a40 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a em. In either.*
16a50 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 * case the datab
16a60 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 ase must already
16a70 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 exist, otherwis
16a80 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 e an error is re
16a90 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a turned.</dd>.**.
16aa0 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f ** <dt>[SQLITE_O
16ab0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c PEN_READWRITE] |
16ac0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
16ad0 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 EATE]</dt>.** <d
16ae0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 d>The database i
16af0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
16b00 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 ding and writing
16b10 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 73 , and is creates
16b20 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 it if.** it doe
16b30 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 s not already ex
16b40 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 ist. This is the
16b50 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 behavior that i
16b60 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f s always used fo
16b70 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 r.** sqlite3_ope
16b80 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
16b90 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a open16().</dd>.*
16ba0 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 * </dl>.**.** If
16bb0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 the 3rd paramet
16bc0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 er to sqlite3_op
16bd0 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f en_v2() is not o
16be0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d ne of the.** com
16bf0 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 binations shown
16c00 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 above or one of
16c10 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 the combinations
16c20 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d shown above com
16c30 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 bined.** with th
16c40 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e e [SQLITE_OPEN_N
16c50 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49 OMUTEX] or [SQLI
16c60 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 TE_OPEN_FULLMUTE
16c70 58 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 X] flags,.** the
16c80 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
16c90 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
16ca0 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54 ** If the [SQLIT
16cb0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 E_OPEN_NOMUTEX]
16cc0 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 flag is set, the
16cd0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
16ce0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 onnection.** ope
16cf0 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d ns in the multi-
16d00 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e thread [threadin
16d10 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 g mode] as long
16d20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 as the single-th
16d30 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 read.** mode has
16d40 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 not been set at
16d50 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 compile-time or
16d60 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 49 66 start-time. If
16d70 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
16d80 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 OPEN_FULLMUTEX]
16d90 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e flag is set then
16da0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
16db0 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a nnection opens.*
16dc0 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 * in the seriali
16dd0 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d zed [threading m
16de0 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 ode] unless sing
16df0 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a le-thread was.**
16e00 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 previously sele
16e10 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d cted at compile-
16e20 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 time or start-ti
16e30 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 me..**.** If the
16e40 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d filename is ":m
16e50 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 emory:", then a
16e60 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 private, tempora
16e70 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 ry in-memory dat
16e80 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 abase.** is crea
16e90 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e ted for the conn
16ea0 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e ection. This in
16eb0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 -memory database
16ec0 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 will vanish whe
16ed0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 n.** the databas
16ee0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
16ef0 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 closed. Future
16f00 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
16f10 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 te might.** make
16f20 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e use of addition
16f30 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e al special filen
16f40 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 ames that begin
16f50 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 with the ":" cha
16f60 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 racter..** It is
16f70 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 recommended tha
16f80 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 t when a databas
16f90 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 e filename actua
16fa0 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 lly does begin w
16fb0 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 ith.** a ":" cha
16fc0 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c racter you shoul
16fd0 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c d prefix the fil
16fe0 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 ename with a pat
16ff0 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a hname such as.**
17000 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 "./" to avoid a
17010 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 mbiguity..**.**
17020 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 If the filename
17030 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 is an empty stri
17040 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 ng, then a priva
17050 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a te, temporary.**
17060 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 on-disk databas
17070 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 e will be create
17080 64 2e 20 20 54 68 69 73 20 70 72 69 76 61 74 65 d. This private
17090 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 database will b
170a0 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c e.** automatical
170b0 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f ly deleted as so
170c0 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 on as the databa
170d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
170e0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 closed..**.** T
170f0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
17100 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f ter to sqlite3_o
17110 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 pen_v2() is the
17120 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b name of the.** [
17130 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
17140 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 ect that defines
17150 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
17160 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 ystem interface
17170 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 that.** the new
17180 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
17190 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 ion should use.
171a0 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 If the fourth p
171b0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 arameter is.** a
171c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
171d0 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b en the default [
171e0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
171f0 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a ect is used..**.
17200 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 ** <b>Note to Wi
17210 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e ndows users:</b>
17220 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 The encoding u
17230 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 sed for the file
17240 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a name argument.**
17250 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e of sqlite3_open
17260 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
17270 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 pen_v2() must be
17280 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 UTF-8, not what
17290 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 ever.** codepage
172a0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 is currently de
172b0 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 fined. Filename
172c0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 s containing int
172d0 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 ernational.** ch
172e0 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 aracters must be
172f0 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 converted to UT
17300 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 F-8 prior to pas
17310 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a sing them into.*
17320 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
17330 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e or sqlite3_open
17340 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 _v2()..**.** Req
17350 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
17360 31 32 37 30 31 5d 20 5b 48 31 32 37 30 32 5d 20 12701] [H12702]
17370 5b 48 31 32 37 30 33 5d 20 5b 48 31 32 37 30 34 [H12703] [H12704
17380 5d 20 5b 48 31 32 37 30 36 5d 20 5b 48 31 32 37 ] [H12706] [H127
17390 30 37 5d 20 5b 48 31 32 37 30 39 5d 20 5b 48 31 07] [H12709] [H1
173a0 32 37 31 31 5d 0a 2a 2a 20 5b 48 31 32 37 31 32 2711].** [H12712
173b0 5d 20 5b 48 31 32 37 31 33 5d 20 5b 48 31 32 37 ] [H12713] [H127
173c0 31 34 5d 20 5b 48 31 32 37 31 37 5d 20 5b 48 31 14] [H12717] [H1
173d0 32 37 31 39 5d 20 5b 48 31 32 37 32 31 5d 20 5b 2719] [H12721] [
173e0 48 31 32 37 32 33 5d 0a 2a 2f 0a 69 6e 74 20 73 H12723].*/.int s
173f0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 qlite3_open(. c
17400 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e onst char *filen
17410 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 ame, /* Databa
17420 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 se filename (UTF
17430 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 -8) */. sqlite3
17440 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 **ppDb
17450 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
17460 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a db handle */.);.
17470 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e int sqlite3_open
17480 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 16(. const void
17490 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a *filename, /*
174a0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 Database filena
174b0 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 me (UTF-16) */.
174c0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 sqlite3 **ppDb
174d0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a /* OUT:
174e0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c SQLite db handl
174f0 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 e */.);.int sqli
17500 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 te3_open_v2(. c
17510 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e onst char *filen
17520 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 ame, /* Databa
17530 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 se filename (UTF
17540 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 -8) */. sqlite3
17550 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 **ppDb,
17560 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
17570 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 db handle */. i
17580 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 nt flags,
17590 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 /* Flags
175a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
175b0 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 *zVfs /*
175c0 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 Name of VFS modu
175d0 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a le to use */.);.
175e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
175f0 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 Error Codes And
17600 20 4d 65 73 73 61 67 65 73 20 7b 48 31 32 38 30 Messages {H1280
17610 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 0} <S60200>.**.*
17620 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 * The sqlite3_er
17630 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 rcode() interfac
17640 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 e returns the nu
17650 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f meric [result co
17660 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e de] or.** [exten
17670 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d ded result code]
17680 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 for the most re
17690 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 cent failed sqli
176a0 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a te3_* API call.*
176b0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
176c0 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f h a [database co
176d0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 nnection]. If a
176e0 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 prior API call f
176f0 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 ailed.** but the
17700 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 most recent API
17710 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c call succeeded,
17720 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
17730 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 e from.** sqlite
17740 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 3_errcode() is u
17750 6e 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20 73 ndefined. The s
17760 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
17770 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 errcode().** int
17780 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 erface is the sa
17790 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 me except that i
177a0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 t always returns
177b0 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 the .** [extend
177c0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 ed result code]
177d0 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 even when extend
177e0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 ed result codes
177f0 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e are.** disabled.
17800 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
17810 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 e3_errmsg() and
17820 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
17830 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 () return Englis
17840 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 h-language.** te
17850 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 xt that describe
17860 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 s the error, as
17870 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
17880 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 UTF-16 respectiv
17890 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 ely..** Memory t
178a0 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 o hold the error
178b0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 message string
178c0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 is managed inter
178d0 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 nally..** The ap
178e0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e plication does n
178f0 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 ot need to worry
17900 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 about freeing t
17910 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f he result..** Ho
17920 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 wever, the error
17930 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 string might be
17940 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 overwritten or
17950 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a deallocated by.*
17960 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c * subsequent cal
17970 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 ls to other SQLi
17980 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e te interface fun
17990 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 ctions..**.** Wh
179a0 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 en the serialize
179b0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 d [threading mod
179c0 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 e] is in use, it
179d0 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a might be the.**
179e0 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 case that a sec
179f0 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 ond error occurs
17a00 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 on a separate t
17a10 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e hread in between
17a20 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 .** the time of
17a30 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 the first error
17a40 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 and the call to
17a50 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 these interfaces
17a60 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 ..** When that h
17a70 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f appens, the seco
17a80 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 nd error will be
17a90 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 reported since
17aa0 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 these.** interfa
17ab0 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 ces always repor
17ac0 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e t the most recen
17ad0 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 t result. To av
17ae0 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 oid.** this, eac
17af0 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 h thread can obt
17b00 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 ain exclusive us
17b10 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 e of the [databa
17b20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
17b30 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 .** by invoking
17b40 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 [sqlite3_mutex_e
17b50 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 nter]([sqlite3_d
17b60 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 b_mutex](D)) bef
17b70 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a ore beginning.**
17b80 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e to use D and in
17b90 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f voking [sqlite3_
17ba0 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 mutex_leave]([sq
17bb0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 lite3_db_mutex](
17bc0 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c D)) after.** all
17bd0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e calls to the in
17be0 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 terfaces listed
17bf0 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 here are complet
17c00 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 ed..**.** If an
17c10 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 interface fails
17c20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 with SQLITE_MISU
17c30 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 SE, that means t
17c40 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 he interface.**
17c50 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f was invoked inco
17c60 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 rrectly by the a
17c70 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 pplication. In
17c80 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a that case, the.*
17c90 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 * error code and
17ca0 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 message may or
17cb0 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a may not be set..
17cc0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
17cd0 74 73 3a 0a 2a 2a 20 5b 48 31 32 38 30 31 5d 20 ts:.** [H12801]
17ce0 5b 48 31 32 38 30 32 5d 20 5b 48 31 32 38 30 33 [H12802] [H12803
17cf0 5d 20 5b 48 31 32 38 30 37 5d 20 5b 48 31 32 38 ] [H12807] [H128
17d00 30 38 5d 20 5b 48 31 32 38 30 39 5d 0a 2a 2f 0a 08] [H12809].*/.
17d10 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 int sqlite3_errc
17d20 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 ode(sqlite3 *db)
17d30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 ;.int sqlite3_ex
17d40 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 tended_errcode(s
17d50 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e qlite3 *db);.con
17d60 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
17d70 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a _errmsg(sqlite3*
17d80 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
17d90 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
17da0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
17db0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 * CAPI3REF: SQL
17dc0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
17dd0 20 7b 48 31 33 30 30 30 7d 20 3c 48 31 33 30 31 {H13000} <H1301
17de0 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 0>.** KEYWORDS:
17df0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d {prepared statem
17e00 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 ent} {prepared s
17e10 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a tatements}.**.**
17e20 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
17e30 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 this object repr
17e40 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 esents a single
17e50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a SQL statement..*
17e60 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 * This object is
17e70 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e variously known
17e80 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 as a "prepared
17e90 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a statement" or a.
17ea0 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c ** "compiled SQL
17eb0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 statement" or s
17ec0 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 imply as a "stat
17ed0 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 ement"..**.** Th
17ee0 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 e life of a stat
17ef0 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 ement object goe
17f00 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 s something like
17f10 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c this:.**.** <ol
17f20 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 >.** <li> Create
17f30 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e the object usin
17f40 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
17f50 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 re_v2()] or a re
17f60 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 lated.** fu
17f70 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 nction..** <li>
17f80 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b Bind values to [
17f90 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d host parameters]
17fa0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 using the sqlit
17fb0 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 e3_bind_*().**
17fc0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a interfaces..
17fd0 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 ** <li> Run the
17fe0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b SQL by calling [
17ff0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
18000 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 one or more time
18010 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 s..** <li> Reset
18020 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 the statement u
18030 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 sing [sqlite3_re
18040 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 set()] then go b
18050 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 ack.** to s
18060 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 tep 2. Do this
18070 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d zero or more tim
18080 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 es..** <li> Dest
18090 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 roy the object u
180a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 sing [sqlite3_fi
180b0 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f nalize()]..** </
180c0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 ol>.**.** Refer
180d0 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e to documentation
180e0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d on individual m
180f0 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 ethods above for
18100 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 additional.** i
18110 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 nformation..*/.t
18120 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
18130 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 lite3_stmt sqlit
18140 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 e3_stmt;../*.**
18150 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 CAPI3REF: Run-ti
18160 6d 65 20 4c 69 6d 69 74 73 20 7b 48 31 32 37 36 me Limits {H1276
18170 30 7d 20 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 0} <S20600>.**.*
18180 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
18190 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 allows the size
181a0 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 of various cons
181b0 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d tructs to be lim
181c0 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e ited.** on a con
181d0 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 nection by conne
181e0 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 ction basis. Th
181f0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
18200 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 r is the.** [dat
18210 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
18220 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 ] whose limit is
18230 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 to be set or qu
18240 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 eried. The.** s
18250 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
18260 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c is one of the [l
18270 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d imit categories]
18280 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a that define a.*
18290 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 * class of const
182a0 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 ructs to be size
182b0 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 limited. The t
182c0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 hird parameter i
182d0 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d s the.** new lim
182e0 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 it for that cons
182f0 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 truct. The func
18300 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
18310 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a old limit..**.*
18320 2a 20 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d * If the new lim
18330 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 it is a negative
18340 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d number, the lim
18350 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e it is unchanged.
18360 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 .** For the limi
18370 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51 t category of SQ
18380 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 LITE_LIMIT_XYZ t
18390 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c here is a .** [l
183a0 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 imits | hard upp
183b0 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 er bound].** set
183c0 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 by a compile-ti
183d0 6d 65 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f me C preprocesso
183e0 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 0a 2a r macro named .*
183f0 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 * [limits | SQLI
18400 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 TE_MAX_XYZ]..**
18410 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 (The "_LIMIT_" i
18420 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 n the name is ch
18430 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 anged to "_MAX_"
18440 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 .).** Attempts t
18450 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d o increase a lim
18460 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 it above its har
18470 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 d upper bound ar
18480 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 e.** silently tr
18490 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 uncated to the h
184a0 61 72 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e ard upper limit.
184b0 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 .**.** Run time
184c0 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e limits are inten
184d0 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 ded for use in a
184e0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
184f0 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 manage.** both
18500 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e their own intern
18510 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 al database and
18520 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 also databases t
18530 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c hat are controll
18540 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 ed.** by untrust
18550 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 ed external sour
18560 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 ces. An example
18570 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 application mig
18580 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 ht be a.** web b
18590 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 rowser that has
185a0 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 its own database
185b0 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 s for storing hi
185c0 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 story and.** sep
185d0 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 arate databases
185e0 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 controlled by Ja
185f0 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 vaScript applica
18600 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 tions downloaded
18610 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 .** off the Inte
18620 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 rnet. The inter
18630 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 nal databases ca
18640 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a n be given the.*
18650 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 * large, default
18660 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 limits. Databa
18670 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 ses managed by e
18680 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 xternal sources
18690 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 can.** be given
186a0 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d much smaller lim
186b0 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 its designed to
186c0 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c prevent a denial
186d0 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 of service.** a
186e0 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 ttack. Develope
186f0 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 rs might also wa
18700 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 nt to use the [s
18710 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
18720 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 rizer()].** inte
18730 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 rface to further
18740 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 control untrust
18750 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a ed SQL. The siz
18760 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
18770 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 e.** created by
18780 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 an untrusted scr
18790 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 ipt can be conta
187a0 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a ined using the.*
187b0 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e * [max_page_coun
187c0 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a t] [PRAGMA]..**.
187d0 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 ** New run-time
187e0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 limit categories
187f0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
18800 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
18810 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
18820 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 36 32 ents:.** [H12762
18830 5d 20 5b 48 31 32 37 36 36 5d 20 5b 48 31 32 37 ] [H12766] [H127
18840 36 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 69].*/.int sqlit
18850 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 e3_limit(sqlite3
18860 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e *, int id, int n
18870 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ewVal);../*.** C
18880 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d API3REF: Run-Tim
18890 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 e Limit Categori
188a0 65 73 20 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 es {H12790} <H12
188b0 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 760>.** KEYWORDS
188c0 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 : {limit categor
188d0 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f y} {limit catego
188e0 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ries}.**.** Thes
188f0 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 e constants defi
18900 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f ne various perfo
18910 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a rmance limits.**
18920 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 that can be low
18930 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 ered at run-time
18940 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
18950 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 limit()]..** The
18960 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 synopsis of the
18970 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 meanings of the
18980 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 various limits
18990 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a is shown below..
189a0 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e ** Additional in
189b0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 formation is ava
189c0 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 ilable at [limit
189d0 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 s | Limits in SQ
189e0 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c Lite]..**.** <dl
189f0 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f >.** <dt>SQLITE_
18a00 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 LIMIT_LENGTH</dt
18a10 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
18a20 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 imum size of any
18a30 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 string or BLOB
18a40 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 or table row.<dd
18a50 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
18a60 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e TE_LIMIT_SQL_LEN
18a70 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e GTH</dt>.** <dd>
18a80 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 The maximum leng
18a90 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 th of an SQL sta
18aa0 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a tement.</dd>.**.
18ab0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ** <dt>SQLITE_LI
18ac0 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a MIT_COLUMN</dt>.
18ad0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
18ae0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c um number of col
18af0 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 umns in a table
18b00 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e definition or in
18b10 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 the.** result s
18b20 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d et of a [SELECT]
18b30 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 or the maximum
18b40 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
18b50 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a s in an index.**
18b60 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 or in an ORDER
18b70 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 BY or GROUP BY c
18b80 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a lause.</dd>.**.*
18b90 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d * <dt>SQLITE_LIM
18ba0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 IT_EXPR_DEPTH</d
18bb0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
18bc0 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 ximum depth of t
18bd0 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e he parse tree on
18be0 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e any expression.
18bf0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
18c00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d SQLITE_LIMIT_COM
18c10 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 POUND_SELECT</dt
18c20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
18c30 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 imum number of t
18c40 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 erms in a compou
18c50 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d nd SELECT statem
18c60 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ent.</dd>.**.**
18c70 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
18c80 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a _VDBE_OP</dt>.**
18c90 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
18ca0 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 number of instr
18cb0 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 uctions in a vir
18cc0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f tual machine pro
18cd0 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 gram.** used to
18ce0 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c implement an SQL
18cf0 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e statement.</dd>
18d00 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
18d10 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e E_LIMIT_FUNCTION
18d20 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 _ARG</dt>.** <dd
18d30 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
18d40 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 ber of arguments
18d50 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c on a function.<
18d60 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
18d70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 QLITE_LIMIT_ATTA
18d80 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 CHED</dt>.** <dd
18d90 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
18da0 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c ber of [ATTACH |
18db0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 attached databa
18dc0 73 65 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ses].</dd>.**.**
18dd0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 <dt>SQLITE_LIMI
18de0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c T_LIKE_PATTERN_L
18df0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ENGTH</dt>.** <d
18e00 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 d>The maximum le
18e10 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 ngth of the patt
18e20 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ern argument to
18e30 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a the [LIKE] or.**
18e40 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 [GLOB] operator
18e50 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 s.</dd>.**.** <d
18e60 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 t>SQLITE_LIMIT_V
18e70 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f ARIABLE_NUMBER</
18e80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
18e90 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
18ea0 20 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e variables in an
18eb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
18ec0 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f hat can.** be bo
18ed0 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 und.</dd>.** </d
18ee0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
18ef0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 LITE_LIMIT_LENGT
18f00 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
18f10 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 0.#define S
18f20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f QLITE_LIMIT_SQL_
18f30 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 LENGTH
18f40 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
18f50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c SQLITE_LIMIT_COL
18f60 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 UMN
18f70 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 2.#define
18f80 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 SQLITE_LIMIT_EX
18f90 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 PR_DEPTH
18fa0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 3.#defin
18fb0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 e SQLITE_LIMIT_C
18fc0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 OMPOUND_SELECT
18fd0 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 4.#defi
18fe0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
18ff0 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 VDBE_OP
19000 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 5.#def
19010 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
19020 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 _FUNCTION_ARG
19030 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 6.#de
19040 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
19050 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 T_ATTACHED
19060 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 7.#d
19070 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
19080 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f IT_LIKE_PATTERN_
19090 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 LENGTH 8.#
190a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
190b0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
190c0 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a BER 9.
190d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
190e0 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 Compiling An SQ
190f0 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 L Statement {H13
19100 30 31 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 010} <S10000>.**
19110 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 KEYWORDS: {SQL
19120 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c statement compil
19130 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 er}.**.** To exe
19140 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 cute an SQL quer
19150 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 y, it must first
19160 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 be compiled int
19170 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a o a byte-code.**
19180 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f program using o
19190 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ne of these rout
191a0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ines..**.** The
191b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 first argument,
191c0 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 "db", is a [data
191d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
191e0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 obtained from a
191f0 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 .** prior succes
19200 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
19210 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b lite3_open()], [
19220 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
19230 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
19240 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 3_open16()]. Th
19250 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
19260 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 ction must not h
19270 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e ave been closed.
19280 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e .**.** The secon
19290 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 d argument, "zSq
192a0 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 l", is the state
192b0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 ment to be compi
192c0 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 led, encoded.**
192d0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 as either UTF-8
192e0 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 or UTF-16. The
192f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
19300 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 ) and sqlite3_pr
19310 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e epare_v2().** in
19320 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 terfaces use UTF
19330 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f -8, and sqlite3_
19340 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 prepare16() and
19350 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
19360 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 6_v2().** use UT
19370 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 F-16..**.** If t
19380 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e he nByte argumen
19390 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a t is less than z
193a0 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 ero, then zSql i
193b0 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 s read up to the
193c0 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 .** first zero t
193d0 65 72 6d 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 erminator. If nB
193e0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 yte is non-negat
193f0 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 ive, then it is
19400 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e the maximum.** n
19410 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 umber of bytes
19420 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 read from zSql.
19430 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e When nByte is n
19440 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 on-negative, the
19450 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 .** zSql string
19460 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 ends at either t
19470 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 he first '\000'
19480 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 or '\u0000' char
19490 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 acter or.** the
194a0 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 nByte-th byte, w
194b0 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 hichever comes f
194c0 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c irst. If the cal
194d0 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 ler knows.** tha
194e0 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 t the supplied s
194f0 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 tring is nul-ter
19500 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 minated, then th
19510 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a ere is a small.*
19520 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 * performance ad
19530 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 vantage to be ga
19540 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 ined by passing
19550 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 an nByte paramet
19560 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 er that.** is eq
19570 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 ual to the numbe
19580 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
19590 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c e input string <
195a0 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a i>including</i>.
195b0 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 ** the nul-termi
195c0 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a nator bytes..**.
195d0 2a 2a 20 49 66 20 70 7a 54 61 69 6c 20 69 73 20 ** If pzTail is
195e0 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 not NULL then *p
195f0 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f zTail is made to
19600 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 point to the fi
19610 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 rst byte.** past
19620 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 the end of the
19630 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d first SQL statem
19640 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 ent in zSql. Th
19650 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c ese routines onl
19660 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 y.** compile the
19670 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 first statement
19680 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a in zSql, so *pz
19690 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 Tail is left poi
196a0 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 nting to.** what
196b0 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 remains uncompi
196c0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 led..**.** *ppSt
196d0 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 mt is left point
196e0 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 ing to a compile
196f0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
19700 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 ement] that can
19710 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 be.** executed u
19720 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 sing [sqlite3_st
19730 65 70 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65 ep()]. If there
19740 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 is an error, *p
19750 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 pStmt is set.**
19760 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 to NULL. If the
19770 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 input text cont
19780 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 ains no SQL (if
19790 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 the input is an
197a0 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 empty.** string
197b0 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 or a comment) th
197c0 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 en *ppStmt is se
197d0 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 t to NULL..** Th
197e0 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 e calling proced
197f0 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 ure is responsib
19800 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 le for deleting
19810 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 the compiled.**
19820 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 SQL statement us
19830 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
19840 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 alize()] after i
19850 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 t has finished w
19860 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d ith it..** ppStm
19870 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c t may not be NUL
19880 4c 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 L..**.** On succ
19890 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d ess, [SQLITE_OK]
198a0 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 is returned, ot
198b0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f herwise an [erro
198c0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
198d0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ned..**.** The s
198e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
198f0 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 2() and sqlite3_
19900 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 prepare16_v2() i
19910 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a nterfaces are.**
19920 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 recommended for
19930 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d all new program
19940 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 s. The two older
19950 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
19960 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 retained.** for
19970 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
19980 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 ibility, but the
19990 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 ir use is discou
199a0 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 raged..** In the
199b0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 "v2" interfaces
199c0 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 , the prepared s
199d0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 tatement.** that
199e0 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 is returned (th
199f0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d e [sqlite3_stmt]
19a00 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e object) contain
19a10 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a s a copy of the.
19a20 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 ** original SQL
19a30 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 text. This cause
19a40 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 s the [sqlite3_s
19a50 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tep()] interface
19a60 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 to.** behave a
19a70 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 differently in t
19a80 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c wo ways:.**.** <
19a90 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 ol>.** <li>.** I
19aa0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 f the database s
19ab0 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 chema changes, i
19ac0 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e nstead of return
19ad0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 ing [SQLITE_SCHE
19ae0 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 MA] as it.** alw
19af0 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 ays used to do,
19b00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
19b10 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 will automatica
19b20 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 lly recompile th
19b30 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 e SQL.** stateme
19b40 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 nt and try to ru
19b50 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 n it again. If
19b60 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 the schema has c
19b70 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 hanged in.** a w
19b80 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 ay that makes th
19b90 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c e statement no l
19ba0 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 onger valid, [sq
19bb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
19bc0 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 ll still.** retu
19bd0 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d rn [SQLITE_SCHEM
19be0 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 A]. But unlike
19bf0 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 the legacy behav
19c00 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 ior, [SQLITE_SCH
19c10 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 EMA] is.** now a
19c20 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 fatal error. C
19c30 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
19c40 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 prepare_v2()] ag
19c50 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b ain will not mak
19c60 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 e the.** error g
19c70 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 o away. Note: u
19c80 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d se [sqlite3_errm
19c90 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 sg()] to find th
19ca0 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 e text.** of the
19cb0 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 parsing error t
19cc0 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 hat results in a
19cd0 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 n [SQLITE_SCHEMA
19ce0 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c ] return..** </l
19cf0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a i>.**.** <li>.**
19d00 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f When an error o
19d10 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f ccurs, [sqlite3_
19d20 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 step()] will ret
19d30 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 urn one of the d
19d40 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f etailed.** [erro
19d50 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 r codes] or [ext
19d60 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
19d70 73 5d 2e 20 20 54 68 65 20 6c 65 67 61 63 79 20 s]. The legacy
19d80 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 behavior was tha
19d90 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 t.** [sqlite3_st
19da0 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 ep()] would only
19db0 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 return a generi
19dc0 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d c [SQLITE_ERROR]
19dd0 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 result code.**
19de0 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 and you would ha
19df0 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 ve to make a sec
19e00 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ond call to [sql
19e10 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e ite3_reset()] in
19e20 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e order.** to fin
19e30 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 d the underlying
19e40 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 cause of the pr
19e50 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 oblem. With the
19e60 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 "v2" prepare.**
19e70 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 interfaces, the
19e80 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f underlying reaso
19e90 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 n for the error
19ea0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 is returned imme
19eb0 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 diately..** </li
19ec0 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a >.** </ol>.**.**
19ed0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
19ee0 2a 20 5b 48 31 33 30 31 31 5d 20 5b 48 31 33 30 * [H13011] [H130
19ef0 31 32 5d 20 5b 48 31 33 30 31 33 5d 20 5b 48 31 12] [H13013] [H1
19f00 33 30 31 34 5d 20 5b 48 31 33 30 31 35 5d 20 5b 3014] [H13015] [
19f10 48 31 33 30 31 36 5d 20 5b 48 31 33 30 31 39 5d H13016] [H13019]
19f20 20 5b 48 31 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a [H13021].**.*/.
19f30 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
19f40 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a are(. sqlite3 *
19f50 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
19f60 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
19f70 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
19f80 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f r *zSql, /
19f90 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
19fa0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a UTF-8 encoded *
19fb0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
19fc0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
19fd0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
19fe0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
19ff0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
1a000 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
1a010 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
1a020 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
1a030 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 char **pzTail
1a040 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
1a050 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
1a060 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
1a070 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 );.int sqlite3_p
1a080 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c repare_v2(. sql
1a090 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
1a0a0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
1a0b0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
1a0c0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
1a0d0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
1a0e0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 ement, UTF-8 enc
1a0f0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
1a100 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
1a110 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
1a120 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
1a130 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
1a140 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
1a150 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
1a160 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
1a170 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a const char **pz
1a180 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
1a190 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
1a1a0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
1a1b0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c ql */.);.int sql
1a1c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a ite3_prepare16(.
1a1d0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
1a1e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
1a1f0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
1a200 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 const void *zS
1a210 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
1a220 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
1a230 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 16 encoded */.
1a240 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
1a250 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
1a260 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
1a270 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
1a280 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
1a290 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
1a2a0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
1a2b0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
1a2c0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f d **pzTail /
1a2d0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
1a2e0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
1a2f0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 of zSql */.);.i
1a300 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nt sqlite3_prepa
1a310 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 re16_v2(. sqlit
1a320 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
1a330 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
1a340 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
1a350 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 void *zSql,
1a360 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
1a370 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f ent, UTF-16 enco
1a380 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
1a390 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
1a3a0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
1a3b0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
1a3c0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
1a3d0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
1a3e0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
1a3f0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
1a400 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 const void **pzT
1a410 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
1a420 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
1a430 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
1a440 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 l */.);../*.** C
1a450 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 API3REF: Retriev
1a460 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 ing Statement SQ
1a470 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30 L {H13100} <H130
1a480 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 00>.**.** This i
1a490 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 nterface can be
1a4a0 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 used to retrieve
1a4b0 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 a saved copy of
1a4c0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a the original.**
1a4d0 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 SQL text used t
1a4e0 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 o create a [prep
1a4f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
1a500 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e if that statemen
1a510 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 t was.** compile
1a520 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b d using either [
1a530 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1a540 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 v2()] or [sqlite
1a550 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
1a560 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 ]..**.** Require
1a570 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 31 30 ments:.** [H1310
1a580 31 5d 20 5b 48 31 33 31 30 32 5d 20 5b 48 31 33 1] [H13102] [H13
1a590 31 30 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 103].*/.const ch
1a5a0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 ar *sqlite3_sql(
1a5b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
1a5c0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
1a5d0 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c I3REF: Dynamical
1a5e0 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f ly Typed Value O
1a5f0 62 6a 65 63 74 20 7b 48 31 35 30 30 30 7d 20 3c bject {H15000} <
1a600 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S20200>.** KEYWO
1a610 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 RDS: {protected
1a620 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b sqlite3_value} {
1a630 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
1a640 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a te3_value}.**.**
1a650 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 SQLite uses the
1a660 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
1a670 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 bject to represe
1a680 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a nt all values.**
1a690 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f that can be sto
1a6a0 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 red in a databas
1a6b0 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 e table. SQLite
1a6c0 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 uses dynamic typ
1a6d0 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 ing.** for the v
1a6e0 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e alues it stores.
1a6f0 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 Values stored i
1a700 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 n sqlite3_value
1a710 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 objects.** can b
1a720 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 e integers, floa
1a730 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 ting point value
1a740 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 s, strings, BLOB
1a750 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a s, or NULL..**.*
1a760 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c * An sqlite3_val
1a770 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 ue object may be
1a780 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 either "protect
1a790 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 ed" or "unprotec
1a7a0 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e ted"..** Some in
1a7b0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 terfaces require
1a7c0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c a protected sql
1a7d0 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 ite3_value. Oth
1a7e0 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a er interfaces.**
1a7f0 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 will accept eit
1a800 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 her a protected
1a810 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 or an unprotecte
1a820 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e d sqlite3_value.
1a830 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 .** Every interf
1a840 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 ace that accepts
1a850 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 sqlite3_value a
1a860 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 rguments specifi
1a870 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 es.** whether or
1a880 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 not it requires
1a890 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c a protected sql
1a8a0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a ite3_value..**.*
1a8b0 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f * The terms "pro
1a8c0 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 tected" and "unp
1a8d0 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 rotected" refer
1a8e0 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f to whether or no
1a8f0 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 t.** a mutex is
1a900 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 held. A interna
1a910 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 l mutex is held
1a920 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a for a protected.
1a930 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
1a940 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d object but no m
1a950 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 utex is held for
1a960 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a an unprotected.
1a970 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
1a980 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c object. If SQL
1a990 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
1a9a0 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 to be single-thr
1a9b0 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b eaded.** (with [
1a9c0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
1a9d0 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 E=0] and with [s
1a9e0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
1a9f0 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 e()] returning 0
1aa00 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 ).** or if SQLit
1aa10 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 e is run in one
1aa20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 of reduced mutex
1aa30 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 modes .** [SQLI
1aa40 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
1aa50 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 THREAD] or [SQLI
1aa60 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
1aa70 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 HREAD].** then t
1aa80 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 here is no disti
1aa90 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 nction between p
1aaa0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 rotected and unp
1aab0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
1aac0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
1aad0 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 s and they can b
1aae0 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e e used interchan
1aaf0 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 geably. However
1ab00 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d ,.** for maximum
1ab10 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 code portabilit
1ab20 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e y it is recommen
1ab30 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 ded that applica
1ab40 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d tions.** still m
1ab50 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 ake the distinct
1ab60 69 6f 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 ion between betw
1ab70 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e een protected an
1ab80 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a d unprotected.**
1ab90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
1aba0 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e bjects even when
1abb0 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 not strictly re
1abc0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 quired..**.** Th
1abd0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 e sqlite3_value
1abe0 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 objects that are
1abf0 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d passed as param
1ac00 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a eters into the.*
1ac10 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
1ac20 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e of [application
1ac30 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
1ac40 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 ctions] are prot
1ac50 65 63 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 ected..** The sq
1ac60 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
1ac70 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a ct returned by.*
1ac80 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
1ac90 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e n_value()] is un
1aca0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e protected..** Un
1acb0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
1acc0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 3_value objects
1acd0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 may only be used
1ace0 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 with.** [sqlite
1acf0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
1ad00 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 ] and [sqlite3_b
1ad10 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a ind_value()]..**
1ad20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 The [sqlite3_va
1ad30 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 lue_blob | sqlit
1ad40 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d e3_value_type()]
1ad50 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e family of.** in
1ad60 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 terfaces require
1ad70 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 protected sqlit
1ad80 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
1ad90 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
1ada0 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f uct Mem sqlite3_
1adb0 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 value;../*.** CA
1adc0 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 PI3REF: SQL Func
1add0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a tion Context Obj
1ade0 65 63 74 20 7b 48 31 36 30 30 31 7d 20 3c 53 32 ect {H16001} <S2
1adf0 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0200>.**.** The
1ae00 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 context in which
1ae10 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e an SQL function
1ae20 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f executes is sto
1ae30 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c red in an.** sql
1ae40 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a ite3_context obj
1ae50 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 ect. A pointer
1ae60 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f to an sqlite3_co
1ae70 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 ntext object.**
1ae80 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 is always first
1ae90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 parameter to [ap
1aea0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
1aeb0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d d SQL functions]
1aec0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
1aed0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
1aee0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
1aef0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 entation will pa
1af00 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 ss this.** point
1af10 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 er through into
1af20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
1af30 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 3_result_int | s
1af40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d qlite3_result()]
1af50 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 ,.** [sqlite3_ag
1af60 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
1af70 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 )], [sqlite3_use
1af80 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 r_data()],.** [s
1af90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 qlite3_context_d
1afa0 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 b_handle()], [sq
1afb0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
1afc0 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 a()],.** and/or
1afd0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 [sqlite3_set_aux
1afe0 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 data()]..*/.type
1aff0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
1b000 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 e3_context sqlit
1b010 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a e3_context;../*.
1b020 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e ** CAPI3REF: Bin
1b030 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 ding Values To P
1b040 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
1b050 74 73 20 7b 48 31 33 35 30 30 7d 20 3c 53 37 30 ts {H13500} <S70
1b060 33 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 300>.** KEYWORDS
1b070 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 : {host paramete
1b080 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 r} {host paramet
1b090 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d ers} {host param
1b0a0 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 eter name}.** KE
1b0b0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 YWORDS: {SQL par
1b0c0 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 ameter} {SQL par
1b0d0 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 ameters} {parame
1b0e0 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a ter binding}.**.
1b0f0 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 ** In the SQL st
1b100 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b rings input to [
1b110 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1b120 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 v2()] and its va
1b130 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 riants,.** liter
1b140 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 als may be repla
1b150 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 ced by a [parame
1b160 74 65 72 5d 20 69 6e 20 6f 6e 65 20 6f 66 20 74 ter] in one of t
1b170 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a hese forms:.**.*
1b180 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 * <ul>.** <li>
1b190 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a ?.** <li> ?NNN.
1b1a0 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a ** <li> :VVV.**
1b1b0 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c <li> @VVV.** <
1b1c0 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 li> $VVV.** </u
1b1d0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 l>.**.** In the
1b1e0 70 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 parameter forms
1b1f0 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 shown above NNN
1b200 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 is an integer li
1b210 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 teral,.** and VV
1b220 56 20 69 73 20 61 6e 20 61 6c 70 68 61 2d 6e 75 V is an alpha-nu
1b230 6d 65 72 69 63 20 70 61 72 61 6d 65 74 65 72 20 meric parameter
1b240 6e 61 6d 65 2e 20 54 68 65 20 76 61 6c 75 65 73 name. The values
1b250 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 of these.** par
1b260 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 ameters (also ca
1b270 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d lled "host param
1b280 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 eter names" or "
1b290 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 SQL parameters")
1b2a0 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 .** can be set u
1b2b0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 sing the sqlite3
1b2c0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
1b2d0 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e es defined here.
1b2e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
1b2f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
1b300 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
1b310 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c ) routines is al
1b320 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 ways.** a pointe
1b330 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 r to the [sqlite
1b340 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 3_stmt] object r
1b350 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 eturned from.**
1b360 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1b370 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 _v2()] or its va
1b380 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 riants..**.** Th
1b390 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
1b3a0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f t is the index o
1b3b0 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 f the SQL parame
1b3c0 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a ter to be set..*
1b3d0 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 * The leftmost S
1b3e0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 QL parameter has
1b3f0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 an index of 1.
1b400 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e When the same n
1b410 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 amed.** SQL para
1b420 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f meter is used mo
1b430 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 re than once, se
1b440 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 cond and subsequ
1b450 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 ent.** occurrenc
1b460 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 es have the same
1b470 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 index as the fi
1b480 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a rst occurrence..
1b490 2a 2a 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72 ** The index for
1b4a0 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 named parameter
1b4b0 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 s can be looked
1b4c0 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 up using the.**
1b4d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
1b4e0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
1b4f0 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e API if desired.
1b500 20 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 The index.** f
1b510 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 or "?NNN" parame
1b520 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 ters is the valu
1b530 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 e of NNN..** The
1b540 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 NNN value must
1b550 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 be between 1 and
1b560 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 the [sqlite3_li
1b570 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 mit()].** parame
1b580 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ter [SQLITE_LIMI
1b590 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 T_VARIABLE_NUMBE
1b5a0 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 R] (default valu
1b5b0 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 e: 999)..**.** T
1b5c0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
1b5d0 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 t is the value t
1b5e0 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 o bind to the pa
1b5f0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 rameter..**.** I
1b600 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 n those routines
1b610 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 that have a fou
1b620 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 rth argument, it
1b630 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a s value is the.*
1b640 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 * number of byte
1b650 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 s in the paramet
1b660 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 er. To be clear
1b670 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 : the value is t
1b680 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
1b690 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 <u>bytes</u> in
1b6a0 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 the value, not t
1b6b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 he number of cha
1b6c0 72 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74 racters..** If t
1b6d0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
1b6e0 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c ter is negative,
1b6f0 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 the length of t
1b700 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 he string is.**
1b710 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
1b720 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 tes up to the fi
1b730 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 rst zero termina
1b740 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 tor..**.** The f
1b750 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f ifth argument to
1b760 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
1b770 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 ob(), sqlite3_bi
1b780 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a nd_text(), and.*
1b790 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 * sqlite3_bind_t
1b7a0 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 ext16() is a des
1b7b0 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 tructor used to
1b7c0 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 dispose of the B
1b7d0 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 LOB or.** string
1b7e0 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 after SQLite ha
1b7f0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 s finished with
1b800 69 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 68 it. If the fifth
1b810 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 argument is.**
1b820 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 the special valu
1b830 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 e [SQLITE_STATIC
1b840 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 ], then SQLite a
1b850 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a ssumes that the.
1b860 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 ** information i
1b870 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d s in static, unm
1b880 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 anaged space and
1b890 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
1b8a0 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 o be freed..** I
1b8b0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 f the fifth argu
1b8c0 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c ment has the val
1b8d0 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 ue [SQLITE_TRANS
1b8e0 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 IENT], then.** S
1b8f0 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 QLite makes its
1b900 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 own private copy
1b910 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d of the data imm
1b920 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 ediately, before
1b930 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f .** the sqlite3_
1b940 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
1b950 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
1b960 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 The sqlite3_bind
1b970 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 _zeroblob() rout
1b980 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 ine binds a BLOB
1b990 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 of length N tha
1b9a0 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 t.** is filled w
1b9b0 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a ith zeroes. A z
1b9c0 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 eroblob uses a f
1b9d0 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d ixed amount of m
1b9e0 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 emory.** (just a
1b9f0 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c n integer to hol
1ba00 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c d its size) whil
1ba10 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 e it is being pr
1ba20 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f ocessed..** Zero
1ba30 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 blobs are intend
1ba40 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 ed to serve as p
1ba50 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 laceholders for
1ba60 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 BLOBs whose.** c
1ba70 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 ontent is later
1ba80 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a written using.**
1ba90 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
1baa0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 pen | incrementa
1bab0 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 l BLOB I/O] rout
1bac0 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 ines..** A negat
1bad0 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 ive value for th
1bae0 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c e zeroblob resul
1baf0 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e ts in a zero-len
1bb00 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 gth BLOB..**.**
1bb10 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 The sqlite3_bind
1bb20 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 _*() routines mu
1bb30 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74 st be called aft
1bb40 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 er.** [sqlite3_p
1bb50 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e repare_v2()] (an
1bb60 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 d its variants)
1bb70 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 or [sqlite3_rese
1bb80 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f t()] and.** befo
1bb90 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 re [sqlite3_step
1bba0 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 ()]..** Bindings
1bbb0 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 are not cleared
1bbc0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 by the [sqlite3
1bbd0 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e _reset()] routin
1bbe0 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 e..** Unbound pa
1bbf0 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 rameters are int
1bc00 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c erpreted as NULL
1bc10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
1bc20 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 utines return [S
1bc30 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
1bc40 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 cess or an error
1bc50 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 code if.** anyt
1bc60 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e hing goes wrong.
1bc70 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d [SQLITE_RANGE]
1bc80 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 is returned if
1bc90 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a the parameter.**
1bca0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 index is out of
1bcb0 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 range. [SQLITE
1bcc0 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 _NOMEM] is retur
1bcd0 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 ned if malloc()
1bce0 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 fails..** [SQLIT
1bcf0 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20 E_MISUSE] might
1bd00 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 be returned if t
1bd10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
1bd20 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a e called on a.**
1bd30 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 virtual machine
1bd40 20 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f that is the wro
1bd50 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 ng state or whic
1bd60 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 h has already be
1bd70 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a en finalized..**
1bd80 20 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 Detection of mi
1bd90 73 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62 suse is unreliab
1bda0 6c 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e le. Application
1bdb0 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 s should not dep
1bdc0 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 end.** on SQLITE
1bdd0 5f 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e _MISUSE returns.
1bde0 20 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 SQLITE_MISUSE
1bdf0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 is intended to i
1be00 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c ndicate a.** a l
1be10 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68 ogic error in th
1be20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 e application.
1be30 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 Future versions
1be40 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a of SQLite might.
1be50 2a 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72 20 ** panic rather
1be60 74 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 than return SQLI
1be70 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a TE_MISUSE..**.**
1be80 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
1be90 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
1bea0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 er_count()],.**
1beb0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
1bec0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c rameter_name()],
1bed0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 and [sqlite3_bi
1bee0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
1bef0 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 ex()]..**.** Req
1bf00 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
1bf10 31 33 35 30 36 5d 20 5b 48 31 33 35 30 39 5d 20 13506] [H13509]
1bf20 5b 48 31 33 35 31 32 5d 20 5b 48 31 33 35 31 35 [H13512] [H13515
1bf30 5d 20 5b 48 31 33 35 31 38 5d 20 5b 48 31 33 35 ] [H13518] [H135
1bf40 32 31 5d 20 5b 48 31 33 35 32 34 5d 20 5b 48 31 21] [H13524] [H1
1bf50 33 35 32 37 5d 0a 2a 2a 20 5b 48 31 33 35 33 30 3527].** [H13530
1bf60 5d 20 5b 48 31 33 35 33 33 5d 20 5b 48 31 33 35 ] [H13533] [H135
1bf70 33 36 5d 20 5b 48 31 33 35 33 39 5d 20 5b 48 31 36] [H13539] [H1
1bf80 33 35 34 32 5d 20 5b 48 31 33 35 34 35 5d 20 5b 3542] [H13545] [
1bf90 48 31 33 35 34 38 5d 20 5b 48 31 33 35 35 31 5d H13548] [H13551]
1bfa0 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 .**.*/.int sqlit
1bfb0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c e3_bind_blob(sql
1bfc0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
1bfd0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
1bfe0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 t n, void(*)(voi
1bff0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 d*));.int sqlite
1c000 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 3_bind_double(sq
1c010 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
1c020 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 , double);.int s
1c030 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 qlite3_bind_int(
1c040 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
1c050 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 nt, int);.int sq
1c060 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 lite3_bind_int64
1c070 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
1c080 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 int, sqlite3_int
1c090 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 64);.int sqlite3
1c0a0 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 _bind_null(sqlit
1c0b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a e3_stmt*, int);.
1c0c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
1c0d0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 _text(sqlite3_st
1c0e0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
1c0f0 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f char*, int n, vo
1c100 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 id(*)(void*));.i
1c110 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
1c120 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 text16(sqlite3_s
1c130 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
1c140 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 void*, int, voi
1c150 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e d(*)(void*));.in
1c160 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 t sqlite3_bind_v
1c170 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d alue(sqlite3_stm
1c180 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 t*, int, const s
1c190 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
1c1a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
1c1b0 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 _zeroblob(sqlite
1c1c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 3_stmt*, int, in
1c1d0 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 t n);../*.** CAP
1c1e0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 I3REF: Number Of
1c1f0 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 20 SQL Parameters
1c200 7b 48 31 33 36 30 30 7d 20 3c 53 37 30 33 30 30 {H13600} <S70300
1c210 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 >.**.** This rou
1c220 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 tine can be used
1c230 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d to find the num
1c240 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 ber of [SQL para
1c250 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 meters].** in a
1c260 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1c270 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d ent]. SQL param
1c280 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 eters are tokens
1c290 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 of the.** form
1c2a0 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 "?", "?NNN", ":A
1c2b0 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 AA", "$AAA", or
1c2c0 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 "@AAA" that serv
1c2d0 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c e as.** placehol
1c2e0 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 ders for values
1c2f0 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 that are [sqlite
1c300 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 3_bind_blob | bo
1c310 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 und].** to the p
1c320 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c arameters at a l
1c330 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a ater time..**.**
1c340 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 This routine ac
1c350 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 tually returns t
1c360 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 he index of the
1c370 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f largest (rightmo
1c380 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 st).** parameter
1c390 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 . For all forms
1c3a0 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 except ?NNN, thi
1c3b0 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e s will correspon
1c3c0 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 d to the.** numb
1c3d0 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 er of unique par
1c3e0 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 ameters. If par
1c3f0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f ameters of the ?
1c400 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a NNN are used,.**
1c410 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 there may be ga
1c420 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a ps in the list..
1c430 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
1c440 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
1c450 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 ob|sqlite3_bind(
1c460 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
1c470 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e bind_parameter_n
1c480 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b ame()], and.** [
1c490 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
1c4a0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
1c4b0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
1c4c0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 30 31 5d nts:.** [H13601]
1c4d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
1c4e0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
1c4f0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d ount(sqlite3_stm
1c500 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
1c510 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 3REF: Name Of A
1c520 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b Host Parameter {
1c530 48 31 33 36 32 30 7d 20 3c 53 37 30 33 30 30 3e H13620} <S70300>
1c540 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
1c550 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ine returns a po
1c560 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d inter to the nam
1c570 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a e of the n-th.**
1c580 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d [SQL parameter]
1c590 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 in a [prepared
1c5a0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 statement]..** S
1c5b0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 QL parameters of
1c5c0 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 the form "?NNN"
1c5d0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 or ":AAA" or "@
1c5e0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a AAA" or "$AAA".*
1c5f0 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 * have a name wh
1c600 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e ich is the strin
1c610 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 g "?NNN" or ":AA
1c620 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 A" or "@AAA" or
1c630 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 "$AAA".** respec
1c640 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 tively..** In ot
1c650 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 her words, the i
1c660 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 nitial ":" or "$
1c670 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a " or "@" or "?".
1c680 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 ** is included a
1c690 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 s part of the na
1c6a0 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 me..** Parameter
1c6b0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f s of the form "?
1c6c0 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c " without a foll
1c6d0 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 owing integer ha
1c6e0 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e ve no name.** an
1c6f0 64 20 61 72 65 20 61 6c 73 6f 20 72 65 66 65 72 d are also refer
1c700 72 65 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 red to as "anony
1c710 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 mous parameters"
1c720 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
1c730 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 t host parameter
1c740 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 has an index of
1c750 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 1, not 0..**.**
1c760 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 If the value n
1c770 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 is out of range
1c780 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 or if the n-th p
1c790 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e arameter is.** n
1c7a0 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 ameless, then NU
1c7b0 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 LL is returned.
1c7c0 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 The returned st
1c7d0 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 ring is.** alway
1c7e0 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 s in UTF-8 encod
1c7f0 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 ing even if the
1c800 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 named parameter
1c810 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c was.** originall
1c820 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 y specified as U
1c830 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 TF-16 in [sqlite
1c840 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 3_prepare16()] o
1c850 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 r.** [sqlite3_pr
1c860 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a epare16_v2()]..*
1c870 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
1c880 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
1c890 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
1c8a0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
1c8b0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
1c8c0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b unt()], and.** [
1c8d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
1c8e0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
1c8f0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
1c900 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 32 31 5d nts:.** [H13621]
1c910 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
1c920 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
1c930 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 ameter_name(sqli
1c940 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b te3_stmt*, int);
1c950 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1c960 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 : Index Of A Par
1c970 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 ameter With A Gi
1c980 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33 36 34 30 ven Name {H13640
1c990 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a } <S70300>.**.**
1c9a0 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 Return the inde
1c9b0 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 x of an SQL para
1c9c0 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 meter given its
1c9d0 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e name. The.** in
1c9e0 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e dex value return
1c9f0 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 ed is suitable f
1ca00 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 or use as the se
1ca10 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 cond.** paramete
1ca20 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 r to [sqlite3_bi
1ca30 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
1ca40 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f bind()]. A zero
1ca50 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
1ca60 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 if no matching p
1ca70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e arameter is foun
1ca80 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74 65 d. The paramete
1ca90 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 r.** name must b
1caa0 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 e given in UTF-8
1cab0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 even if the ori
1cac0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a ginal statement.
1cad0 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 ** was prepared
1cae0 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 from UTF-16 text
1caf0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
1cb00 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e prepare16_v2()].
1cb10 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
1cb20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
1cb30 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 lob|sqlite3_bind
1cb40 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
1cb50 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
1cb60 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a count()], and.**
1cb70 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
1cb80 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
1cb90 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 ]..**.** Require
1cba0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 34 ments:.** [H1364
1cbb0 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 1].*/.int sqlite
1cbc0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
1cbd0 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 _index(sqlite3_s
1cbe0 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 tmt*, const char
1cbf0 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a *zName);../*.**
1cc00 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 CAPI3REF: Reset
1cc10 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e All Bindings On
1cc20 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 A Prepared Stat
1cc30 65 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c ement {H13660} <
1cc40 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f S70300>.**.** Co
1cc50 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e ntrary to the in
1cc60 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c tuition of many,
1cc70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
1cc80 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 )] does not rese
1cc90 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 t.** the [sqlite
1cca0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 3_bind_blob | bi
1ccb0 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 ndings] on a [pr
1ccc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1ccd0 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 72 ]..** Use this r
1cce0 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 outine to reset
1ccf0 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 all host paramet
1cd00 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a ers to NULL..**.
1cd10 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
1cd20 0a 2a 2a 20 5b 48 31 33 36 36 31 5d 0a 2a 2f 0a .** [H13661].*/.
1cd30 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 int sqlite3_clea
1cd40 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 r_bindings(sqlit
1cd50 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
1cd60 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
1cd70 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e er Of Columns In
1cd80 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 A Result Set {H
1cd90 31 33 37 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 13710} <S10700>.
1cda0 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 **.** Return the
1cdb0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
1cdc0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ns in the result
1cdd0 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 set returned by
1cde0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
1cdf0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 d statement]. Th
1ce00 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
1ce10 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 ns 0 if pStmt is
1ce20 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 an SQL.** state
1ce30 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e ment that does n
1ce40 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 ot return data (
1ce50 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b for example an [
1ce60 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 UPDATE])..**.**
1ce70 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
1ce80 20 5b 48 31 33 37 31 31 5d 0a 2a 2f 0a 69 6e 74 [H13711].*/.int
1ce90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
1cea0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 count(sqlite3_st
1ceb0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
1cec0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c ** CAPI3REF: Col
1ced0 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 umn Names In A R
1cee0 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 32 esult Set {H1372
1cef0 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 0} <S10700>.**.*
1cf00 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
1cf10 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 return the name
1cf20 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 assigned to a p
1cf30 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e articular column
1cf40 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c .** in the resul
1cf50 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 t set of a [SELE
1cf60 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 CT] statement.
1cf70 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 The sqlite3_colu
1cf80 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 mn_name().** int
1cf90 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
1cfa0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 pointer to a ze
1cfb0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
1cfc0 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e F-8 string.** an
1cfd0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
1cfe0 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e _name16() return
1cff0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
1d000 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1d010 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e .** UTF-16 strin
1d020 67 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 g. The first pa
1d030 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b rameter is the [
1d040 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1d050 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c nt].** that impl
1d060 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 ements the [SELE
1d070 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 CT] statement. T
1d080 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
1d090 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f ter is the.** co
1d0a0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 lumn number. Th
1d0b0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d e leftmost colum
1d0c0 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a n is number 0..*
1d0d0 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 *.** The returne
1d0e0 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 d string pointer
1d0f0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 is valid until
1d100 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 either the [prep
1d110 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a ared statement].
1d120 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 ** is destroyed
1d130 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 by [sqlite3_fina
1d140 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c lize()] or until
1d150 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 the next call t
1d160 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c o.** sqlite3_col
1d170 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 umn_name() or sq
1d180 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
1d190 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d e16() on the sam
1d1a0 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 e column..**.**
1d1b0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f If sqlite3_mallo
1d1c0 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 c() fails during
1d1d0 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 the processing
1d1e0 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e of either routin
1d1f0 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c e.** (for exampl
1d200 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 e during a conve
1d210 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 rsion from UTF-8
1d220 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e to UTF-16) then
1d230 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 a.** NULL point
1d240 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a er is returned..
1d250 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f **.** The name o
1d260 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d f a result colum
1d270 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f n is the value o
1d280 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 f the "AS" claus
1d290 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f e for.** that co
1d2a0 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 lumn, if there i
1d2b0 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 s an AS clause.
1d2c0 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 If there is no
1d2d0 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 AS clause.** the
1d2e0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 n the name of th
1d2f0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 e column is unsp
1d300 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 ecified and may
1d310 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f change from.** o
1d320 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 ne release of SQ
1d330 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 Lite to the next
1d340 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
1d350 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 32 31 ents:.** [H13721
1d360 5d 20 5b 48 31 33 37 32 33 5d 20 5b 48 31 33 37 ] [H13723] [H137
1d370 32 34 5d 20 5b 48 31 33 37 32 35 5d 20 5b 48 31 24] [H13725] [H1
1d380 33 37 32 36 5d 20 5b 48 31 33 37 32 37 5d 0a 2a 3726] [H13727].*
1d390 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 /.const char *sq
1d3a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
1d3b0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
1d3c0 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 int N);.const v
1d3d0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
1d3e0 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 umn_name16(sqlit
1d3f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 e3_stmt*, int N)
1d400 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1d410 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 F: Source Of Dat
1d420 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 a In A Query Res
1d430 75 6c 74 20 7b 48 31 33 37 34 30 7d 20 3c 53 31 ult {H13740} <S1
1d440 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 0700>.**.** Thes
1d450 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 e routines provi
1d460 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 de a means to de
1d470 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c termine what col
1d480 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 umn of what.** t
1d490 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61 able in which da
1d4a0 74 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 20 tabase a result
1d4b0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 of a [SELECT] st
1d4c0 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 atement comes fr
1d4d0 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 om..** The name
1d4e0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
1d4f0 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 or table or colu
1d500 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e mn can be return
1d510 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 ed as.** either
1d520 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 a UTF-8 or UTF-1
1d530 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 6 string. The _
1d540 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e database_ routin
1d550 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 es return.** the
1d560 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 database name,
1d570 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 the _table_ rout
1d580 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 ines return the
1d590 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a table name, and.
1d5a0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 ** the origin_ r
1d5b0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
1d5c0 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a he column name..
1d5d0 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 ** The returned
1d5e0 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 string is valid
1d5f0 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 until the [prepa
1d600 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 red statement] i
1d610 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 s destroyed.** u
1d620 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 sing [sqlite3_fi
1d630 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 nalize()] or unt
1d640 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f il the same info
1d650 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 rmation is reque
1d660 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e sted.** again in
1d670 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 a different enc
1d680 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 oding..**.** The
1d690 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 names returned
1d6a0 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c are the original
1d6b0 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 un-aliased name
1d6c0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 s of the.** data
1d6d0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 base, table, and
1d6e0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 column..**.** T
1d6f0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
1d700 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 t to the followi
1d710 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 ng calls is a [p
1d720 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1d730 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e t]..** These fun
1d740 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e ctions return in
1d750 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 formation about
1d760 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 the Nth column r
1d770 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 eturned by.** th
1d780 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 e statement, whe
1d790 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f re N is the seco
1d7a0 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 nd function argu
1d7b0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 ment..**.** If t
1d7c0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 he Nth column re
1d7d0 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 turned by the st
1d7e0 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 atement is an ex
1d7f0 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 pression or.** s
1d800 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e ubquery and is n
1d810 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 ot a column valu
1d820 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 e, then all of t
1d830 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 hese functions r
1d840 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 eturn.** NULL.
1d850 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 These routine mi
1d860 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 ght also return
1d870 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 NULL if a memory
1d880 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f allocation erro
1d890 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 r.** occurs. Ot
1d8a0 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 herwise, they re
1d8b0 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 turn the name of
1d8c0 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 the attached da
1d8d0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a tabase, table.**
1d8e0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 and column that
1d8f0 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f query result co
1d900 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 lumn was extract
1d910 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 ed from..**.** A
1d920 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 s with all other
1d930 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 SQLite APIs, th
1d940 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 ose postfixed wi
1d950 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a th "16" return.*
1d960 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 * UTF-16 encoded
1d970 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 strings, the ot
1d980 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 her functions re
1d990 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 turn UTF-8. {END
1d9a0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 }.**.** These AP
1d9b0 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 Is are only avai
1d9c0 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 lable if the lib
1d9d0 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 rary was compile
1d9e0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 d with the.** [S
1d9f0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c QLITE_ENABLE_COL
1da00 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d UMN_METADATA] C-
1da10 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d preprocessor sym
1da20 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a bol defined..**.
1da30 2a 2a 20 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 ** {A13751}.** I
1da40 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 f two or more th
1da50 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f reads call one o
1da60 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 r more of these
1da70 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 routines against
1da80 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 the same.** pre
1da90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
1daa0 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 and column at th
1dab0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e e same time then
1dac0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
1dad0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a .** undefined..*
1dae0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
1daf0 73 3a 0a 2a 2a 20 5b 48 31 33 37 34 31 5d 20 5b s:.** [H13741] [
1db00 48 31 33 37 34 32 5d 20 5b 48 31 33 37 34 33 5d H13742] [H13743]
1db10 20 5b 48 31 33 37 34 34 5d 20 5b 48 31 33 37 34 [H13744] [H1374
1db20 35 5d 20 5b 48 31 33 37 34 36 5d 20 5b 48 31 33 5] [H13746] [H13
1db30 37 34 38 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 748].**.** If tw
1db40 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 o or more thread
1db50 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f s call one or mo
1db60 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 re.** [sqlite3_c
1db70 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e olumn_database_n
1db80 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 ame | column met
1db90 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 adata interfaces
1dba0 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d ].** for the sam
1dbb0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
1dbc0 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c ement] and resul
1dbd0 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 t column.** at t
1dbe0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 he same time the
1dbf0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 n the results ar
1dc00 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a e undefined..*/.
1dc10 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
1dc20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
1dc30 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 ase_name(sqlite3
1dc40 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
1dc50 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
1dc60 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
1dc70 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
1dc80 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
1dc90 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
1dca0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d column_table_nam
1dcb0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
1dcc0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 int);.const void
1dcd0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
1dce0 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 _table_name16(sq
1dcf0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
1dd00 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 ;.const char *sq
1dd10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 lite3_column_ori
1dd20 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 gin_name(sqlite3
1dd30 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
1dd40 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
1dd50 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e _column_origin_n
1dd60 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
1dd70 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a mt*,int);../*.**
1dd80 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 CAPI3REF: Decla
1dd90 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 red Datatype Of
1dda0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b A Query Result {
1ddb0 48 31 33 37 36 30 7d 20 3c 53 31 30 37 30 30 3e H13760} <S10700>
1ddc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
1ddd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
1dde0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1ddf0 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 ent]..** If this
1de00 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 statement is a
1de10 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
1de20 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 nt and the Nth c
1de30 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 olumn of the.**
1de40 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 returned result
1de50 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c set of that [SEL
1de60 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 ECT] is a table
1de70 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a column (not an.*
1de80 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 * expression or
1de90 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 subquery) then t
1dea0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 he declared type
1deb0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a of the table.**
1dec0 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 column is retur
1ded0 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68 ned. If the Nth
1dee0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 column of the r
1def0 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a esult set is an.
1df00 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 ** expression or
1df10 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 subquery, then
1df20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
1df30 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 s returned..** T
1df40 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
1df50 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 ng is always UTF
1df60 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 -8 encoded. {END
1df70 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d }.**.** For exam
1df80 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 ple, given the d
1df90 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a atabase schema:.
1dfa0 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 **.** CREATE TAB
1dfb0 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 LE t1(c1 VARIANT
1dfc0 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 );.**.** and the
1dfd0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 following state
1dfe0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 ment to be compi
1dff0 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 led:.**.** SELEC
1e000 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f T c1 + 1, c1 FRO
1e010 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 M t1;.**.** this
1e020 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 routine would r
1e030 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 eturn the string
1e040 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 "VARIANT" for t
1e050 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 he second result
1e060 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 .** column (i==1
1e070 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f ), and a NULL po
1e080 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 inter for the fi
1e090 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d rst result colum
1e0a0 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 n (i==0)..**.**
1e0b0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 SQLite uses dyna
1e0c0 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 mic run-time typ
1e0d0 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 ing. So just be
1e0e0 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a cause a column.*
1e0f0 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f * is declared to
1e100 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 contain a parti
1e110 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 cular type does
1e120 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 not mean that th
1e130 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 e.** data stored
1e140 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 in that column
1e150 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 is of the declar
1e160 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 ed type. SQLite
1e170 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 is.** strongly
1e180 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 typed, but the t
1e190 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 yping is dynamic
1e1a0 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 not static. Ty
1e1b0 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 pe.** is associa
1e1c0 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 ted with individ
1e1d0 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 ual values, not
1e1e0 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e with the contain
1e1f0 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 ers.** used to h
1e200 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 old those values
1e210 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
1e220 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 36 31 ents:.** [H13761
1e230 5d 20 5b 48 31 33 37 36 32 5d 20 5b 48 31 33 37 ] [H13762] [H137
1e240 36 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 63].*/.const cha
1e250 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
1e260 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 n_decltype(sqlit
1e270 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 e3_stmt*,int);.c
1e280 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
1e290 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
1e2a0 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d pe16(sqlite3_stm
1e2b0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t*,int);../*.**
1e2c0 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 CAPI3REF: Evalua
1e2d0 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d te An SQL Statem
1e2e0 65 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 ent {H13200} <S1
1e2f0 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 0000>.**.** Afte
1e300 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 r a [prepared st
1e310 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 atement] has bee
1e320 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 n prepared using
1e330 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 either.** [sqli
1e340 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1e350 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ] or [sqlite3_pr
1e360 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 epare16_v2()] or
1e370 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 one of the lega
1e380 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 cy.** interfaces
1e390 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1e3a0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 e()] or [sqlite3
1e3b0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 _prepare16()], t
1e3c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 his function.**
1e3d0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f must be called o
1e3e0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ne or more times
1e3f0 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 to evaluate the
1e400 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a statement..**.*
1e410 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 * The details of
1e420 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 the behavior of
1e430 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 the sqlite3_ste
1e440 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 p() interface de
1e450 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 pend.** on wheth
1e460 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 er the statement
1e470 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 was prepared us
1e480 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 ing the newer "v
1e490 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 2" interface.**
1e4a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1e4b0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 _v2()] and [sqli
1e4c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
1e4d0 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 ()] or the older
1e4e0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 legacy.** inter
1e4f0 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 face [sqlite3_pr
1e500 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 epare()] and [sq
1e510 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
1e520 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 )]. The use of
1e530 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 the.** new "v2"
1e540 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 interface is rec
1e550 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 ommended for new
1e560 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 applications bu
1e570 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 t the legacy.**
1e580 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 interface will c
1e590 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 ontinue to be su
1e5a0 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 pported..**.** I
1e5b0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 n the legacy int
1e5c0 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 erface, the retu
1e5d0 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 rn value will be
1e5e0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f either [SQLITE_
1e5f0 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 BUSY],.** [SQLIT
1e600 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 E_DONE], [SQLITE
1e610 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 _ROW], [SQLITE_E
1e620 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 RROR], or [SQLIT
1e630 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 E_MISUSE]..** Wi
1e640 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 th the "v2" inte
1e650 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 rface, any of th
1e660 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 e other [result
1e670 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 codes] or.** [ex
1e680 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
1e690 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 des] might be re
1e6a0 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a turned as well..
1e6b0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 **.** [SQLITE_BU
1e6c0 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 SY] means that t
1e6d0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 he database engi
1e6e0 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f ne was unable to
1e6f0 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 acquire the.**
1e700 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 database locks i
1e710 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 t needs to do it
1e720 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 s job. If the s
1e730 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 tatement is a [C
1e740 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 OMMIT].** or occ
1e750 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 urs outside of a
1e760 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 n explicit trans
1e770 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 action, then you
1e780 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a can retry the.*
1e790 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 * statement. If
1e7a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
1e7b0 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d s not a [COMMIT]
1e7c0 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 and occurs with
1e7d0 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 in a.** explicit
1e7e0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 transaction the
1e7f0 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c n you should rol
1e800 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 lback the transa
1e810 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 ction before.**
1e820 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a continuing..**.*
1e830 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 * [SQLITE_DONE]
1e840 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 means that the s
1e850 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e tatement has fin
1e860 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a ished executing.
1e870 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e ** successfully.
1e880 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 sqlite3_step()
1e890 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 should not be c
1e8a0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 alled again on t
1e8b0 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d his virtual.** m
1e8c0 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 achine without f
1e8d0 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 irst calling [sq
1e8e0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 lite3_reset()] t
1e8f0 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 o reset the virt
1e900 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 ual.** machine b
1e910 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 ack to its initi
1e920 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 al state..**.**
1e930 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 If the SQL state
1e940 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 ment being execu
1e950 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 ted returns any
1e960 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 data, then [SQLI
1e970 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 TE_ROW].** is re
1e980 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 turned each time
1e990 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 a new row of da
1e9a0 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 ta is ready for
1e9b0 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 processing by th
1e9c0 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 e.** caller. The
1e9d0 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 values may be a
1e9e0 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 ccessed using th
1e9f0 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 e [column access
1ea00 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 functions]..**
1ea10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
1ea20 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 s called again t
1ea30 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e o retrieve the n
1ea40 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e ext row of data.
1ea50 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 .**.** [SQLITE_E
1ea60 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 RROR] means that
1ea70 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f a run-time erro
1ea80 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e r (such as a con
1ea90 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 straint.** viola
1eaa0 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 tion) has occurr
1eab0 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 ed. sqlite3_ste
1eac0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 p() should not b
1ead0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f e called again o
1eae0 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 n.** the VM. Mor
1eaf0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 e information ma
1eb00 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 y be found by ca
1eb10 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 lling [sqlite3_e
1eb20 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 rrmsg()]..** Wit
1eb30 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 h the legacy int
1eb40 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 erface, a more s
1eb50 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f pecific error co
1eb60 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c de (for example,
1eb70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 .** [SQLITE_INTE
1eb80 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f RRUPT], [SQLITE_
1eb90 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 SCHEMA], [SQLITE
1eba0 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 _CORRUPT], and s
1ebb0 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 o forth).** can
1ebc0 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 be obtained by c
1ebd0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
1ebe0 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a reset()] on the.
1ebf0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
1ec00 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 tement]. In the
1ec10 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c "v2" interface,
1ec20 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 .** the more spe
1ec30 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 cific error code
1ec40 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 is returned dir
1ec50 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 ectly by sqlite3
1ec60 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b _step()..**.** [
1ec70 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d SQLITE_MISUSE] m
1ec80 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 eans that the th
1ec90 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 is routine was c
1eca0 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 alled inappropri
1ecb0 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 ately..** Perhap
1ecc0 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 s it was called
1ecd0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 on a [prepared s
1ece0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 tatement] that h
1ecf0 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 as.** already be
1ed00 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 en [sqlite3_fina
1ed10 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 lize | finalized
1ed20 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 ] or on one that
1ed30 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 had.** previous
1ed40 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c ly returned [SQL
1ed50 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 ITE_ERROR] or [S
1ed60 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 QLITE_DONE]. Or
1ed70 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 it could.** be
1ed80 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 the case that th
1ed90 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
1eda0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 connection is be
1edb0 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 ing used by two
1edc0 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 or.** more threa
1edd0 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d ds at the same m
1ede0 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a oment in time..*
1edf0 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e *.** <b>Goofy In
1ee00 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f terface Alert:</
1ee10 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 b> In the legacy
1ee20 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 interface, the
1ee30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a sqlite3_step().*
1ee40 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 * API always ret
1ee50 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 urns a generic e
1ee60 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 rror code, [SQLI
1ee70 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f TE_ERROR], follo
1ee80 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f wing any.** erro
1ee90 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 r other than [SQ
1eea0 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b LITE_BUSY] and [
1eeb0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 SQLITE_MISUSE].
1eec0 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a You must call.*
1eed0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
1eee0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
1eef0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f finalize()] in o
1ef00 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 rder to find one
1ef10 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 of the.** speci
1ef20 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 fic [error codes
1ef30 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 ] that better de
1ef40 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f scribes the erro
1ef50 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 r..** We admit t
1ef60 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f hat this is a go
1ef70 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 ofy design. The
1ef80 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 problem has bee
1ef90 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 n fixed.** with
1efa0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
1efb0 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 ce. If you prep
1efc0 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 are all of your
1efd0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
1efe0 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b * using either [
1eff0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1f000 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 v2()] or [sqlite
1f010 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
1f020 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 ] instead.** of
1f030 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 the legacy [sqli
1f040 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 te3_prepare()] a
1f050 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
1f060 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 are16()] interfa
1f070 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ces,.** then the
1f080 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b more specific [
1f090 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 error codes] are
1f0a0 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 returned direct
1f0b0 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 ly.** by sqlite3
1f0c0 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 _step(). The us
1f0d0 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e e of the "v2" in
1f0e0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d terface is recom
1f0f0 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 mended..**.** Re
1f100 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
1f110 48 31 33 32 30 32 5d 20 5b 48 31 35 33 30 34 5d H13202] [H15304]
1f120 20 5b 48 31 35 33 30 36 5d 20 5b 48 31 35 33 30 [H15306] [H1530
1f130 38 5d 20 5b 48 31 35 33 31 30 5d 0a 2a 2f 0a 69 8] [H15310].*/.i
1f140 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 nt sqlite3_step(
1f150 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
1f160 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1f170 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d Number of colum
1f180 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 ns in a result s
1f190 65 74 20 7b 48 31 33 37 37 30 7d 20 3c 53 31 30 et {H13770} <S10
1f1a0 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 700>.**.** Retur
1f1b0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
1f1c0 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 values in the c
1f1d0 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 urrent row of th
1f1e0 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a e result set..**
1f1f0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
1f200 3a 0a 2a 2a 20 5b 48 31 33 37 37 31 5d 20 5b 48 :.** [H13771] [H
1f210 31 33 37 37 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 13772].*/.int sq
1f220 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
1f230 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
1f240 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
1f250 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e PI3REF: Fundamen
1f260 74 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 48 tal Datatypes {H
1f270 31 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c 10265} <S10110><
1f280 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f S10120>.** KEYWO
1f290 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 RDS: SQLITE_TEXT
1f2a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20 .**.** {H10266}
1f2b0 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 Every value in S
1f2c0 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 QLite has one of
1f2d0 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 five fundamenta
1f2e0 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a l datatypes:.**.
1f2f0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
1f300 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 64-bit signed in
1f310 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 teger.** <li> 64
1f320 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 -bit IEEE floati
1f330 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a ng point number.
1f340 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a ** <li> string.*
1f350 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c * <li> BLOB.** <
1f360 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c li> NULL.** </ul
1f370 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 > {END}.**.** Th
1f380 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ese constants ar
1f390 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 e codes for each
1f3a0 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e of those types.
1f3b0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
1f3c0 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 the SQLITE_TEXT
1f3d0 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c constant was al
1f3e0 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 so used in SQLit
1f3f0 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 e version 2.** f
1f400 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 or a completely
1f410 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e different meanin
1f420 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 g. Software tha
1f430 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 t links against
1f440 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 both.** SQLite v
1f450 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c ersion 2 and SQL
1f460 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 ite version 3 sh
1f470 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 ould use SQLITE3
1f480 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 _TEXT, not.** SQ
1f490 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 LITE_TEXT..*/.#d
1f4a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 efine SQLITE_INT
1f4b0 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 EGER 1.#define
1f4c0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 SQLITE_FLOAT
1f4d0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
1f4e0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 _BLOB 4.#def
1f4f0 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 ine SQLITE_NULL
1f500 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 5.#ifdef SQL
1f510 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 ITE_TEXT.# undef
1f520 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c SQLITE_TEXT.#el
1f530 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 se.# define SQLI
1f540 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 TE_TEXT 3.#e
1f550 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c ndif.#define SQL
1f560 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a ITE3_TEXT 3.
1f570 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1f580 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 Result Values F
1f590 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31 33 rom A Query {H13
1f5a0 38 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 800} <S10700>.**
1f5b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 KEYWORDS: {colu
1f5c0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 mn access functi
1f5d0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ons}.**.** These
1f5e0 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 routines form t
1f5f0 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 he "result set q
1f600 75 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e uery" interface.
1f610 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
1f620 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 tines return inf
1f630 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 ormation about a
1f640 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f single column o
1f650 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a f the current.**
1f660 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 result row of a
1f670 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 query. In ever
1f680 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 y case the first
1f690 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 argument is a p
1f6a0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ointer.** to the
1f6b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1f6c0 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 ment] that is be
1f6d0 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 ing evaluated (t
1f6e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
1f6f0 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 *].** that was r
1f700 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 eturned from [sq
1f710 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1f720 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 ()] or one of it
1f730 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 s variants).** a
1f740 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 nd the second ar
1f750 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e gument is the in
1f760 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d dex of the colum
1f770 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f n for which info
1f780 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c rmation.** shoul
1f790 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 d be returned.
1f7a0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c The leftmost col
1f7b0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c umn of the resul
1f7c0 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e t set has the in
1f7d0 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 dex 0..**.** If
1f7e0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
1f7f0 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 t does not curre
1f800 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 ntly point to a
1f810 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 valid row, or if
1f820 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 the.** column i
1f830 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 ndex is out of r
1f840 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 ange, the result
1f850 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
1f860 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
1f870 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c may only be cal
1f880 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 led when the mos
1f890 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
1f8a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
1f8b0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 p()] has returne
1f8c0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 d [SQLITE_ROW] a
1f8d0 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 nd neither.** [s
1f8e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
1f8f0 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e nor [sqlite3_fin
1f900 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 alize()] have be
1f910 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 en called subseq
1f920 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e uently..** If an
1f930 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 y of these routi
1f940 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 nes are called a
1f950 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 fter [sqlite3_re
1f960 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 set()] or.** [sq
1f970 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
1f980 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 ] or after [sqli
1f990 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 te3_step()] has
1f9a0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 returned.** some
1f9b0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e thing other than
1f9c0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 [SQLITE_ROW], t
1f9d0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 he results are u
1f9e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 ndefined..** If
1f9f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1fa00 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 or [sqlite3_res
1fa10 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 et()] or [sqlite
1fa20 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 3_finalize()].**
1fa30 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d are called from
1fa40 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 a different thr
1fa50 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 ead while any of
1fa60 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a these routines.
1fa70 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 ** are pending,
1fa80 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 then the results
1fa90 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
1faa0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
1fab0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 3_column_type()
1fac0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
1fad0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 the.** [SQLITE_I
1fae0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 NTEGER | datatyp
1faf0 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 e code] for the
1fb00 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 initial data typ
1fb10 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 e.** of the resu
1fb20 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 lt column. The
1fb30 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 returned value i
1fb40 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 s one of [SQLITE
1fb50 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 _INTEGER],.** [S
1fb60 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 QLITE_FLOAT], [S
1fb70 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 QLITE_TEXT], [SQ
1fb80 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b LITE_BLOB], or [
1fb90 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 SQLITE_NULL]. T
1fba0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 he value.** retu
1fbb0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
1fbc0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 column_type() is
1fbd0 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c only meaningful
1fbe0 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 if no type.** c
1fbf0 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 onversions have
1fc00 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 occurred as desc
1fc10 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 ribed below. Af
1fc20 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 ter a type conve
1fc30 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 rsion,.** the va
1fc40 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
1fc50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
1fc60 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e ype() is undefin
1fc70 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 ed. Future.** v
1fc80 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
1fc90 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 e may change the
1fca0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c behavior of sql
1fcb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
1fcc0 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 ().** following
1fcd0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f a type conversio
1fce0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 n..**.** If the
1fcf0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 result is a BLOB
1fd00 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 or UTF-8 string
1fd10 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 then the sqlite
1fd20 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
1fd30 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 .** routine retu
1fd40 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
1fd50 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 f bytes in that
1fd60 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a BLOB or string..
1fd70 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 ** If the result
1fd80 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 is a UTF-16 str
1fd90 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 ing, then sqlite
1fda0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
1fdb0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 converts.** the
1fdc0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 string to UTF-8
1fdd0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e and then return
1fde0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
1fdf0 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 bytes..** If the
1fe00 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d result is a num
1fe10 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 eric value then
1fe20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
1fe30 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b ytes() uses.** [
1fe40 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
1fe50 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 ()] to convert t
1fe60 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 hat value to a U
1fe70 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 TF-8 string and
1fe80 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e returns.** the n
1fe90 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
1fea0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a n that string..*
1feb0 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 * The value retu
1fec0 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e rned does not in
1fed0 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 clude the zero t
1fee0 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 erminator at the
1fef0 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 end.** of the s
1ff00 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 tring. For clar
1ff10 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 ity: the value r
1ff20 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e eturned is the n
1ff30 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 umber of.** byte
1ff40 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c s in the string,
1ff50 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 not the number
1ff60 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a of characters..*
1ff70 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 *.** Strings ret
1ff80 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
1ff90 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 _column_text() a
1ffa0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
1ffb0 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 n_text16(),.** e
1ffc0 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 ven empty string
1ffd0 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 s, are always ze
1ffe0 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 ro terminated.
1fff0 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 The return.** va
20000 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 lue from sqlite3
20010 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 _column_blob() f
20020 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 or a zero-length
20030 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 BLOB is an arbi
20040 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 trary.** pointer
20050 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 , possibly even
20060 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
20070 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
20080 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
20090 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 () routine is si
200a0 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 milar to sqlite3
200b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a _column_bytes().
200c0 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 ** but leaves th
200d0 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d e result in UTF-
200e0 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 16 in native byt
200f0 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 e order instead
20100 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 of UTF-8..** The
20110 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
20120 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 is not included
20130 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a in this count..
20140 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 **.** The object
20150 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 returned by [sq
20160 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
20170 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b ue()] is an.** [
20180 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
20190 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
201a0 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 t. An unprotect
201b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
201c0 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f object.** may o
201d0 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 nly be used with
201e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 [sqlite3_bind_v
201f0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c alue()] and [sql
20200 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
20210 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 e()]..** If the
20220 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
20230 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
20240 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a ct returned by.*
20250 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
20260 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 n_value()] is us
20270 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 ed in any other
20280 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 way, including c
20290 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 alls.** to routi
202a0 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 nes like [sqlite
202b0 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 3_value_int()],
202c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
202d0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 ext()],.** or [s
202e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 qlite3_value_byt
202f0 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 es()], then the
20300 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 behavior is unde
20310 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 fined..**.** The
20320 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 se routines atte
20330 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 mpt to convert t
20340 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 he value where a
20350 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 ppropriate. For
20360 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 .** example, if
20370 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 the internal rep
20380 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 resentation is F
20390 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 LOAT and a text
203a0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 result.** is req
203b0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 uested, [sqlite3
203c0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 _snprintf()] is
203d0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 used internally
203e0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a to perform the.*
203f0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 * conversion aut
20400 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 omatically. The
20410 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 following table
20420 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e details the con
20430 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 versions.** that
20440 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a are applied:.**
20450 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
20460 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 .** <table borde
20470 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 r="1">.** <tr><t
20480 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 h> Internal<br>T
20490 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 ype <th> Request
204a0 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 ed<br>Type <th>
204b0 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a Conversion.**.*
204c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
204d0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
204e0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
204f0 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 s 0.** <tr><td>
20500 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 NULL <td> F
20510 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 LOAT <td> Res
20520 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 ult is 0.0.** <t
20530 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
20540 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
20550 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 td> Result is NU
20560 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 LL pointer.** <t
20570 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
20580 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
20590 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 td> Result is NU
205a0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 LL pointer.** <t
205b0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 r><td> INTEGER
205c0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
205d0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d td> Convert from
205e0 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 integer to floa
205f0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e t.** <tr><td> IN
20600 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 TEGER <td> TE
20610 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 XT <td> ASCII
20620 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 rendering of th
20630 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 e integer.** <tr
20640 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c ><td> INTEGER <
20650 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
20660 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 d> Same as INTEG
20670 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e ER->TEXT.** <tr>
20680 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 <td> FLOAT <t
20690 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
206a0 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 > Convert from f
206b0 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a loat to integer.
206c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f ** <tr><td> FLO
206d0 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 AT <td> TEXT
206e0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 <td> ASCII r
206f0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 endering of the
20700 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 float.** <tr><td
20710 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
20720 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 BLOB <td> S
20730 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 ame as FLOAT->TE
20740 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 XT.** <tr><td>
20750 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 TEXT <td> INT
20760 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 EGER <td> Use
20770 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 atoi().** <tr><t
20780 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
20790 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
207a0 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 Use atof().** <t
207b0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
207c0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
207d0 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a td> No change.**
207e0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 <tr><td> BLOB
207f0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 <td> INTEGER
20800 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 <td> Convert t
20810 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 o TEXT then use
20820 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 atoi().** <tr><t
20830 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e d> BLOB <td>
20840 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
20850 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 Convert to TEXT
20860 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a then use atof().
20870 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f ** <tr><td> BLO
20880 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 B <td> TEXT
20890 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a <td> Add a z
208a0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 ero terminator i
208b0 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 f needed.** </ta
208c0 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 ble>.** </blockq
208d0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 uote>.**.** The
208e0 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 table above make
208f0 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 s reference to s
20900 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
20910 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 y functions atoi
20920 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 ().** and atof()
20930 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e . SQLite does n
20940 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 ot really use th
20950 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 ese functions.
20960 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 It has its.** ow
20970 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 n equivalent int
20980 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 ernal routines.
20990 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 The atoi() and
209a0 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 atof() names are
209b0 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 .** used in the
209c0 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 table for brevit
209d0 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 y and because th
209e0 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 ey are familiar
209f0 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f to most.** C pro
20a00 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 grammers..**.**
20a10 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 Note that when t
20a20 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 ype conversions
20a30 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 occur, pointers
20a40 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f returned by prio
20a50 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 r.** calls to sq
20a60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
20a70 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c b(), sqlite3_col
20a80 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f umn_text(), and/
20a90 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f or.** sqlite3_co
20aa0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 lumn_text16() ma
20ab0 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 y be invalidated
20ac0 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 ..** Type conver
20ad0 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 sions and pointe
20ae0 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 r invalidations
20af0 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 might occur.** i
20b00 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 n the following
20b10 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c cases:.**.** <ul
20b20 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e >.** <li> The in
20b30 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 itial content is
20b40 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 a BLOB and sqli
20b50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
20b60 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c ) or.** sql
20b70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
20b80 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 16() is called.
20b90 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 A zero-terminat
20ba0 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 or might.**
20bb0 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 need to be adde
20bc0 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e d to the string.
20bd0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 </li>.** <li> Th
20be0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
20bf0 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 t is UTF-8 text
20c00 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
20c10 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a mn_bytes16() or.
20c20 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f ** sqlite3_
20c30 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
20c40 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 is called. The
20c50 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 content must be
20c60 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 converted.**
20c70 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 to UTF-16.</li
20c80 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e >.** <li> The in
20c90 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 itial content is
20ca0 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 UTF-16 text and
20cb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
20cc0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 bytes() or.**
20cd0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d sqlite3_colum
20ce0 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c n_text() is call
20cf0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 ed. The content
20d00 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 must be convert
20d10 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 ed.** to UT
20d20 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 F-8.</li>.** </u
20d30 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 l>.**.** Convers
20d40 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 ions between UTF
20d50 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 -16be and UTF-16
20d60 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f le are always do
20d70 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 ne in place and
20d80 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 do.** not invali
20d90 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 date a prior poi
20da0 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 nter, though of
20db0 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 course the conte
20dc0 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 nt of the buffer
20dd0 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 .** that the pri
20de0 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 or pointer point
20df0 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 s to will have b
20e00 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f een modified. O
20e10 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 ther kinds.** of
20e20 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 conversion are
20e30 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 done in place wh
20e40 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c en it is possibl
20e50 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 e, but sometimes
20e60 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 they.** are not
20e70 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e possible and in
20e80 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 those cases pri
20e90 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 or pointers are
20ea0 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a invalidated..**.
20eb0 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e ** The safest an
20ec0 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d d easiest to rem
20ed0 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 ember policy is
20ee0 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 to invoke these
20ef0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f routines.** in o
20f00 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
20f10 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 ing ways:.**.**
20f20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c <ul>.** <li>sql
20f30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
20f40 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 () followed by s
20f50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
20f60 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c tes()</li>.** <
20f70 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d li>sqlite3_colum
20f80 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 n_blob() followe
20f90 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
20fa0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e umn_bytes()</li>
20fb0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 .** <li>sqlite3
20fc0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
20fd0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c followed by sql
20fe0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
20ff0 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f s16()</li>.** </
21000 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 ul>.**.** In oth
21010 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 er words, you sh
21020 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 ould call sqlite
21030 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 3_column_text(),
21040 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
21050 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 mn_blob(), or sq
21060 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
21070 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 t16() first to f
21080 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a orce the result.
21090 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 ** into the desi
210a0 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e red format, then
210b0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
210c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f column_bytes() o
210d0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c r.** sqlite3_col
210e0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f umn_bytes16() to
210f0 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f find the size o
21100 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 f the result. D
21110 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a o not mix calls.
21120 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ** to sqlite3_co
21130 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 lumn_text() or s
21140 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
21150 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 ob() with calls
21160 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f to.** sqlite3_co
21170 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 lumn_bytes16(),
21180 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 and do not mix c
21190 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
211a0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a column_text16().
211b0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f ** with calls to
211c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
211d0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 bytes()..**.** T
211e0 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 he pointers retu
211f0 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 rned are valid u
21200 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 ntil a type conv
21210 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 ersion occurs as
21220 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 .** described ab
21230 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 ove, or until [s
21240 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f qlite3_step()] o
21250 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
21260 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
21270 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 e3_finalize()] i
21280 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d s called. The m
21290 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 emory space used
212a0 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 to hold strings
212b0 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 .** and BLOBs is
212c0 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 freed automatic
212d0 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 ally. Do <b>not
212e0 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f </b> pass the po
212f0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a inters returned.
21300 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
21310 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c mn_blob()], [sql
21320 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
21330 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a ()], etc. into.*
21340 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 * [sqlite3_free(
21350 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d )]..**.** If a m
21360 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
21370 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 error occurs du
21380 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 ring the evaluat
21390 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 ion of any.** of
213a0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c these routines,
213b0 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 a default value
213c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 is returned. T
213d0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 he default value
213e0 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 .** is either th
213f0 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 e integer 0, the
21400 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
21410 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 number 0.0, or a
21420 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 NULL.** pointer
21430 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 . Subsequent ca
21440 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
21450 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 errcode()] will
21460 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 return.** [SQLIT
21470 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 E_NOMEM]..**.**
21480 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
21490 20 5b 48 31 33 38 30 33 5d 20 5b 48 31 33 38 30 [H13803] [H1380
214a0 36 5d 20 5b 48 31 33 38 30 39 5d 20 5b 48 31 33 6] [H13809] [H13
214b0 38 31 32 5d 20 5b 48 31 33 38 31 35 5d 20 5b 48 812] [H13815] [H
214c0 31 33 38 31 38 5d 20 5b 48 31 33 38 32 31 5d 20 13818] [H13821]
214d0 5b 48 31 33 38 32 34 5d 0a 2a 2a 20 5b 48 31 33 [H13824].** [H13
214e0 38 32 37 5d 20 5b 48 31 33 38 33 30 5d 0a 2a 2f 827] [H13830].*/
214f0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
21500 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
21510 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
21520 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 int iCol);.int s
21530 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
21540 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 tes(sqlite3_stmt
21550 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e *, int iCol);.in
21560 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
21570 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 _bytes16(sqlite3
21580 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
21590 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 );.double sqlite
215a0 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 3_column_double(
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 69 6e 74 20 73 71 nt iCol);.int sq
215d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 lite3_column_int
215e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
215f0 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 int iCol);.sqlit
21600 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e3_int64 sqlite3
21610 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 _column_int64(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 63 6f 6e 73 74 20 75 6e iCol);.const un
21640 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c signed char *sql
21650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
21660 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
21670 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 int iCol);.const
21680 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
21690 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c olumn_text16(sql
216a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
216b0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 iCol);.int sqlit
216c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 e3_column_type(s
216d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
216e0 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 t iCol);.sqlite3
216f0 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f _value *sqlite3_
21700 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c column_value(sql
21710 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
21720 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 iCol);../*.** CA
21730 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 PI3REF: Destroy
21740 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
21750 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 ment Object {H13
21760 33 30 30 7d 20 3c 53 37 30 33 30 30 3e 3c 53 33 300} <S70300><S3
21770 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0100>.**.** The
21780 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
21790 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 () function is c
217a0 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 alled to delete
217b0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
217c0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 ement]..** If th
217d0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 e statement was
217e0 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73 executed success
217f0 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 fully or not exe
21800 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 cuted at all, th
21810 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 en.** SQLITE_OK
21820 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20 is returned. If
21830 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 execution of the
21840 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 statement faile
21850 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 d then an.** [er
21860 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 ror code] or [ex
21870 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 tended error cod
21880 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a e] is returned..
21890 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
218a0 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 ne can be called
218b0 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 at any point du
218c0 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 ring the executi
218d0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 on of the.** [pr
218e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
218f0 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75 ]. If the virtu
21900 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e al machine has n
21910 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 ot.** completed
21920 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 execution when t
21930 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 his routine is c
21940 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c alled, that is l
21950 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 ike.** encounter
21960 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 ing an error or
21970 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 an [sqlite3_inte
21980 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 rrupt | interrup
21990 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 t]..** Incomplet
219a0 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 e updates may be
219b0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 rolled back and
219c0 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 transactions ca
219d0 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e nceled,.** depen
219e0 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 ding on the circ
219f0 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 umstances, and t
21a00 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 he.** [error cod
21a10 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c e] returned will
21a20 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 be [SQLITE_ABOR
21a30 54 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 T]..**.** Requir
21a40 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 31 33 ements:.** [H113
21a50 30 32 5d 20 5b 48 31 31 33 30 34 5d 0a 2a 2f 0a 02] [H11304].*/.
21a60 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 int sqlite3_fina
21a70 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d lize(sqlite3_stm
21a80 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
21a90 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
21aa0 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 t A Prepared Sta
21ab0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 tement Object {H
21ac0 31 33 33 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a 13330} <S70300>.
21ad0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
21ae0 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 3_reset() functi
21af0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 on is called to
21b00 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 reset a [prepare
21b10 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 d statement].**
21b20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 object back to i
21b30 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 ts initial state
21b40 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 , ready to be re
21b50 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e -executed..** An
21b60 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 y SQL statement
21b70 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 variables that h
21b80 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 ad values bound
21b90 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a to them using.**
21ba0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 the [sqlite3_bi
21bb0 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 nd_blob | sqlite
21bc0 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 3_bind_*() API]
21bd0 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c retain their val
21be0 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c ues..** Use [sql
21bf0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 ite3_clear_bindi
21c00 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 ngs()] to reset
21c10 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a the bindings..**
21c20 0a 2a 2a 20 7b 48 31 31 33 33 32 7d 20 54 68 65 .** {H11332} The
21c30 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
21c40 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 S)] interface re
21c50 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 sets the [prepar
21c60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a ed statement] S.
21c70 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61 63 6b ** back
21c80 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e to the beginnin
21c90 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d g of its program
21ca0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d ..**.** {H11334}
21cb0 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 If the most rec
21cc0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ent call to [sql
21cd0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f ite3_step(S)] fo
21ce0 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 r the.**
21cf0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 [prepared stat
21d00 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 ement] S returne
21d10 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f d [SQLITE_ROW] o
21d20 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c r [SQLITE_DONE],
21d30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
21d40 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 if [sqlite3_step
21d50 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 (S)] has never b
21d60 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 efore been calle
21d70 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 d on S,.**
21d80 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 then [sqlite
21d90 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 3_reset(S)] retu
21da0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e rns [SQLITE_OK].
21db0 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20 .**.** {H11336}
21dc0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
21dd0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nt call to [sqli
21de0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 te3_step(S)] for
21df0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
21e00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
21e10 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 ment] S indicate
21e20 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e d an error, then
21e30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
21e40 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 lite3_reset(S)]
21e50 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f returns an appro
21e60 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f priate [error co
21e70 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 de]..**.** {H113
21e80 33 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 38} The [sqlite3
21e90 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 _reset(S)] inter
21ea0 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 face does not ch
21eb0 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a ange the values.
21ec0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 ** of a
21ed0 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ny [sqlite3_bind
21ee0 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 _blob|bindings]
21ef0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 on the [prepared
21f00 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a statement] S..*
21f10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 /.int sqlite3_re
21f20 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 set(sqlite3_stmt
21f30 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
21f40 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 CAPI3REF: Creat
21f50 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 e Or Redefine SQ
21f60 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 L Functions {H16
21f70 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 100} <S20200>.**
21f80 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 KEYWORDS: {func
21f90 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f tion creation ro
21fa0 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f utines}.** KEYWO
21fb0 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f RDS: {applicatio
21fc0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
21fd0 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f nction}.** KEYWO
21fe0 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f RDS: {applicatio
21ff0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
22000 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 nctions}.**.** T
22010 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f hese two functio
22020 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 ns (collectively
22030 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 known as "funct
22040 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 ion creation rou
22050 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 tines").** are u
22060 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 sed to add SQL f
22070 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 unctions or aggr
22080 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 egates or to red
22090 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 efine the behavi
220a0 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e or.** of existin
220b0 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 g SQL functions
220c0 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 or aggregates.
220d0 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 The only differe
220e0 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a nce between the.
220f0 2a 2a 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 ** two is that t
22100 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
22110 74 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 ter, the name of
22120 20 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 the (scalar) fu
22130 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 nction or.** agg
22140 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 regate, is encod
22150 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 ed in UTF-8 for
22160 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
22170 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 unction() and UT
22180 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 F-16.** for sqli
22190 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
221a0 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 ion16()..**.** T
221b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
221c0 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 er is the [datab
221d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
221e0 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c to which the SQL
221f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 .** function is
22200 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49 66 to be added. If
22210 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 a single progra
22220 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e m uses more than
22230 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a one database.**
22240 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 connection inte
22250 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c rnally, then SQL
22260 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 functions must
22270 62 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 be added individ
22280 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 ually to.** each
22290 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
222a0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tion..**.** The
222b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
222c0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
222d0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
222e0 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f to be created o
222f0 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 r.** redefined.
22300 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 The length of t
22310 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 he name is limit
22320 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c ed to 255 bytes,
22330 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a exclusive of.**
22340 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
22350 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 ator. Note that
22360 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 the name length
22370 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 limit is in byt
22380 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 es, not.** chara
22390 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 cters. Any atte
223a0 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 mpt to create a
223b0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 function with a
223c0 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 longer name.** w
223d0 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 ill result in [S
223e0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 QLITE_ERROR] bei
223f0 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a ng returned..**.
22400 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70 61 72 ** The third par
22410 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a ameter (nArg).**
22420 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
22430 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 f arguments that
22440 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
22450 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 n or.** aggregat
22460 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 e takes. If this
22470 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 parameter is ne
22480 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 gative, then the
22490 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 SQL function or
224a0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 .** aggregate ma
224b0 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 y take any numbe
224c0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a r of arguments..
224d0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 **.** The fourth
224e0 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 parameter, eTex
224f0 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 tRep, specifies
22500 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f what.** [SQLITE_
22510 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f UTF8 | text enco
22520 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 ding] this SQL f
22530 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 unction prefers
22540 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d for.** its param
22550 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 eters. Any SQL
22560 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
22570 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 ntation should b
22580 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a e able to work.*
22590 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d * work with UTF-
225a0 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 8, UTF-16le, or
225b0 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 UTF-16be. But s
225c0 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ome implementati
225d0 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f ons may be.** mo
225e0 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 re efficient wit
225f0 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 h one encoding t
22600 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 han another. It
22610 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a is allowed to.*
22620 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 * invoke sqlite3
22630 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
22640 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 () or sqlite3_cr
22650 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
22660 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 ) multiple.** ti
22670 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d mes with the sam
22680 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 e function but w
22690 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 ith different va
226a0 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 lues of eTextRep
226b0 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 ..** When multip
226c0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
226d0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 ns of the same f
226e0 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 unction are avai
226f0 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a lable, SQLite.**
22700 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f will pick the o
22710 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 ne that involves
22720 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e the least amoun
22730 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 t of data conver
22740 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 sion..** If ther
22750 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 e is only a sing
22760 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
22770 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 n which does not
22780 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a care what text.
22790 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 ** encoding is u
227a0 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f sed, then the fo
227b0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 urth argument sh
227c0 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f ould be [SQLITE_
227d0 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ANY]..**.** The
227e0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 fifth parameter
227f0 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 is an arbitrary
22800 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d pointer. The im
22810 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
22820 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 the.** function
22830 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 can gain access
22840 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 to this pointer
22850 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 using [sqlite3_u
22860 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a ser_data()]..**.
22870 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 ** The seventh,
22880 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 eighth and ninth
22890 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 parameters, xFu
228a0 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 nc, xStep and xF
228b0 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 inal, are.** poi
228c0 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 nters to C-langu
228d0 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 age functions th
228e0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 at implement the
228f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 SQL function or
22900 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 41 .** aggregate. A
22910 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 scalar SQL func
22920 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e tion requires an
22930 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
22940 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 of the xFunc.**
22950 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e callback only, N
22960 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f ULL pointers sho
22970 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73 uld be passed as
22980 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 the xStep and x
22990 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 Final.** paramet
229a0 65 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 ers. An aggregat
229b0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 e SQL function r
229c0 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 equires an imple
229d0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 mentation of xSt
229e0 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c ep.** and xFinal
229f0 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 and NULL should
22a00 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 be passed for x
22a10 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 Func. To delete
22a20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 an existing.** S
22a30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 QL function or a
22a40 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e ggregate, pass N
22a50 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 ULL for all thre
22a60 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 e function callb
22a70 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 acks..**.** It i
22a80 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 s permitted to r
22a90 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 egister multiple
22aa0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
22ab0 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 of the same.**
22ac0 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 functions with t
22ad0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 he same name but
22ae0 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 with either dif
22af0 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f fering numbers o
22b00 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f f.** arguments o
22b10 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 r differing pref
22b20 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 erred text encod
22b30 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69 ings. SQLite wi
22b40 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d ll use.** the im
22b50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 plementation mos
22b60 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 t closely matche
22b70 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 s the way in whi
22b80 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 ch the.** SQL fu
22b90 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 nction is used.
22ba0 20 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c A function impl
22bb0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 ementation with
22bc0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a a non-negative.*
22bd0 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 * nArg parameter
22be0 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 is a better mat
22bf0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 ch than a functi
22c00 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
22c10 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 n with.** a nega
22c20 74 69 76 65 20 6e 41 72 67 2e 20 20 41 20 66 75 tive nArg. A fu
22c30 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 nction where the
22c40 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 preferred text
22c50 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 encoding.** matc
22c60 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 hes the database
22c70 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 encoding is a b
22c80 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 etter.** match t
22c90 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 han a function w
22ca0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e here the encodin
22cb0 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 g is different.
22cc0 20 0a 2a 2a 20 41 20 66 75 6e 63 74 69 6f 6e 20 .** A function
22cd0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 where the encodi
22ce0 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 ng difference is
22cf0 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 between UTF16le
22d00 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 and UTF16be.**
22d10 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 is a closer matc
22d20 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f h than a functio
22d30 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f n where the enco
22d40 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 ding difference
22d50 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 is.** between UT
22d60 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a F8 and UTF16..**
22d70 0a 2a 2a 20 42 75 69 6c 74 2d 69 6e 20 66 75 6e .** Built-in fun
22d80 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 ctions may be ov
22d90 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 erloaded by new
22da0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
22db0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a ned functions..*
22dc0 2a 20 54 68 65 20 66 69 72 73 74 20 61 70 70 6c * The first appl
22dd0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
22de0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 function with a
22df0 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72 given name overr
22e00 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c ides all.** buil
22e10 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69 t-in functions i
22e20 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 n the same [data
22e30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
22e40 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e with the same n
22e50 61 6d 65 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 ame..** Subseque
22e60 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 nt application-d
22e70 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 efined functions
22e80 20 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61 6d of the same nam
22e90 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65 20 e only override
22ea0 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69 63 .** prior applic
22eb0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
22ec0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 nctions that are
22ed0 20 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68 20 an exact match
22ee0 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 for the.** numbe
22ef0 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 r of parameters
22f00 61 6e 64 20 70 72 65 66 65 72 72 65 64 20 65 6e and preferred en
22f10 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e coding..**.** An
22f20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
22f30 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 ined function is
22f40 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 permitted to ca
22f50 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 ll other.** SQLi
22f60 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 te interfaces.
22f70 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 However, such ca
22f80 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 lls must not.**
22f90 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 close the databa
22fa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f se connection no
22fb0 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 r finalize or re
22fc0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 set the prepared
22fd0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e .** statement in
22fe0 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 which the funct
22ff0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ion is running..
23000 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
23010 74 73 3a 0a 2a 2a 20 5b 48 31 36 31 30 33 5d 20 ts:.** [H16103]
23020 5b 48 31 36 31 30 36 5d 20 5b 48 31 36 31 30 39 [H16106] [H16109
23030 5d 20 5b 48 31 36 31 31 32 5d 20 5b 48 31 36 31 ] [H16112] [H161
23040 31 38 5d 20 5b 48 31 36 31 32 31 5d 20 5b 48 31 18] [H16121] [H1
23050 36 31 32 34 5d 20 5b 48 31 36 31 32 37 5d 0a 2a 6124] [H16127].*
23060 2a 20 5b 48 31 36 31 33 30 5d 20 5b 48 31 36 31 * [H16130] [H161
23070 33 33 5d 20 5b 48 31 36 31 33 36 5d 20 5b 48 31 33] [H16136] [H1
23080 36 31 33 39 5d 20 5b 48 31 36 31 34 32 5d 0a 2a 6139] [H16142].*
23090 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 /.int sqlite3_cr
230a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 eate_function(.
230b0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 sqlite3 *db,.
230c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e const char *zFun
230d0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 ctionName,. int
230e0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 nArg,. int eTe
230f0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 xtRep,. void *p
23100 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 App,. void (*xF
23110 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e unc)(sqlite3_con
23120 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
23130 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
23140 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 id (*xStep)(sqli
23150 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
23160 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
23170 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e ),. void (*xFin
23180 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 al)(sqlite3_cont
23190 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c ext*).);.int sql
231a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
231b0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 tion16(. sqlite
231c0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 3 *db,. const v
231d0 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 oid *zFunctionNa
231e0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a me,. int nArg,.
231f0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a int eTextRep,.
23200 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 void *pApp,.
23210 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 void (*xFunc)(sq
23220 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
23230 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
23240 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 **),. void (*xS
23250 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e tep)(sqlite3_con
23260 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
23270 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
23280 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c id (*xFinal)(sql
23290 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 ite3_context*).)
232a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
232b0 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 F: Text Encoding
232c0 73 20 7b 48 31 30 32 36 37 7d 20 3c 53 35 30 32 s {H10267} <S502
232d0 30 30 3e 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 00> <H16100>.**.
232e0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
232f0 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 t define integer
23300 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 codes that repr
23310 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 esent the variou
23320 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 s.** text encodi
23330 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 ngs supported by
23340 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 SQLite..*/.#def
23350 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 ine SQLITE_UTF8
23360 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 1.#def
23370 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
23380 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 LE 2.#def
23390 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
233a0 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 BE 3.#def
233b0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
233c0 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 4 /
233d0 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 * Use native byt
233e0 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 e order */.#defi
233f0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 ne SQLITE_ANY
23400 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 5 /*
23410 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
23420 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f function only */
23430 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
23440 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 UTF16_ALIGNED 8
23450 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 /* sqlite3_c
23460 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 reate_collation
23470 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 only */../*.** C
23480 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 API3REF: Depreca
23490 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a ted Functions.**
234a0 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a DEPRECATED.**.*
234b0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e * These function
234c0 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 s are [deprecate
234d0 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f d]. In order to
234e0 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 maintain.** bac
234f0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
23500 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 lity with older
23510 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 code, these func
23520 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a tions continue .
23530 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 ** to be support
23540 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 ed. However, ne
23550 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 w applications s
23560 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 hould avoid.** t
23570 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 he use of these
23580 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 functions. To h
23590 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 elp encourage pe
235a0 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a ople to avoid.**
235b0 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e using these fun
235c0 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e ctions, we are n
235d0 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c ot going to tell
235e0 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 you what they d
235f0 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 o..*/.#ifndef SQ
23600 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 LITE_OMIT_DEPREC
23610 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 ATED.SQLITE_DEPR
23620 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
23630 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 e3_aggregate_cou
23640 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 nt(sqlite3_conte
23650 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 xt*);.SQLITE_DEP
23660 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
23670 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 te3_expired(sqli
23680 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 te3_stmt*);.SQLI
23690 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
236a0 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 t sqlite3_transf
236b0 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 er_bindings(sqli
236c0 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 te3_stmt*, sqlit
236d0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 e3_stmt*);.SQLIT
236e0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
236f0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f sqlite3_global_
23700 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 recover(void);.S
23710 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
23720 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 void sqlite3_th
23730 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 read_cleanup(voi
23740 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 d);.SQLITE_DEPRE
23750 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
23760 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 3_memory_alarm(v
23770 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c oid(*)(void*,sql
23780 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c ite3_int64,int),
23790 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e void*,sqlite3_in
237a0 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a t64);.#endif../*
237b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 .** CAPI3REF: Ob
237c0 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 taining SQL Func
237d0 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 tion Parameter V
237e0 61 6c 75 65 73 20 7b 48 31 35 31 30 30 7d 20 3c alues {H15100} <
237f0 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S20200>.**.** Th
23800 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 e C-language imp
23810 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 lementation of S
23820 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 QL functions and
23830 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 aggregates uses
23840 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 .** this set of
23850 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e interface routin
23860 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 es to access the
23870 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 parameter value
23880 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 s on.** the func
23890 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 tion or aggregat
238a0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 e..**.** The xFu
238b0 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 nc (for scalar f
238c0 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 unctions) or xSt
238d0 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 ep (for aggregat
238e0 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a es) parameters.*
238f0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 * to [sqlite3_cr
23900 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
23910 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 and [sqlite3_cr
23920 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
23930 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c )].** define cal
23940 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c lbacks that impl
23950 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 ement the SQL fu
23960 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
23970 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 egates..** The 4
23980 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
23990 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 these callbacks
239a0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
239b0 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 ointers to.** [p
239c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
239d0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e _value] objects.
239e0 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b There is one [
239f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
23a00 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 bject for.** eac
23a10 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
23a20 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e he SQL function.
23a30 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 These routines
23a40 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 are used to.**
23a50 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 extract values f
23a60 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 rom the [sqlite3
23a70 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e _value] objects.
23a80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
23a90 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 tines work only
23aa0 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 with [protected
23ab0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
23ac0 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 bjects..** Any a
23ad0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 ttempt to use th
23ae0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 ese routines on
23af0 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 an [unprotected
23b00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a sqlite3_value].*
23b10 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 * object results
23b20 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 in undefined be
23b30 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 havior..**.** Th
23b40 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 ese routines wor
23b50 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 k just like the
23b60 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 corresponding [c
23b70 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e olumn access fun
23b80 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 ctions].** excep
23b90 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f t that these ro
23ba0 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 utines take a si
23bb0 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 ngle [protected
23bc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
23bd0 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 bject.** pointer
23be0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 instead of a [s
23bf0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f qlite3_stmt*] po
23c00 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 inter and an int
23c10 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 eger column numb
23c20 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 er..**.** The sq
23c30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
23c40 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 16() interface e
23c50 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 xtracts a UTF-16
23c60 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 string.** in th
23c70 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 e native byte-or
23c80 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 der of the host
23c90 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a machine. The.**
23ca0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
23cb0 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 ext16be() and sq
23cc0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
23cd0 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 16le() interface
23ce0 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 s.** extract UTF
23cf0 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 -16 strings as b
23d00 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 ig-endian and li
23d10 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 ttle-endian resp
23d20 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ectively..**.**
23d30 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
23d40 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 e_numeric_type()
23d50 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d interface attem
23d60 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 pts to apply.**
23d70 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 numeric affinity
23d80 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 to the value.
23d90 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 This means that
23da0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a an attempt is.**
23db0 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 made to convert
23dc0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e the value to an
23dd0 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 integer or floa
23de0 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a ting point. If.
23df0 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 ** such a conver
23e00 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 sion is possible
23e10 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 without loss of
23e20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e information (in
23e30 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c other.** words,
23e40 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 if the value is
23e50 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c a string that l
23e60 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 ooks like a numb
23e70 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 er).** then the
23e80 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 conversion is pe
23e90 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 rformed. Otherw
23ea0 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f ise no conversio
23eb0 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 n occurs..** The
23ec0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 [SQLITE_INTEGER
23ed0 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 | datatype] aft
23ee0 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 er conversion is
23ef0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
23f00 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 Please pay part
23f10 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e icular attention
23f20 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 to the fact tha
23f30 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 t the pointer re
23f40 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b turned.** from [
23f50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c sqlite3_value_bl
23f60 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f ob()], [sqlite3_
23f70 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f value_text()], o
23f80 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 r.** [sqlite3_va
23f90 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 lue_text16()] ca
23fa0 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 n be invalidated
23fb0 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 by a subsequent
23fc0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
23fd0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
23fe0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 ()], [sqlite3_va
23ff0 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 lue_bytes16()],
24000 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
24010 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 ext()],.** or [s
24020 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
24030 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 t16()]..**.** Th
24040 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 ese routines mus
24050 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d t be called from
24060 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
24070 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 as.** the SQL f
24080 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 unction that sup
24090 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 plied the [sqlit
240a0 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d e3_value*] param
240b0 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 eters..**.** Req
240c0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
240d0 31 35 31 30 33 5d 20 5b 48 31 35 31 30 36 5d 20 15103] [H15106]
240e0 5b 48 31 35 31 30 39 5d 20 5b 48 31 35 31 31 32 [H15109] [H15112
240f0 5d 20 5b 48 31 35 31 31 35 5d 20 5b 48 31 35 31 ] [H15115] [H151
24100 31 38 5d 20 5b 48 31 35 31 32 31 5d 20 5b 48 31 18] [H15121] [H1
24110 35 31 32 34 5d 0a 2a 2a 20 5b 48 31 35 31 32 37 5124].** [H15127
24120 5d 20 5b 48 31 35 31 33 30 5d 20 5b 48 31 35 31 ] [H15130] [H151
24130 33 33 5d 20 5b 48 31 35 31 33 36 5d 0a 2a 2f 0a 33] [H15136].*/.
24140 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
24150 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 te3_value_blob(s
24160 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
24170 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
24180 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f e_bytes(sqlite3_
24190 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c value*);.int sql
241a0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
241b0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 16(sqlite3_value
241c0 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 *);.double sqlit
241d0 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 e3_value_double(
241e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
241f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c .int sqlite3_val
24200 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 ue_int(sqlite3_v
24210 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f alue*);.sqlite3_
24220 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 int64 sqlite3_va
24230 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 lue_int64(sqlite
24240 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 3_value*);.const
24250 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a unsigned char *
24260 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
24270 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 xt(sqlite3_value
24280 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a *);.const void *
24290 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
242a0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c xt16(sqlite3_val
242b0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 ue*);.const void
242c0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f *sqlite3_value_
242d0 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 text16le(sqlite3
242e0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 _value*);.const
242f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 void *sqlite3_va
24300 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c lue_text16be(sql
24310 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e ite3_value*);.in
24320 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f t sqlite3_value_
24330 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c type(sqlite3_val
24340 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ue*);.int sqlite
24350 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 3_value_numeric_
24360 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c type(sqlite3_val
24370 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ue*);../*.** CAP
24380 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 I3REF: Obtain Ag
24390 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e gregate Function
243a0 20 43 6f 6e 74 65 78 74 20 7b 48 31 36 32 31 30 Context {H16210
243b0 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a } <S20200>.**.**
243c0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 The implementat
243d0 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65 ion of aggregate
243e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 SQL functions u
243f0 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 se this routine
24400 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 to allocate.** a
24410 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 structure for s
24420 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 toring their sta
24430 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 te..**.** The fi
24440 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c rst time the sql
24450 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
24460 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65 ontext() routine
24470 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 is called for a
24480 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 61 .** particular a
24490 67 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74 65 ggregate, SQLite
244a0 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 allocates nByte
244b0 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 s of memory, zer
244c0 6f 65 73 20 6f 75 74 20 74 68 61 74 0a 2a 2a 20 oes out that.**
244d0 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 memory, and retu
244e0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
244f0 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 61 it. On second a
24500 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 nd subsequent ca
24510 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 lls to.** sqlite
24520 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
24530 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 ext() for the sa
24540 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e me aggregate fun
24550 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 ction index,.**
24560 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 the same buffer
24570 69 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65 is returned. The
24580 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
24590 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 of the aggregate
245a0 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74 68 65 20 can use.** the
245b0 72 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 returned buffer
245c0 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 to accumulate da
245d0 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ta..**.** SQLite
245e0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 automatically f
245f0 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 rees the allocat
24600 65 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 74 ed buffer when t
24610 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 he aggregate.**
24620 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e query concludes.
24630 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
24640 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c parameter shoul
24650 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 d be a copy of t
24660 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 he.** [sqlite3_c
24670 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e ontext | SQL fun
24680 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 ction context] t
24690 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 hat is the first
246a0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f parameter.** to
246b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f the callback ro
246c0 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 utine that imple
246d0 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 ments the aggreg
246e0 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a ate function..**
246f0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
24700 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
24710 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
24720 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a read in which.**
24730 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 the aggregate S
24740 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 QL function is r
24750 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 unning..**.** Re
24760 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
24770 48 31 36 32 31 31 5d 20 5b 48 31 36 32 31 33 5d H16211] [H16213]
24780 20 5b 48 31 36 32 31 35 5d 20 5b 48 31 36 32 31 [H16215] [H1621
24790 37 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 7].*/.void *sqli
247a0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
247b0 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f ntext(sqlite3_co
247c0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 ntext*, int nByt
247d0 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 es);../*.** CAPI
247e0 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 3REF: User Data
247f0 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 For Functions {H
24800 31 36 32 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a 16240} <S20200>.
24810 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
24820 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 3_user_data() in
24830 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
24840 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 a copy of.** the
24850 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 pointer that wa
24860 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 s the pUserData
24870 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 parameter (the 5
24880 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a th parameter).**
24890 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
248a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
248b0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 ()].** and [sqli
248c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
248d0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 ion16()] routine
248e0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c s that originall
248f0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 y.** registered
24900 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
24910 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
24920 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 . {END}.**.** Th
24930 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 is routine must
24940 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 be called from t
24950 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 he same thread i
24960 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 n which.** the a
24970 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
24980 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 ed function is r
24990 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 unning..**.** Re
249a0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
249b0 48 31 36 32 34 33 5d 0a 2a 2f 0a 76 6f 69 64 20 H16243].*/.void
249c0 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 *sqlite3_user_da
249d0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ta(sqlite3_conte
249e0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 xt*);../*.** CAP
249f0 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 I3REF: Database
24a00 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 Connection For F
24a10 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35 30 unctions {H16250
24a20 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32 30 32 30 } <S60600><S2020
24a30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0>.**.** The sql
24a40 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f ite3_context_db_
24a50 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 handle() interfa
24a60 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 ce returns a cop
24a70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e y of.** the poin
24a80 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 ter to the [data
24a90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
24aa0 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 (the 1st parame
24ab0 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b ter).** of the [
24ac0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
24ad0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e unction()].** an
24ae0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
24af0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 e_function16()]
24b00 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 routines that or
24b10 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 iginally.** regi
24b20 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 stered the appli
24b30 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 cation defined f
24b40 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 unction..**.** R
24b50 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
24b60 5b 48 31 36 32 35 33 5d 0a 2a 2f 0a 73 71 6c 69 [H16253].*/.sqli
24b70 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e te3 *sqlite3_con
24b80 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 text_db_handle(s
24b90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
24ba0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
24bb0 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 F: Function Auxi
24bc0 6c 69 61 72 79 20 44 61 74 61 20 7b 48 31 36 32 liary Data {H162
24bd0 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 70} <S20200>.**.
24be0 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ** The following
24bf0 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d two functions m
24c00 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 ay be used by sc
24c10 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f alar SQL functio
24c20 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 ns to.** associa
24c30 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 te metadata with
24c40 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 argument values
24c50 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 . If the same va
24c60 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f lue is passed to
24c70 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 .** multiple inv
24c80 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ocations of the
24c90 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f same SQL functio
24ca0 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 n during query e
24cb0 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a xecution, under.
24cc0 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 ** some circumst
24cd0 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 ances the associ
24ce0 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 ated metadata ma
24cf0 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 y be preserved.
24d00 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 This may.** be u
24d10 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 sed, for example
24d20 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c , to add a regul
24d30 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 ar-expression ma
24d40 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a tching scalar.**
24d50 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 function. The c
24d60 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 ompiled version
24d70 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 of the regular e
24d80 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f xpression is sto
24d90 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 red as.** metada
24da0 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ta associated wi
24db0 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 th the SQL value
24dc0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 passed as the r
24dd0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f egular expressio
24de0 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 n.** pattern. T
24df0 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 he compiled regu
24e00 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 lar expression c
24e10 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 an be reused on
24e20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f multiple.** invo
24e30 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 cations of the s
24e40 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 ame function so
24e50 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 that the origina
24e60 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 l pattern string
24e70 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 .** does not nee
24e80 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c d to be recompil
24e90 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 ed on each invoc
24ea0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ation..**.** The
24eb0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 sqlite3_get_aux
24ec0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 data() interface
24ed0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
24ee0 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 er to the metada
24ef0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 ta.** associated
24f00 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f by the sqlite3_
24f10 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 set_auxdata() fu
24f20 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 nction with the
24f30 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 Nth argument.**
24f40 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 value to the app
24f50 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
24f60 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f function. If no
24f70 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 metadata has be
24f80 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 en ever.** been
24f90 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 set for the Nth
24fa0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 argument of the
24fb0 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 function, or if
24fc0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
24fd0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 g.** function pa
24fe0 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e rameter has chan
24ff0 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 ged since the me
25000 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c ta-data was set,
25010 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 .** then sqlite3
25020 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 _get_auxdata() r
25030 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
25040 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 inter..**.** The
25050 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
25060 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 data() interface
25070 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 saves the metad
25080 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 ata.** pointed t
25090 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 o by its 3rd par
250a0 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 ameter as the me
250b0 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e tadata for the N
250c0 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 -th.** argument
250d0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
250e0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
250f0 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 ion. Subsequent
25100 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c .** calls to sql
25110 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
25120 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 () might return
25130 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 this data, if it
25140 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e has.** not been
25150 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 destroyed..** I
25160 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c f it is not NULL
25170 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e , SQLite will in
25180 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 voke the destruc
25190 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 tor.** function
251a0 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 given by the 4th
251b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
251c0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
251d0 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 a() on.** the me
251e0 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 tadata when the
251f0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 corresponding fu
25200 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 nction parameter
25210 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 changes.** or w
25220 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 hen the SQL stat
25230 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c ement completes,
25240 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 whichever comes
25250 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 first..**.** SQ
25260 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 Lite is free to
25270 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 call the destruc
25280 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 tor and drop met
25290 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 adata on any.**
252a0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 parameter of any
252b0 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 function at any
252c0 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 time. The only
252d0 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 guarantee is th
252e0 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 at.** the destru
252f0 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c ctor will be cal
25300 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d led before the m
25310 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 etadata is dropp
25320 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 ed..**.** In pra
25330 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 ctice, metadata
25340 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 is preserved bet
25350 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 ween function ca
25360 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 lls for.** expre
25370 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 ssions that are
25380 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 constant at comp
25390 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 ile time. This i
253a0 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a ncludes literal.
253b0 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 ** values and SQ
253c0 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a L variables..**.
253d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
253e0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 s must be called
253f0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 from the same t
25400 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a hread in which.*
25410 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 * the SQL functi
25420 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a on is running..*
25430 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
25440 73 3a 0a 2a 2a 20 5b 48 31 36 32 37 32 5d 20 5b s:.** [H16272] [
25450 48 31 36 32 37 34 5d 20 5b 48 31 36 32 37 36 5d H16274] [H16276]
25460 20 5b 48 31 36 32 37 37 5d 20 5b 48 31 36 32 37 [H16277] [H1627
25470 38 5d 20 5b 48 31 36 32 37 39 5d 0a 2a 2f 0a 76 8] [H16279].*/.v
25480 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 oid *sqlite3_get
25490 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 _auxdata(sqlite3
254a0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e _context*, int N
254b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
254c0 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 set_auxdata(sqli
254d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
254e0 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 t N, void*, void
254f0 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a (*)(void*));...
25500 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
25510 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 Constants Defini
25520 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 ng Special Destr
25530 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20 7b uctor Behavior {
25540 48 31 30 32 38 30 7d 20 3c 53 33 30 31 30 30 3e H10280} <S30100>
25550 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 .**.** These are
25560 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 special values
25570 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 for the destruct
25580 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 or that is passe
25590 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 d in as the.** f
255a0 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f inal argument to
255b0 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b routines like [
255c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
255d0 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 lob()]. If the
255e0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 destructor.** ar
255f0 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 gument is SQLITE
25600 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e _STATIC, it mean
25610 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 s that the conte
25620 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f nt pointer is co
25630 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 nstant.** and wi
25640 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e ll never change.
25650 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 It does not ne
25660 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 ed to be destroy
25670 65 64 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 ed. The.** SQLI
25680 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c TE_TRANSIENT val
25690 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 ue means that th
256a0 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c e content will l
256b0 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a ikely change in.
256c0 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 ** the near futu
256d0 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 re and that SQLi
256e0 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 te should make i
256f0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 ts own private c
25700 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f opy of.** the co
25710 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 ntent before ret
25720 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 urning..**.** Th
25730 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 e typedef is nec
25740 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 essary to work a
25750 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 round problems i
25760 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b n certain.** C++
25770 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 compilers. See
25780 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a ticket #2191..*
25790 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 /.typedef void (
257a0 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 *sqlite3_destruc
257b0 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 tor_type)(void*)
257c0 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ;.#define SQLITE
257d0 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 _STATIC ((s
257e0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f qlite3_destructo
257f0 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e r_type)0).#defin
25800 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 e SQLITE_TRANSIE
25810 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 NT ((sqlite3_d
25820 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d estructor_type)-
25830 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 1)../*.** CAPI3R
25840 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 EF: Setting The
25850 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c Result Of An SQL
25860 20 46 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34 30 Function {H1640
25870 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 0} <S20200>.**.*
25880 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
25890 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 are used by the
258a0 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c xFunc or xFinal
258b0 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a callbacks that.
258c0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c ** implement SQL
258d0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 functions and a
258e0 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a ggregates. See.
258f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ** [sqlite3_crea
25900 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 te_function()] a
25910 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
25920 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
25930 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e .** for addition
25940 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
25950 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 **.** These func
25960 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 tions work very
25970 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 much like the [p
25980 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 arameter binding
25990 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 ] family of.** f
259a0 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f unctions used to
259b0 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 bind values to
259c0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 host parameters
259d0 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 in prepared stat
259e0 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 ements..** Refer
259f0 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 to the [SQL par
25a00 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 ameter] document
25a10 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 ation for additi
25a20 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
25a30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
25a40 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
25a50 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
25a60 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
25a70 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 .** an applicati
25a80 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
25a90 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c ion to be the BL
25aa0 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 OB whose content
25ab0 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 is pointed.** t
25ac0 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 o by the second
25ad0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 parameter and wh
25ae0 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c ich is N bytes l
25af0 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 ong where N is t
25b00 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 he.** third para
25b10 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 meter..**.** The
25b20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
25b30 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 zeroblob() inter
25b40 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 faces set the re
25b50 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 sult of.** the a
25b60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
25b70 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
25b80 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e e a BLOB contain
25b90 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 ing all zero.**
25ba0 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 bytes and N byte
25bb0 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 s in size, where
25bc0 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 N is the value
25bd0 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d of the 2nd param
25be0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eter..**.** The
25bf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 sqlite3_result_d
25c00 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 ouble() interfac
25c10 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c e sets the resul
25c20 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 t from.** an app
25c30 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
25c40 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
25c50 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 a floating point
25c60 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 value specified
25c70 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 .** by its 2nd a
25c80 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 rgument..**.** T
25c90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
25ca0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 t_error() and sq
25cb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
25cc0 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 or16() functions
25cd0 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d .** cause the im
25ce0 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 plemented SQL fu
25cf0 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 nction to throw
25d00 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a an exception..**
25d10 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 SQLite uses the
25d20 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 string pointed
25d30 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 to by the.** 2nd
25d40 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 parameter of sq
25d50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
25d60 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f or() or sqlite3_
25d70 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
25d80 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 .** as the text
25d90 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 of an error mess
25da0 61 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 age. SQLite int
25db0 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f erprets the erro
25dc0 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 r.** message str
25dd0 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ing from sqlite3
25de0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 _result_error()
25df0 61 73 20 55 54 46 2d 38 2e 20 53 51 4c 69 74 65 as UTF-8. SQLite
25e00 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 .** interprets t
25e10 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 he string from s
25e20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
25e30 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 ror16() as UTF-1
25e40 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 6 in native.** b
25e50 79 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74 yte order. If t
25e60 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
25e70 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
25e80 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 sult_error().**
25e90 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c or sqlite3_resul
25ea0 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e t_error16() is n
25eb0 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c egative then SQL
25ec0 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 ite takes as the
25ed0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 error.** messag
25ee0 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 e all text up th
25ef0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 rough the first
25f00 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a zero character..
25f10 2a 2a 20 49 66 20 74 68 65 20 74 68 69 72 64 20 ** If the third
25f20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
25f30 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
25f40 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 r() or.** sqlite
25f50 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
25f60 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 () is non-negati
25f70 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 ve then SQLite t
25f80 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a akes that many.*
25f90 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 * bytes (not cha
25fa0 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 racters) from th
25fb0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
25fc0 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 as the error mes
25fd0 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c sage..** The sql
25fe0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
25ff0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f r() and sqlite3_
26000 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
26010 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b .** routines mak
26020 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 e a private copy
26030 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 of the error me
26040 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 ssage text befor
26050 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e e.** they return
26060 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 . Hence, the ca
26070 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 lling function c
26080 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 an deallocate or
26090 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 .** modify the t
260a0 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 ext after they r
260b0 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 eturn without ha
260c0 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 rm..** The sqlit
260d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
260e0 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 code() function
260f0 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f changes the erro
26100 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e r code.** return
26110 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 ed by SQLite as
26120 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 a result of an e
26130 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 rror in a functi
26140 6f 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c on. By default,
26150 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f .** the error co
26160 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 de is SQLITE_ERR
26170 4f 52 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e OR. A subsequen
26180 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 t call to sqlite
26190 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
261a0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 .** or sqlite3_r
261b0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 esult_error16()
261c0 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 resets the error
261d0 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f code to SQLITE_
261e0 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ERROR..**.** The
261f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
26200 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 toobig() interfa
26210 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 ce causes SQLite
26220 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 to throw an err
26230 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 or.** indicating
26240 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f that a string o
26250 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e r BLOB is to lon
26260 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a g to represent..
26270 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
26280 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 3_result_nomem()
26290 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 interface cause
262a0 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f s SQLite to thro
262b0 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e w an error.** in
262c0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 dicating that a
262d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
262e0 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 n failed..**.**
262f0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
26300 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 lt_int() interfa
26310 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 ce sets the retu
26320 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 rn value.** of t
26330 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
26340 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
26350 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 to be the 32-bit
26360 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a signed integer.
26370 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 ** value given i
26380 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 n the 2nd argume
26390 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 nt..** The sqlit
263a0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 e3_result_int64(
263b0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
263c0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
263d0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c e.** of the appl
263e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
263f0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 function to be t
26400 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 he 64-bit signed
26410 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 integer.** valu
26420 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 e given in the 2
26430 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a nd argument..**.
26440 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
26450 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 esult_null() int
26460 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
26470 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 return value.**
26480 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
26490 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
264a0 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a ion to be NULL..
264b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
264c0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 3_result_text(),
264d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
264e0 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c text16(),.** sql
264f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
26500 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 16le(), and sqli
26510 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
26520 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 6be() interfaces
26530 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 .** set the retu
26540 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 rn value of the
26550 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
26560 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
26570 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 be.** a text str
26580 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 ing which is rep
26590 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d resented as UTF-
265a0 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 8, UTF-16 native
265b0 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 byte order,.**
265c0 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e UTF-16 little en
265d0 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 dian, or UTF-16
265e0 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 big endian, resp
265f0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c ectively..** SQL
26600 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 ite takes the te
26610 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 xt result from t
26620 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 he application f
26630 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 rom.** the 2nd p
26640 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 arameter of the
26650 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
26660 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e ext* interfaces.
26670 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 .** If the 3rd p
26680 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
26690 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
266a0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a ext* interfaces.
266b0 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 ** is negative,
266c0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 then SQLite take
266d0 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 s result text fr
266e0 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d om the 2nd param
266f0 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 eter.** through
26700 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 the first zero c
26710 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 haracter..** If
26720 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
26730 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
26740 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
26750 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e terfaces.** is n
26760 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 on-negative, the
26770 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 n as many bytes
26780 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 (not characters)
26790 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 of the text.**
267a0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 pointed to by th
267b0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
267c0 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 are taken as the
267d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
267e0 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e ined.** function
267f0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 result..** If t
26800 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
26810 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
26820 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
26830 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 erfaces.** or sq
26840 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f lite3_result_blo
26850 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 b is a non-NULL
26860 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 pointer, then SQ
26870 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a Lite calls that.
26880 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 ** function as t
26890 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e he destructor on
268a0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f the text or BLO
268b0 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 B result when it
268c0 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 has.** finished
268d0 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 using that resu
268e0 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 lt..** If the 4t
268f0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
26900 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
26910 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
26920 65 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 es or.** sqlite3
26930 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 _result_blob is
26940 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 the special cons
26950 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 tant SQLITE_STAT
26960 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a IC, then SQLite.
26970 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 ** assumes that
26980 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 the text or BLOB
26990 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f result is in co
269a0 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 nstant space and
269b0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 does not.** cop
269c0 79 20 74 68 65 20 69 74 20 6f 72 20 63 61 6c 6c y the it or call
269d0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 77 68 a destructor wh
269e0 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 en it has finish
269f0 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 ed using that re
26a00 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 sult..** If the
26a10 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
26a20 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
26a30 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
26a40 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 aces.** or sqlit
26a50 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 e3_result_blob i
26a60 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f s the special co
26a70 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 nstant SQLITE_TR
26a80 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 ANSIENT.** then
26a90 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 SQLite makes a c
26aa0 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c opy of the resul
26ab0 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 t into space obt
26ac0 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 ained from.** fr
26ad0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
26ae0 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 oc()] before it
26af0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 returns..**.** T
26b00 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
26b10 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 t_value() interf
26b20 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 ace sets the res
26b30 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 ult of.** the ap
26b40 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
26b50 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
26b60 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b a copy the.** [
26b70 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
26b80 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
26b90 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 t specified by t
26ba0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
26bb0 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 . The.** sqlite
26bc0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
26bd0 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 interface makes
26be0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b a copy of the [
26bf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a sqlite3_value].*
26c00 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 * so that the [s
26c10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 qlite3_value] sp
26c20 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 ecified in the p
26c30 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 arameter may cha
26c40 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 nge or.** be dea
26c50 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 llocated after s
26c60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 qlite3_result_va
26c70 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 lue() returns wi
26c80 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 thout harm..** A
26c90 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
26ca0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
26cb0 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 t may always be
26cc0 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a used where an.**
26cd0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
26ce0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
26cf0 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c ect is required,
26d00 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 so either.** ki
26d10 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 nd of [sqlite3_v
26d20 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e alue] object can
26d30 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 be used with th
26d40 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a is interface..**
26d50 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 .** If these rou
26d60 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
26d70 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 from within the
26d80 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
26d90 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e d.** than the on
26da0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 e containing the
26db0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
26dc0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 ined function th
26dd0 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 at received.** t
26de0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 he [sqlite3_cont
26df0 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 ext] pointer, th
26e00 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
26e10 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 defined..**.** R
26e20 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
26e30 5b 48 31 36 34 30 33 5d 20 5b 48 31 36 34 30 36 [H16403] [H16406
26e40 5d 20 5b 48 31 36 34 30 39 5d 20 5b 48 31 36 34 ] [H16409] [H164
26e50 31 32 5d 20 5b 48 31 36 34 31 35 5d 20 5b 48 31 12] [H16415] [H1
26e60 36 34 31 38 5d 20 5b 48 31 36 34 32 31 5d 20 5b 6418] [H16421] [
26e70 48 31 36 34 32 34 5d 0a 2a 2a 20 5b 48 31 36 34 H16424].** [H164
26e80 32 37 5d 20 5b 48 31 36 34 33 30 5d 20 5b 48 31 27] [H16430] [H1
26e90 36 34 33 33 5d 20 5b 48 31 36 34 33 36 5d 20 5b 6433] [H16436] [
26ea0 48 31 36 34 33 39 5d 20 5b 48 31 36 34 34 32 5d H16439] [H16442]
26eb0 20 5b 48 31 36 34 34 35 5d 20 5b 48 31 36 34 34 [H16445] [H1644
26ec0 38 5d 0a 2a 2a 20 5b 48 31 36 34 35 31 5d 20 5b 8].** [H16451] [
26ed0 48 31 36 34 35 34 5d 20 5b 48 31 36 34 35 37 5d H16454] [H16457]
26ee0 20 5b 48 31 36 34 36 30 5d 20 5b 48 31 36 34 36 [H16460] [H1646
26ef0 33 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 3].*/.void sqlit
26f00 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 e3_result_blob(s
26f10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
26f20 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
26f30 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
26f40 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
26f50 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 _result_double(s
26f60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
26f70 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 double);.void s
26f80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
26f90 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ror(sqlite3_cont
26fa0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 ext*, const char
26fb0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 *, int);.void sq
26fc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
26fd0 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e or16(sqlite3_con
26fe0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
26ff0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 d*, int);.void s
27000 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
27010 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 ror_toobig(sqlit
27020 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f e3_context*);.vo
27030 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
27040 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 t_error_nomem(sq
27050 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
27060 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
27070 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 sult_error_code(
27080 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
27090 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c , int);.void sql
270a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 ite3_result_int(
270b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
270c0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c , int);.void sql
270d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 ite3_result_int6
270e0 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 4(sqlite3_contex
270f0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 t*, sqlite3_int6
27100 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 4);.void sqlite3
27110 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c _result_null(sql
27120 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
27130 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
27140 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 ult_text(sqlite3
27150 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
27160 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 char*, int, voi
27170 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f d(*)(void*));.vo
27180 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
27190 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 t_text16(sqlite3
271a0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
271b0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 void*, int, voi
271c0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f d(*)(void*));.vo
271d0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
271e0 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 t_text16le(sqlit
271f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
27200 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f st void*, int,vo
27210 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 id(*)(void*));.v
27220 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
27230 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 lt_text16be(sqli
27240 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
27250 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 nst void*, int,v
27260 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
27270 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
27280 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 ult_value(sqlite
27290 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 3_context*, sqli
272a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 te3_value*);.voi
272b0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
272c0 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 _zeroblob(sqlite
272d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 3_context*, int
272e0 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 n);../*.** CAPI3
272f0 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 REF: Define New
27300 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e Collating Sequen
27310 63 65 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 32 ces {H16600} <S2
27320 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 0300>.**.** Thes
27330 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 e functions are
27340 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 used to add new
27350 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
27360 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 ces to the.** [d
27370 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
27380 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 on] specified as
27390 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
273a0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e ent..**.** The n
273b0 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 ame of the new c
273c0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
273d0 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 e is specified a
273e0 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 s a UTF-8 string
273f0 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f .** for sqlite3_
27400 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
27410 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 () and sqlite3_c
27420 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
27430 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 v2().** and a UT
27440 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 F-16 string for
27450 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
27460 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e ollation16(). In
27470 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 all cases.** th
27480 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 e name is passed
27490 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 as the second f
274a0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 unction argument
274b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 ..**.** The thir
274c0 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 d argument may b
274d0 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e e one of the con
274e0 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 stants [SQLITE_U
274f0 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 TF8],.** [SQLITE
27500 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 _UTF16LE] or [SQ
27510 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 LITE_UTF16BE], i
27520 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 ndicating that t
27530 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 he user-supplied
27540 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 .** routine expe
27550 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 cts to be passed
27560 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
27570 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 ings encoded usi
27580 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 ng UTF-8,.** UTF
27590 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 -16 little-endia
275a0 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 n, or UTF-16 big
275b0 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 -endian, respect
275c0 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 ively. The.** th
275d0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 ird argument mig
275e0 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 ht also be [SQLI
275f0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 TE_UTF16_ALIGNED
27600 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 ] to indicate th
27610 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e at.** the routin
27620 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 e expects pointe
27630 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 rs to 16-bit wor
27640 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 d aligned string
27650 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 s.** of UTF-16 i
27660 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 n the native byt
27670 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 e order of the h
27680 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a ost computer..**
27690 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f .** A pointer to
276a0 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 the user suppli
276b0 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 ed routine must
276c0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
276d0 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 fifth.** argume
276e0 6e 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55 nt. If it is NU
276f0 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 LL, this is the
27700 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 same as deleting
27710 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a the collation.*
27720 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 * sequence (so t
27730 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f hat SQLite canno
27740 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 t call it anymor
27750 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 e)..** Each time
27760 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
27770 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 supplied functi
27780 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 on is invoked, i
27790 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 t is passed.** a
277a0 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72 61 s its first para
277b0 6d 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66 20 meter a copy of
277c0 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 the void* passed
277d0 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 as the fourth a
277e0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 rgument.** to sq
277f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
27800 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 lation() or sqli
27810 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
27820 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 tion16()..**.**
27830 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 The remaining ar
27840 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 guments to the a
27850 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c pplication-suppl
27860 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 ied routine are
27870 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 two strings,.**
27880 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 each represented
27890 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 by a (length, d
278a0 61 74 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e ata) pair and en
278b0 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 coded in the enc
278c0 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 oding.** that wa
278d0 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 s passed as the
278e0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 third argument w
278f0 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f hen the collatio
27900 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a n sequence was.*
27910 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 * registered. {E
27920 4e 44 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 ND} The applica
27930 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c tion defined col
27940 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 lation routine s
27950 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 hould.** return
27960 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f negative, zero o
27970 72 20 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 r positive if th
27980 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 e first string i
27990 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 s less than,.**
279a0 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 equal to, or gre
279b0 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 ater than the se
279c0 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 cond string. i.e
279d0 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 . (STRING1 - STR
279e0 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ING2)..**.** The
279f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
27a00 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 collation_v2() w
27a10 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 orks like sqlite
27a20 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
27a30 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 on().** except t
27a40 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 hat it takes an
27a50 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 extra argument w
27a60 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75 hich is a destru
27a70 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 ctor for.** the
27a80 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 collation. The
27a90 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 destructor is ca
27aa0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f lled when the co
27ab0 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 llation is.** de
27ac0 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 stroyed and is p
27ad0 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 assed a copy of
27ae0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
27af0 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 eter void* point
27b00 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c er.** of the sql
27b10 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
27b20 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 ation_v2()..** C
27b30 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 ollations are de
27b40 73 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 stroyed when the
27b50 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e y are overridden
27b60 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 by later calls
27b70 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 to the.** collat
27b80 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e ion creation fun
27b90 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 ctions or when t
27ba0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
27bb0 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 nection] is clos
27bc0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c ed.** using [sql
27bd0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a ite3_close()]..*
27be0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
27bf0 73 3a 0a 2a 2a 20 5b 48 31 36 36 30 33 5d 20 5b s:.** [H16603] [
27c00 48 31 36 36 30 34 5d 20 5b 48 31 36 36 30 36 5d H16604] [H16606]
27c10 20 5b 48 31 36 36 30 39 5d 20 5b 48 31 36 36 31 [H16609] [H1661
27c20 32 5d 20 5b 48 31 36 36 31 35 5d 20 5b 48 31 36 2] [H16615] [H16
27c30 36 31 38 5d 20 5b 48 31 36 36 32 31 5d 0a 2a 2a 618] [H16621].**
27c40 20 5b 48 31 36 36 32 34 5d 20 5b 48 31 36 36 32 [H16624] [H1662
27c50 37 5d 20 5b 48 31 36 36 33 30 5d 0a 2a 2f 0a 69 7] [H16630].*/.i
27c60 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
27c70 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 e_collation(. s
27c80 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 qlite3*, . cons
27c90 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a t char *zName, .
27ca0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 int eTextRep,
27cb0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 . void*,. int(
27cc0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a *xCompare)(void*
27cd0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
27ce0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
27cf0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ).);.int sqlite3
27d00 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
27d10 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a n_v2(. sqlite3*
27d20 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 , . const char
27d30 2a 7a 4e 61 6d 65 2c 20 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 2c 0a 20 20 76 6f nst void*),. vo
27d90 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f id(*xDestroy)(vo
27da0 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 id*).);.int sqli
27db0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
27dc0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 tion16(. sqlite
27dd0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 3*, . const voi
27de0 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 d *zName,. int
27df0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 eTextRep, . voi
27e00 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 d*,. int(*xComp
27e10 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 are)(void*,int,c
27e20 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 onst void*,int,c
27e30 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a onst void*).);..
27e40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
27e50 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 Collation Needed
27e60 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37 Callbacks {H167
27e70 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 00} <S20300>.**.
27e80 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 ** To avoid havi
27e90 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 ng to register a
27ea0 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 ll collation seq
27eb0 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 uences before a
27ec0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 database.** can
27ed0 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c be used, a singl
27ee0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
27ef0 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 ion may be regis
27f00 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a tered with the.*
27f10 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
27f20 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61 ection] to be ca
27f30 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e lled whenever an
27f40 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 undefined colla
27f50 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 tion.** sequence
27f60 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a is required..**
27f70 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 .** If the funct
27f80 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 ion is registere
27f90 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 d using the sqli
27fa0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
27fb0 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 eded() API,.** t
27fc0 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 hen it is passed
27fd0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e the names of un
27fe0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f defined collatio
27ff0 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 n sequences as s
28000 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 trings.** encode
28010 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36 d in UTF-8. {H16
28020 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 703} If sqlite3_
28030 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
28040 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 16() is used,.**
28050 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 the names are p
28060 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 assed as UTF-16
28070 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 in machine nativ
28080 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a e byte order..**
28090 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 A call to eithe
280a0 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 r function repla
280b0 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 ces any existing
280c0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a callback..**.**
280d0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 When the callba
280e0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 ck is invoked, t
280f0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
28100 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f t passed is a co
28110 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 py.** of the sec
28120 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
28130 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
28140 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a n_needed() or.**
28150 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
28160 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 on_needed16().
28170 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
28180 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 ent is the datab
28190 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
281a0 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 n. The third ar
281b0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 gument is one of
281c0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 [SQLITE_UTF8],
281d0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d [SQLITE_UTF16BE]
281e0 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f ,.** or [SQLITE_
281f0 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 UTF16LE], indica
28200 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 ting the most de
28210 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 sirable form of
28220 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a the collation.**
28230 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 sequence functi
28240 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 on required. Th
28250 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
28260 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f er is the name o
28270 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 f the.** require
28280 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 d collation sequ
28290 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ence..**.** The
282a0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
282b0 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 n should registe
282c0 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f r the desired co
282d0 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a llation using.**
282e0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
282f0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b _collation()], [
28300 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
28310 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f ollation16()], o
28320 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 r.** [sqlite3_cr
28330 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
28340 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 2()]..**.** Requ
28350 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
28360 36 37 30 32 5d 20 5b 48 31 36 37 30 34 5d 20 5b 6702] [H16704] [
28370 48 31 36 37 30 36 5d 0a 2a 2f 0a 69 6e 74 20 73 H16706].*/.int s
28380 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
28390 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 _needed(. sqlit
283a0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a e3*, . void*, .
283b0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c void(*)(void*,
283c0 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 sqlite3*,int eTe
283d0 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 xtRep,const char
283e0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *).);.int sqlite
283f0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
28400 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a ed16(. sqlite3*
28410 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f , . void*,. vo
28420 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 id(*)(void*,sqli
28430 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 te3*,int eTextRe
28440 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 p,const void*).)
28450 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 ;../*.** Specify
28460 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 the key for an
28470 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 encrypted databa
28480 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e se. This routin
28490 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 e should be.** c
284a0 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 alled right afte
284b0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 r sqlite3_open()
284c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 ..**.** The code
284d0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 to implement th
284e0 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 is API is not av
284f0 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 ailable in the p
28500 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a ublic release.**
28510 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 of SQLite..*/.i
28520 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a nt sqlite3_key(.
28530 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
28540 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
28550 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 /* Database to
28560 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 be rekeyed */.
28570 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 const void *pKey
28580 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f , int nKey /
28590 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a * The key */.);.
285a0 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 ./*.** Change th
285b0 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e e key on an open
285c0 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 database. If t
285d0 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 he current datab
285e0 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e ase is not.** en
285f0 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f crypted, this ro
28600 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 utine will encry
28610 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d pt it. If pNew=
28620 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 =0 or nNew==0, t
28630 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 he.** database i
28640 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a s decrypted..**.
28650 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 ** The code to i
28660 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 mplement this AP
28670 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 I is not availab
28680 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 le in the public
28690 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 release.** of S
286a0 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 QLite..*/.int sq
286b0 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 lite3_rekey(. s
286c0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
286d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
286e0 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 Database to be
286f0 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e rekeyed */. con
28700 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 st void *pKey, i
28710 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 nt nKey /* T
28720 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b he new key */.);
28730 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
28740 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 : Suspend Execut
28750 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 ion For A Short
28760 54 69 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c 53 Time {H10530} <S
28770 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 40410>.**.** The
28780 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 sqlite3_sleep()
28790 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 function causes
287a0 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 the current thr
287b0 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 ead to suspend e
287c0 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 xecution.** for
287d0 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 at least a numbe
287e0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 r of millisecond
287f0 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 s specified in i
28800 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a ts parameter..**
28810 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 .** If the opera
28820 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 ting system does
28830 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 not support sle
28840 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 ep requests with
28850 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 .** millisecond
28860 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c time resolution,
28870 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 then the time w
28880 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 ill be rounded u
28890 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 p to.** the near
288a0 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 est second. The
288b0 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 number of millis
288c0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 econds of sleep
288d0 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 actually.** requ
288e0 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f ested from the o
288f0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 perating system
28900 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
28910 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d ** SQLite implem
28920 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 ents this interf
28930 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 ace by calling t
28940 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d he xSleep().** m
28950 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 ethod of the def
28960 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
28970 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a s] object..**.**
28980 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b Requirements: [
28990 48 31 30 35 33 33 5d 20 5b 48 31 30 35 33 36 5d H10533] [H10536]
289a0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
289b0 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a sleep(int);../*.
289c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d ** CAPI3REF: Nam
289d0 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 e Of The Folder
289e0 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 Holding Temporar
289f0 79 20 46 69 6c 65 73 20 7b 48 31 30 33 31 30 7d y Files {H10310}
28a00 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20000>.**.**
28a10 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 If this global v
28a20 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 ariable is made
28a30 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 to point to a st
28a40 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a ring which is.**
28a50 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 the name of a f
28a60 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 older (a.k.a. di
28a70 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 rectory), then a
28a80 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c ll temporary fil
28a90 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 es.** created by
28aa0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 SQLite will be
28ab0 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 placed in that d
28ac0 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68 irectory. If th
28ad0 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 is variable.** i
28ae0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
28af0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 , then SQLite pe
28b00 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 rforms a search
28b10 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 for an appropria
28b20 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 te.** temporary
28b30 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a file directory..
28b40 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 **.** It is not
28b50 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 safe to read or
28b60 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 modify this vari
28b70 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 able in more tha
28b80 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 n one.** thread
28b90 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 at a time. It i
28ba0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 s not safe to re
28bb0 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 ad or modify thi
28bc0 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 s variable.** if
28bd0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
28be0 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e nection] is bein
28bf0 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 g used at the sa
28c00 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 me time in a sep
28c10 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e arate.** thread.
28c20 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 .** It is intend
28c30 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 ed that this var
28c40 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 iable be set onc
28c50 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 e.** as part of
28c60 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 process initiali
28c70 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 zation and befor
28c80 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 e any SQLite int
28c90 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e erface.** routin
28ca0 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c es have been cal
28cb0 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 led and that thi
28cc0 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 s variable remai
28cd0 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 n unchanged.** t
28ce0 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a hereafter..**.**
28cf0 20 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 The [temp_store
28d00 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d _directory pragm
28d10 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 a] may modify th
28d20 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 is variable and
28d30 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 cause.** it to p
28d40 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f oint to memory o
28d50 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
28d60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 lite3_malloc].
28d70 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 Furthermore,.**
28d80 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f the [temp_store_
28d90 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 directory pragma
28da0 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 ] always assumes
28db0 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 that any string
28dc0 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 .** that this va
28dd0 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f riable points to
28de0 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f is held in memo
28df0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ry obtained from
28e00 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 .** [sqlite3_ma
28e10 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 lloc] and the pr
28e20 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 agma may attempt
28e30 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 to free that me
28e40 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 mory.** using [s
28e50 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a qlite3_free]..**
28e60 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 Hence, if this
28e70 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 variable is modi
28e80 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 fied directly, e
28e90 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 ither it should
28ea0 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 be.** made NULL
28eb0 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 or made to point
28ec0 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 to memory obtai
28ed0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
28ee0 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 3_malloc].** or
28ef0 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 else the use of
28f00 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f the [temp_store_
28f10 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 directory pragma
28f20 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 ] should be avoi
28f30 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 ded..*/.SQLITE_E
28f40 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 XTERN char *sqli
28f50 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f te3_temp_directo
28f60 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ry;../*.** CAPI3
28f70 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 REF: Test For Au
28f80 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b to-Commit Mode {
28f90 48 31 32 39 33 30 7d 20 3c 53 36 30 32 30 30 3e H12930} <S60200>
28fa0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 .** KEYWORDS: {a
28fb0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a utocommit mode}.
28fc0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
28fd0 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 3_get_autocommit
28fe0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
28ff0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 urns non-zero or
29000 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 .** zero if the
29010 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 given database c
29020 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 onnection is or
29030 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f is not in autoco
29040 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 mmit mode,.** re
29050 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 75 74 spectively. Aut
29060 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 ocommit mode is
29070 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a on by default..*
29080 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 * Autocommit mod
29090 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 e is disabled by
290a0 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 a [BEGIN] state
290b0 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d ment..** Autocom
290c0 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 mit mode is re-e
290d0 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d nabled by a [COM
290e0 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 MIT] or [ROLLBAC
290f0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 K]..**.** If cer
29100 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 tain kinds of er
29110 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 rors occur on a
29120 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e statement within
29130 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 a multi-stateme
29140 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f nt.** transactio
29150 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 n (errors includ
29160 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c ing [SQLITE_FULL
29170 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 ], [SQLITE_IOERR
29180 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f ],.** [SQLITE_NO
29190 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 MEM], [SQLITE_BU
291a0 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 SY], and [SQLITE
291b0 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 _INTERRUPT]) the
291c0 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 n the.** transac
291d0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f tion might be ro
291e0 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 lled back automa
291f0 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e tically. The on
29200 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e ly way to.** fin
29210 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 d out whether SQ
29220 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c Lite automatical
29230 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 ly rolled back t
29240 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 he transaction a
29250 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 fter.** an error
29260 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 is to use this
29270 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
29280 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 If another threa
29290 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 d changes the au
292a0 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 tocommit status
292b0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a of the database.
292c0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 ** connection wh
292d0 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ile this routine
292e0 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 is running, the
292f0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c n the return val
29300 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e ue.** is undefin
29310 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ed..**.** Requir
29320 65 6d 65 6e 74 73 3a 20 5b 48 31 32 39 33 31 5d ements: [H12931]
29330 20 5b 48 31 32 39 33 32 5d 20 5b 48 31 32 39 33 [H12932] [H1293
29340 33 5d 20 5b 48 31 32 39 33 34 5d 0a 2a 2f 0a 69 3] [H12934].*/.i
29350 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 nt sqlite3_get_a
29360 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 utocommit(sqlite
29370 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
29380 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 3REF: Find The D
29390 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f atabase Handle O
293a0 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 f A Prepared Sta
293b0 74 65 6d 65 6e 74 20 7b 48 31 33 31 32 30 7d 20 tement {H13120}
293c0 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S60600>.**.** T
293d0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 he sqlite3_db_ha
293e0 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 ndle interface r
293f0 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 eturns the [data
29400 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
29410 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 handle.** to wh
29420 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 ich a [prepared
29430 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e statement] belon
29440 67 73 2e 20 20 54 68 65 20 5b 64 61 74 61 62 61 gs. The [databa
29450 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a se connection].*
29460 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 * returned by sq
29470 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 lite3_db_handle
29480 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 is the same [dat
29490 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
294a0 5d 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66 ] that was the f
294b0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a irst argument.**
294c0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
294d0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 _prepare_v2()] c
294e0 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 all (or its vari
294f0 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75 ants) that was u
29500 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 sed to.** create
29510 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
29520 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 n the first plac
29530 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 e..**.** Require
29540 6d 65 6e 74 73 3a 20 5b 48 31 33 31 32 33 5d 0a ments: [H13123].
29550 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 */.sqlite3 *sqli
29560 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 te3_db_handle(sq
29570 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f lite3_stmt*);../
29580 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
29590 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 ind the next pre
295a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
295b0 7b 48 31 33 31 34 30 7d 20 3c 53 36 30 36 30 30 {H13140} <S60600
295c0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 >.**.** This int
295d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
295e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
295f0 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 next [prepared s
29600 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a tatement] after.
29610 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 ** pStmt associa
29620 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 ted with the [da
29630 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
29640 6e 5d 20 70 44 62 2e 20 20 49 66 20 70 53 74 6d n] pDb. If pStm
29650 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 t is NULL.** the
29660 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 n this interface
29670 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
29680 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 er to the first
29690 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
296a0 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 nt.** associated
296b0 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 with the databa
296c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 se connection pD
296d0 62 2e 20 20 49 66 20 6e 6f 20 70 72 65 70 61 72 b. If no prepar
296e0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 ed statement.**
296f0 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f satisfies the co
29700 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 nditions of this
29710 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 routine, it ret
29720 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a urns NULL..**.**
29730 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 The [database c
29740 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 onnection] point
29750 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 er D in a call t
29760 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 o.** [sqlite3_ne
29770 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 xt_stmt(D,S)] mu
29780 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f st refer to an o
29790 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 pen database.**
297a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 connection and i
297b0 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 n particular mus
297c0 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 t not be a NULL
297d0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 52 pointer..**.** R
297e0 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 equirements: [H1
297f0 33 31 34 33 5d 20 5b 48 31 33 31 34 36 5d 20 5b 3143] [H13146] [
29800 48 31 33 31 34 39 5d 20 5b 48 31 33 31 35 32 5d H13149] [H13152]
29810 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 .*/.sqlite3_stmt
29820 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 *sqlite3_next_s
29830 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 tmt(sqlite3 *pDb
29840 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a , sqlite3_stmt *
29850 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
29860 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 API3REF: Commit
29870 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 And Rollback Not
29880 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 ification Callba
29890 63 6b 73 20 7b 48 31 32 39 35 30 7d 20 3c 53 36 cks {H12950} <S6
298a0 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0400>.**.** The
298b0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 sqlite3_commit_h
298c0 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 ook() interface
298d0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c registers a call
298e0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e back.** function
298f0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 to be invoked w
29900 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 henever a transa
29910 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 ction is committ
29920 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 ed..** Any callb
29930 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 ack set by a pre
29940 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 vious call to sq
29950 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f lite3_commit_hoo
29960 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 k().** for the s
29970 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
29980 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 nection is overr
29990 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 idden..** The sq
299a0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 lite3_rollback_h
299b0 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 ook() interface
299c0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c registers a call
299d0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e back.** function
299e0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 to be invoked w
299f0 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 henever a transa
29a00 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 ction is committ
29a10 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 ed..** Any callb
29a20 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 ack set by a pre
29a30 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 vious call to sq
29a40 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f lite3_commit_hoo
29a50 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 k().** for the s
29a60 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
29a70 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 nection is overr
29a80 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 idden..** The pA
29a90 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 rg argument is p
29aa0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f assed through to
29ab0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a the callback..*
29ac0 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 * If the callbac
29ad0 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f k on a commit ho
29ae0 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 ok function retu
29af0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a rns non-zero,.**
29b00 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 then the commit
29b10 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e is converted in
29b20 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a to a rollback..*
29b30 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 *.** If another
29b40 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 function was pre
29b50 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 viously register
29b60 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20 ed, its.** pArg
29b70 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 value is returne
29b80 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 d. Otherwise NU
29b90 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a LL is returned..
29ba0 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 **.** The callba
29bb0 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ck implementatio
29bc0 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e n must not do an
29bd0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c ything that will
29be0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
29bf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
29c00 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
29c10 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 the callback. A
29c20 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f ny actions.** to
29c30 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 modify the data
29c40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
29c50 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 must be deferred
29c60 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 until after the
29c70 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f .** completion o
29c80 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 f the [sqlite3_s
29c90 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 tep()] call that
29ca0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63 triggered the c
29cb0 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c ommit.** or roll
29cc0 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 back hook in the
29cd0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a first place..**
29ce0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 Note that [sqli
29cf0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
29d00 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 ] and [sqlite3_s
29d10 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 tep()] both modi
29d20 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 fy their.** data
29d30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
29d40 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 for the meaning
29d50 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 of "modify" in
29d60 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a this paragraph..
29d70 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e **.** Registerin
29d80 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f g a NULL functio
29d90 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 n disables the c
29da0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 allback..**.** F
29db0 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 or the purposes
29dc0 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 of this API, a t
29dd0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 ransaction is sa
29de0 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a id to have been.
29df0 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 ** rolled back i
29e00 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 f an explicit "R
29e10 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 OLLBACK" stateme
29e20 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 nt is executed,
29e30 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f or.** an error o
29e40 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 r constraint cau
29e50 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 ses an implicit
29e60 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 rollback to occu
29e70 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 r..** The rollba
29e80 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e ck callback is n
29e90 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 ot invoked if a
29ea0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a transaction is.*
29eb0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 * automatically
29ec0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 rolled back beca
29ed0 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 use the database
29ee0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 connection is c
29ef0 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f losed..** The ro
29f00 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 llback callback
29f10 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 is not invoked i
29f20 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 f a transaction
29f30 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 is.** rolled bac
29f40 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d k because a comm
29f50 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 it callback retu
29f60 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a rned non-zero..*
29f70 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f * <todo> Check o
29f80 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a n this </todo>.*
29f90 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
29fa0 73 3a 0a 2a 2a 20 5b 48 31 32 39 35 31 5d 20 5b s:.** [H12951] [
29fb0 48 31 32 39 35 32 5d 20 5b 48 31 32 39 35 33 5d H12952] [H12953]
29fc0 20 5b 48 31 32 39 35 34 5d 20 5b 48 31 32 39 35 [H12954] [H1295
29fd0 35 5d 0a 2a 2a 20 5b 48 31 32 39 36 31 5d 20 5b 5].** [H12961] [
29fe0 48 31 32 39 36 32 5d 20 5b 48 31 32 39 36 33 5d H12962] [H12963]
29ff0 20 5b 48 31 32 39 36 34 5d 0a 2a 2f 0a 76 6f 69 [H12964].*/.voi
2a000 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 d *sqlite3_commi
2a010 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c t_hook(sqlite3*,
2a020 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 int(*)(void*),
2a030 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 void*);.void *sq
2a040 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 lite3_rollback_h
2a050 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f ook(sqlite3*, vo
2a060 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 id(*)(void *), v
2a070 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
2a080 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 PI3REF: Data Cha
2a090 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e nge Notification
2a0a0 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 Callbacks {H129
2a0b0 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 70} <S60400>.**.
2a0c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 ** The sqlite3_u
2a0d0 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 pdate_hook() int
2a0e0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 erface registers
2a0f0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 a callback func
2a100 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 tion.** with the
2a110 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2a120 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 ction] identifie
2a130 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 d by the first a
2a140 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 rgument.** to be
2a150 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 invoked wheneve
2a160 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 r a row is updat
2a170 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 ed, inserted or
2a180 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 deleted..** Any
2a190 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 callback set by
2a1a0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 a previous call
2a1b0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e to this function
2a1c0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 .** for the same
2a1d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
2a1e0 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 tion is overridd
2a1f0 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 en..**.** The se
2a200 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
2a210 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
2a220 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e e function to in
2a230 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 voke when a.** r
2a240 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 ow is updated, i
2a250 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 nserted or delet
2a260 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 ed..** The first
2a270 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
2a280 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 callback is a c
2a290 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 opy of the third
2a2a0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
2a2b0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 sqlite3_update_h
2a2c0 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 ook()..** The se
2a2d0 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 cond callback ar
2a2e0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 gument is one of
2a2f0 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d [SQLITE_INSERT]
2a300 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 , [SQLITE_DELETE
2a310 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 ],.** or [SQLITE
2a320 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 _UPDATE], depend
2a330 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 ing on the opera
2a340 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 tion that caused
2a350 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a the callback.**
2a360 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a to be invoked..
2a370 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 ** The third and
2a380 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
2a390 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 s to the callbac
2a3a0 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 k contain pointe
2a3b0 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 rs to the.** dat
2a3c0 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 abase and table
2a3d0 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 name containing
2a3e0 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 the affected row
2a3f0 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 ..** The final c
2a400 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 allback paramete
2a410 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d r is the [rowid]
2a420 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 of the row..**
2a430 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 In the case of a
2a440 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 n update, this i
2a450 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 s the [rowid] af
2a460 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74 ter the update t
2a470 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a akes place..**.*
2a480 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f * The update hoo
2a490 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 k is not invoked
2a4a0 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 when internal s
2a4b0 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 ystem tables are
2a4c0 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e .** modified (i.
2a4d0 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 e. sqlite_master
2a4e0 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 and sqlite_sequ
2a4f0 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ence)..**.** The
2a500 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 update hook imp
2a510 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 lementation must
2a520 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 not do anything
2a530 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 that will modif
2a540 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 y.** the databas
2a550 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 e connection tha
2a560 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 t invoked the up
2a570 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 date hook. Any
2a580 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f actions.** to mo
2a590 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 dify the databas
2a5a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 e connection mus
2a5b0 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e t be deferred un
2a5c0 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a til after the.**
2a5d0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 completion of t
2a5e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 he [sqlite3_step
2a5f0 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 ()] call that tr
2a600 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61 iggered the upda
2a610 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 te hook..** Note
2a620 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 that [sqlite3_p
2a630 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
2a640 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2a650 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 ] both modify th
2a660 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 eir.** database
2a670 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 connections for
2a680 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 the meaning of "
2a690 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 modify" in this
2a6a0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a paragraph..**.**
2a6b0 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 If another func
2a6c0 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 tion was previou
2a6d0 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 sly registered,
2a6e0 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a its pArg value.*
2a6f0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 * is returned.
2a700 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 Otherwise NULL i
2a710 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
2a720 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
2a730 2a 2a 20 5b 48 31 32 39 37 31 5d 20 5b 48 31 32 ** [H12971] [H12
2a740 39 37 33 5d 20 5b 48 31 32 39 37 35 5d 20 5b 48 973] [H12975] [H
2a750 31 32 39 37 37 5d 20 5b 48 31 32 39 37 39 5d 20 12977] [H12979]
2a760 5b 48 31 32 39 38 31 5d 20 5b 48 31 32 39 38 33 [H12981] [H12983
2a770 5d 20 5b 48 31 32 39 38 36 5d 0a 2a 2f 0a 76 6f ] [H12986].*/.vo
2a780 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 id *sqlite3_upda
2a790 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 te_hook(. sqlit
2a7a0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 e3*, . void(*)(
2a7b0 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 void *,int ,char
2a7c0 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f const *,char co
2a7d0 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e nst *,sqlite3_in
2a7e0 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b t64),. void*.);
2a7f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2a800 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 : Enable Or Disa
2a810 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72 ble Shared Pager
2a820 20 43 61 63 68 65 20 7b 48 31 30 33 33 30 7d 20 Cache {H10330}
2a830 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b 45 59 57 <S30900>.** KEYW
2a840 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61 ORDS: {shared ca
2a850 63 68 65 7d 20 7b 73 68 61 72 65 64 20 63 61 63 che} {shared cac
2a860 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 he mode}.**.** T
2a870 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 his routine enab
2a880 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 les or disables
2a890 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 the sharing of t
2a8a0 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68 he database cach
2a8b0 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 e.** and schema
2a8c0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 data structures
2a8d0 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73 between [databas
2a8e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 e connection | c
2a8f0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 onnections].** t
2a900 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 o the same datab
2a910 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20 ase. Sharing is
2a920 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 enabled if the a
2a930 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a rgument is true.
2a940 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 ** and disabled
2a950 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 if the argument
2a960 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 is false..**.**
2a970 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 Cache sharing is
2a980 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 enabled and dis
2a990 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 abled for an ent
2a9a0 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 ire process..**
2a9b0 54 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 This is a change
2a9c0 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 as of SQLite ve
2a9d0 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 rsion 3.5.0. In
2a9e0 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f prior versions o
2a9f0 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 f SQLite,.** sha
2aa00 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64 ring was enabled
2aa10 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 or disabled for
2aa20 20 65 61 63 68 20 74 68 72 65 61 64 20 73 65 70 each thread sep
2aa30 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 arately..**.** T
2aa40 68 65 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 he cache sharing
2aa50 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 mode set by thi
2aa60 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 s interface effe
2aa70 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 cts all subseque
2aa80 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b nt.** calls to [
2aa90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
2aaa0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
2aab0 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 2()], and [sqlit
2aac0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a e3_open16()]..**
2aad0 20 45 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 Existing databa
2aae0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 se connections c
2aaf0 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 ontinue use the
2ab00 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 sharing mode.**
2ab10 74 68 61 74 20 77 61 73 20 69 6e 20 65 66 66 65 that was in effe
2ab20 63 74 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 ct at the time t
2ab30 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e hey were opened.
2ab40 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 .**.** Virtual t
2ab50 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 ables cannot be
2ab60 75 73 65 64 20 77 69 74 68 20 61 20 73 68 61 72 used with a shar
2ab70 65 64 20 63 61 63 68 65 2e 20 20 57 68 65 6e 20 ed cache. When
2ab80 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 shared.** cache
2ab90 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 is enabled, the
2aba0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2abb0 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49 20 75 73 module()] API us
2abc0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a ed to register.*
2abd0 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 * virtual tables
2abe0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 will always ret
2abf0 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a urn an error..**
2ac00 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
2ac10 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
2ac20 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 _OK] if shared c
2ac30 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 ache was enabled
2ac40 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 or disabled.**
2ac50 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 successfully. A
2ac60 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
2ac70 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 s returned other
2ac80 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 wise..**.** Shar
2ac90 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 ed cache is disa
2aca0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e bled by default.
2acb0 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 But this might
2acc0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 change in.** fut
2acd0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
2ace0 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 SQLite. Applica
2acf0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 tions that care
2ad00 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 about shared.**
2ad10 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 cache setting sh
2ad20 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c ould set it expl
2ad30 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 icitly..**.** Se
2ad40 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 e Also: [SQLite
2ad50 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f Shared-Cache Mo
2ad60 64 65 5d 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 de].**.** Requir
2ad70 65 6d 65 6e 74 73 3a 20 5b 48 31 30 33 33 31 5d ements: [H10331]
2ad80 20 5b 48 31 30 33 33 36 5d 20 5b 48 31 30 33 33 [H10336] [H1033
2ad90 37 5d 20 5b 48 31 30 33 33 39 5d 0a 2a 2f 0a 69 7] [H10339].*/.i
2ada0 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c nt sqlite3_enabl
2adb0 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 e_shared_cache(i
2adc0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
2add0 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 3REF: Attempt To
2ade0 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 Free Heap Memor
2adf0 79 20 7b 48 31 37 33 34 30 7d 20 3c 53 33 30 32 y {H17340} <S302
2ae00 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 20>.**.** The sq
2ae10 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 lite3_release_me
2ae20 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 mory() interface
2ae30 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 attempts to fre
2ae40 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 e N bytes.** of
2ae50 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 heap memory by d
2ae60 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d eallocating non-
2ae70 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 essential memory
2ae80 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 allocations.**
2ae90 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 held by the data
2aea0 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 7b 45 base library. {E
2aeb0 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 ND} Memory used
2aec0 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 to cache databa
2aed0 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 se.** pages to i
2aee0 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e mprove performan
2aef0 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 ce is an example
2af00 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 of non-essentia
2af10 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 73 71 6c l memory..** sql
2af20 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d ite3_release_mem
2af30 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 ory() returns th
2af40 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
2af50 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 s actually freed
2af60 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 ,.** which might
2af70 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 be more or less
2af80 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 than the amount
2af90 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a requested..**.*
2afa0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 * Requirements:
2afb0 5b 48 31 37 33 34 31 5d 20 5b 48 31 37 33 34 32 [H17341] [H17342
2afc0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ].*/.int sqlite3
2afd0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 _release_memory(
2afe0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
2aff0 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 I3REF: Impose A
2b000 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 Limit On Heap Si
2b010 7a 65 20 7b 48 31 37 33 35 30 7d 20 3c 53 33 30 ze {H17350} <S30
2b020 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 220>.**.** The s
2b030 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 qlite3_soft_heap
2b040 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61 _limit() interfa
2b050 63 65 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 ce places a "sof
2b060 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 t" limit.** on t
2b070 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 he amount of hea
2b080 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 p memory that ma
2b090 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 y be allocated b
2b0a0 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 49 66 20 y SQLite..** If
2b0b0 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f an internal allo
2b0c0 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 cation is reques
2b0d0 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65 ted that would e
2b0e0 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 xceed the.** sof
2b0f0 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 t heap limit, [s
2b100 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d qlite3_release_m
2b110 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f emory()] is invo
2b120 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f ked one or.** mo
2b130 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65 re times to free
2b140 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62 up some space b
2b150 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 efore the alloca
2b160 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 tion is performe
2b170 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d d..**.** The lim
2b180 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f it is called "so
2b190 66 74 22 2c 20 62 65 63 61 75 73 65 20 69 66 20 ft", because if
2b1a0 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 [sqlite3_release
2b1b0 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 _memory()].** ca
2b1c0 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69 63 nnot free suffic
2b1d0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 ient memory to p
2b1e0 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 revent the limit
2b1f0 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 from being exce
2b200 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d eded,.** the mem
2b210 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 ory is allocated
2b220 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 anyway and the
2b230 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f current operatio
2b240 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a n proceeds..**.*
2b250 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 * A negative or
2b260 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e zero value for N
2b270 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 means that ther
2b280 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 e is no soft hea
2b290 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b p limit and.** [
2b2a0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f sqlite3_release_
2b2b0 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f memory()] will o
2b2c0 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 nly be called wh
2b2d0 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 en memory is exh
2b2e0 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64 austed..** The d
2b2f0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 efault value for
2b300 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c the soft heap l
2b310 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a imit is zero..**
2b320 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 .** SQLite makes
2b330 20 61 20 62 65 73 74 20 65 66 66 6f 72 74 20 74 a best effort t
2b340 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 o honor the soft
2b350 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 heap limit..**
2b360 42 75 74 20 69 66 20 74 68 65 20 73 6f 66 74 20 But if the soft
2b370 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f heap limit canno
2b380 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78 t be honored, ex
2b390 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 ecution will.**
2b3a0 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74 continue without
2b3b0 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 error or notifi
2b3c0 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 73 cation. This is
2b3d0 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20 69 why the limit i
2b3e0 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 s.** called a "s
2b3f0 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 oft" limit. It
2b400 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 is advisory only
2b410 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f ..**.** Prior to
2b420 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
2b430 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 3.5.0, this rout
2b440 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 ine only constra
2b450 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a ined the memory.
2b460 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 ** allocated by
2b470 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20 a single thread
2b480 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 - the same threa
2b490 64 20 69 6e 20 77 68 69 63 68 20 74 68 69 73 20 d in which this
2b4a0 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e routine.** runs.
2b4b0 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 Beginning with
2b4c0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
2b4d0 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 3.5.0, the soft
2b4e0 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a heap limit is.**
2b4f0 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 applied to all
2b500 74 68 72 65 61 64 73 2e 20 54 68 65 20 76 61 6c threads. The val
2b510 75 65 20 73 70 65 63 69 66 69 65 64 20 66 6f 72 ue specified for
2b520 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c the soft heap l
2b530 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70 imit.** is an up
2b540 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 per bound on the
2b550 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c total memory al
2b560 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c location for all
2b570 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 threads. In.**
2b580 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68 version 3.5.0 th
2b590 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e ere is no mechan
2b5a0 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67 ism for limiting
2b5b0 20 74 68 65 20 68 65 61 70 20 75 73 61 67 65 20 the heap usage
2b5c0 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 for.** individua
2b5d0 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a l threads..**.**
2b5e0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
2b5f0 2a 20 5b 48 31 36 33 35 31 5d 20 5b 48 31 36 33 * [H16351] [H163
2b600 35 32 5d 20 5b 48 31 36 33 35 33 5d 20 5b 48 31 52] [H16353] [H1
2b610 36 33 35 34 5d 20 5b 48 31 36 33 35 35 5d 20 5b 6354] [H16355] [
2b620 48 31 36 33 35 38 5d 0a 2a 2f 0a 76 6f 69 64 20 H16358].*/.void
2b630 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 sqlite3_soft_hea
2b640 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f p_limit(int);../
2b650 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 *.** CAPI3REF: E
2b660 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 xtract Metadata
2b670 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f About A Column O
2b680 66 20 41 20 54 61 62 6c 65 20 7b 48 31 32 38 35 f A Table {H1285
2b690 30 7d 20 3c 53 36 30 33 30 30 3e 0a 2a 2a 0a 2a 0} <S60300>.**.*
2b6a0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 * This routine r
2b6b0 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20 eturns metadata
2b6c0 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 about a specific
2b6d0 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 column of a spe
2b6e0 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 cific.** databas
2b6f0 65 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 e table accessib
2b700 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61 le using the [da
2b710 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2b720 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 n] handle.** pas
2b730 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 sed as the first
2b740 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 function argume
2b750 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f nt..**.** The co
2b760 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 lumn is identifi
2b770 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 ed by the second
2b780 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 , third and four
2b790 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f th parameters to
2b7a0 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f .** this functio
2b7b0 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 n. The second pa
2b7c0 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65 rameter is eithe
2b7d0 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 r the name of th
2b7e0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 e database.** (i
2b7f0 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d .e. "main", "tem
2b800 70 22 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65 p" or an attache
2b810 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74 d database) cont
2b820 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69 aining the speci
2b830 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 fied.** table or
2b840 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69 73 20 NULL. If it is
2b850 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 NULL, then all a
2b860 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
2b870 73 20 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a s are searched.*
2b880 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 * for the table
2b890 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 using the same a
2b8a0 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20 62 79 lgorithm used by
2b8b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e the database en
2b8c0 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c gine to.** resol
2b8d0 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 ve unqualified t
2b8e0 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e able references.
2b8f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 .**.** The third
2b900 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 and fourth para
2b910 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 meters to this f
2b920 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 unction are the
2b930 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e table and column
2b940 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 .** name of the
2b950 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 desired column,
2b960 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 respectively. Ne
2b970 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 ither of these p
2b980 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 arameters.** may
2b990 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 be NULL..**.**
2b9a0 4d 65 74 61 64 61 74 61 20 69 73 20 72 65 74 75 Metadata is retu
2b9b0 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 rned by writing
2b9c0 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f to the memory lo
2b9d0 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 cations passed a
2b9e0 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 s the 5th.** and
2b9f0 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 subsequent para
2ba00 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 meters to this f
2ba10 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 unction. Any of
2ba20 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 these arguments
2ba30 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 may be.** NULL,
2ba40 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 in which case th
2ba50 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
2ba60 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 element of metad
2ba70 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a ata is omitted..
2ba80 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
2ba90 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 e>.** <table bor
2baa0 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e der="1">.** <tr>
2bab0 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c <th> Parameter <
2bac0 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 th> Output<br>Ty
2bad0 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70 pe <th> Descrip
2bae0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c tion.**.** <tr><
2baf0 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e td> 5th <td> con
2bb00 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 st char* <td> Da
2bb10 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c ta type.** <tr><
2bb20 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e td> 6th <td> con
2bb30 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 st char* <td> Na
2bb40 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f me of default co
2bb50 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
2bb60 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 .** <tr><td> 7th
2bb70 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 <td> int
2bb80 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 <td> True if c
2bb90 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 olumn has a NOT
2bba0 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a NULL constraint.
2bbb0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 ** <tr><td> 8th
2bbc0 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 <td> int
2bbd0 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f <td> True if co
2bbe0 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 lumn is part of
2bbf0 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a the PRIMARY KEY.
2bc00 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 ** <tr><td> 9th
2bc10 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 <td> int
2bc20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f <td> True if co
2bc30 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 lumn is [AUTOINC
2bc40 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 REMENT].** </tab
2bc50 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 le>.** </blockqu
2bc60 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d ote>.**.** The m
2bc70 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f emory pointed to
2bc80 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65 by the characte
2bc90 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 r pointers retur
2bca0 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 ned for the.** d
2bcb0 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 eclaration type
2bcc0 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 and collation se
2bcd0 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 quence is valid
2bce0 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e only until the n
2bcf0 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 ext.** call to a
2bd00 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 ny SQLite API fu
2bd10 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 nction..**.** If
2bd20 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74 the specified t
2bd30 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 able is actually
2bd40 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 a view, an [err
2bd50 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
2bd60 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 rned..**.** If t
2bd70 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c he specified col
2bd80 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20 umn is "rowid",
2bd90 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 "oid" or "_rowid
2bda0 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e _" and an.** [IN
2bdb0 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 TEGER PRIMARY KE
2bdc0 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 Y] column has be
2bdd0 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 en explicitly de
2bde0 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65 clared, then the
2bdf0 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d output.** param
2be00 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66 6f eters are set fo
2be10 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79 r the explicitly
2be20 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e declared column
2be30 2e 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f . If there is no
2be40 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 .** explicitly d
2be50 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52 eclared [INTEGER
2be60 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f PRIMARY KEY] co
2be70 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f lumn, then the o
2be80 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 utput.** paramet
2be90 65 72 73 20 61 72 65 20 73 65 74 20 61 73 20 66 ers are set as f
2bea0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 ollows:.**.** <p
2beb0 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 re>.** data
2bec0 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a type: "INTEGER".
2bed0 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e ** collation
2bee0 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 sequence: "BINA
2bef0 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e RY".** not n
2bf00 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 ull: 0.** pr
2bf10 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 imary key: 1.**
2bf20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 auto increme
2bf30 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a nt: 0.** </pre>.
2bf40 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 **.** This funct
2bf50 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 ion may load one
2bf60 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 or more schemas
2bf70 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 from database f
2bf80 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 iles. If an.** e
2bf90 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 rror occurs duri
2bfa0 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c ng this process,
2bfb0 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65 or if the reque
2bfc0 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f sted table or co
2bfd0 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 lumn.** cannot b
2bfe0 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 e found, an [err
2bff0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
2c000 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f rned and an erro
2c010 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74 0a 2a r message left.*
2c020 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 * in the [databa
2c030 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 se connection] (
2c040 74 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20 to be retrieved
2c050 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 using sqlite3_er
2c060 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 rmsg())..**.** T
2c070 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 his API is only
2c080 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 available if the
2c090 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d library was com
2c0a0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a piled with the.*
2c0b0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 * [SQLITE_ENABLE
2c0c0 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 _COLUMN_METADATA
2c0d0 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C-preprocessor
2c0e0 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e symbol defined.
2c0f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2c100 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 table_column_met
2c110 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 adata(. sqlite3
2c120 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
2c130 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 /* Connecti
2c140 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 on handle */. c
2c150 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 onst char *zDbNa
2c160 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 me, /* Da
2c170 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e tabase name or N
2c180 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ULL */. const c
2c190 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c har *zTableName,
2c1a0 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 /* Table na
2c1b0 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 me */. const ch
2c1c0 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c ar *zColumnName,
2c1d0 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 /* Column na
2c1e0 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e me */. char con
2c1f0 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c st **pzDataType,
2c200 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 /* OUTPUT: D
2c210 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 eclared data typ
2c220 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 e */. char cons
2c230 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 t **pzCollSeq,
2c240 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f /* OUTPUT: Co
2c250 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
2c260 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a name */. int *
2c270 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 pNotNull,
2c280 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 /* OUTPUT
2c290 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 : True if NOT NU
2c2a0 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 LL constraint ex
2c2b0 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 ists */. int *p
2c2c0 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 PrimaryKey,
2c2d0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a /* OUTPUT:
2c2e0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 True if column
2c2f0 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 part of PK */.
2c300 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 int *pAutoinc
2c310 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f /* O
2c320 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 UTPUT: True if c
2c330 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e olumn is auto-in
2c340 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f crement */.);../
2c350 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c *.** CAPI3REF: L
2c360 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e oad An Extension
2c370 20 7b 48 31 32 36 30 30 7d 20 3c 53 32 30 35 30 {H12600} <S2050
2c380 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 0>.**.** This in
2c390 74 65 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e terface loads an
2c3a0 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f SQLite extensio
2c3b0 6e 20 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 n library from t
2c3c0 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a he named file..*
2c3d0 2a 0a 2a 2a 20 7b 48 31 32 36 30 31 7d 20 54 68 *.** {H12601} Th
2c3e0 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 e sqlite3_load_e
2c3f0 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 xtension() inter
2c400 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f face attempts to
2c410 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 20 20 20 20 load an.**
2c420 20 20 20 20 20 53 51 4c 69 74 65 20 65 78 74 65 SQLite exte
2c430 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f nsion library co
2c440 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 ntained in the f
2c450 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a ile zFile..**.**
2c460 20 7b 48 31 32 36 30 32 7d 20 54 68 65 20 65 6e {H12602} The en
2c470 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 try point is zPr
2c480 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 oc..**.** {H1260
2c490 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 3} zProc may be
2c4a0 30 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 0, in which case
2c4b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
2c4c0 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 entry point.**
2c4d0 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 default
2c4e0 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 s to "sqlite3_ex
2c4f0 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a tension_init"..*
2c500 2a 0a 2a 2a 20 7b 48 31 32 36 30 34 7d 20 54 68 *.** {H12604} Th
2c510 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 e sqlite3_load_e
2c520 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 xtension() inter
2c530 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75 72 face shall retur
2c540 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 n.** [S
2c550 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
2c560 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 cess and [SQLITE
2c570 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 _ERROR] if somet
2c580 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e hing goes wrong.
2c590 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 35 7d 20 .**.** {H12605}
2c5a0 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 If an error occu
2c5b0 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 rs and pzErrMsg
2c5c0 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 is not 0, then t
2c5d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
2c5e0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 sqlite3_load_ext
2c5f0 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 ension()] interf
2c600 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 ace shall attemp
2c610 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 t to.**
2c620 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 fill *pzErrMsg
2c630 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73 73 61 with error messa
2c640 67 65 20 74 65 78 74 20 73 74 6f 72 65 64 20 69 ge text stored i
2c650 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 n memory.**
2c660 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72 obtained fr
2c670 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
2c680 6f 63 28 29 5d 2e 20 7b 45 4e 44 7d 20 20 54 68 oc()]. {END} Th
2c690 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 e calling functi
2c6a0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 on.** s
2c6b0 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 hould free this
2c6c0 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e memory by callin
2c6d0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 g [sqlite3_free(
2c6e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 )]..**.** {H1260
2c6f0 36 7d 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 6} Extension loa
2c700 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61 ding must be ena
2c710 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 bled using.**
2c720 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
2c730 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 enable_load_exte
2c740 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 nsion()] prior t
2c750 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 o calling this A
2c760 50 49 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 PI,.**
2c770 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 otherwise an err
2c780 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 or will be retur
2c790 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ned..*/.int sqli
2c7a0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 te3_load_extensi
2c7b0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 on(. sqlite3 *d
2c7c0 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c b, /* L
2c7d0 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f oad the extensio
2c7e0 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61 n into this data
2c7f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2c800 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
2c810 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 *zFile, /* Na
2c820 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72 65 64 me of the shared
2c830 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e library contain
2c840 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f ing extension */
2c850 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
2c860 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 Proc, /* Entr
2c870 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 y point. Derive
2c880 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 d from zFile if
2c890 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 0 */. char **pz
2c8a0 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 ErrMsg /*
2c8b0 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 Put error messag
2c8c0 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20 e here if not 0
2c8d0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
2c8e0 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 I3REF: Enable Or
2c8f0 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69 Disable Extensi
2c900 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 48 31 32 36 on Loading {H126
2c910 32 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 20} <S20500>.**.
2c920 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 ** So as not to
2c930 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f open security ho
2c940 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 les in older app
2c950 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61 lications that a
2c960 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 re.** unprepared
2c970 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78 to deal with ex
2c980 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c tension loading,
2c990 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20 and as a means
2c9a0 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 of disabling.**
2c9b0 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e extension loadin
2c9c0 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 g while evaluati
2c9d0 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 ng user-entered
2c9e0 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 SQL, the followi
2c9f0 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 70 72 6f ng API.** is pro
2ca00 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68 vided to turn th
2ca10 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f e [sqlite3_load_
2ca20 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 extension()] mec
2ca30 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 hanism on and of
2ca40 66 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 6e 73 69 f..**.** Extensi
2ca50 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 on loading is of
2ca60 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20 53 65 f by default. Se
2ca70 65 20 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a e ticket #1863..
2ca80 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 31 7d 20 43 **.** {H12621} C
2ca90 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f all the sqlite3_
2caa0 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 enable_load_exte
2cab0 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 nsion() routine
2cac0 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a with onoff==1.**
2cad0 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 75 72 to tur
2cae0 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 n extension load
2caf0 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 ing on and call
2cb00 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 it with onoff==0
2cb10 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 20 20 20 20 to turn.**
2cb20 20 20 20 20 20 69 74 20 62 61 63 6b 20 6f 66 66 it back off
2cb30 20 61 67 61 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 again..**.** {H
2cb40 31 32 36 32 32 7d 20 45 78 74 65 6e 73 69 6f 6e 12622} Extension
2cb50 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 loading is off
2cb60 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69 by default..*/.i
2cb70 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c nt sqlite3_enabl
2cb80 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e e_load_extension
2cb90 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e (sqlite3 *db, in
2cba0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a t onoff);../*.**
2cbb0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 6f 6d CAPI3REF: Autom
2cbc0 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e atically Load An
2cbd0 20 45 78 74 65 6e 73 69 6f 6e 73 20 7b 48 31 32 Extensions {H12
2cbe0 36 34 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 640} <S20500>.**
2cbf0 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 63 61 6e .** This API can
2cc00 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 be invoked at p
2cc10 72 6f 67 72 61 6d 20 73 74 61 72 74 75 70 20 69 rogram startup i
2cc20 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73 n order to regis
2cc30 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f ter.** one or mo
2cc40 72 65 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 re statically li
2cc50 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 nked extensions
2cc60 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61 that will be ava
2cc70 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c ilable.** to all
2cc80 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 new [database c
2cc90 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20 7b 45 4e onnections]. {EN
2cca0 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f D}.**.** This ro
2ccb0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 utine stores a p
2ccc0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 ointer to the ex
2ccd0 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 tension in an ar
2cce0 72 61 79 20 74 68 61 74 20 69 73 0a 2a 2a 20 6f ray that is.** o
2ccf0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
2cd00 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
2cd10 20 20 49 66 20 79 6f 75 20 72 75 6e 20 61 20 6d If you run a m
2cd20 65 6d 6f 72 79 20 6c 65 61 6b 20 63 68 65 63 6b emory leak check
2cd30 65 72 0a 2a 2a 20 6f 6e 20 79 6f 75 72 20 70 72 er.** on your pr
2cd40 6f 67 72 61 6d 20 61 6e 64 20 69 74 20 72 65 70 ogram and it rep
2cd50 6f 72 74 73 20 61 20 6c 65 61 6b 20 62 65 63 61 orts a leak beca
2cd60 75 73 65 20 6f 66 20 74 68 69 73 20 61 72 72 61 use of this arra
2cd70 79 2c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71 y, invoke.** [sq
2cd80 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f lite3_reset_auto
2cd90 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 _extension()] pr
2cda0 69 6f 72 20 74 6f 20 73 68 75 74 64 6f 77 6e 20 ior to shutdown
2cdb0 74 6f 20 66 72 65 65 20 74 68 65 20 6d 65 6d 6f to free the memo
2cdc0 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 ry..**.** {H1264
2cdd0 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 1} This function
2cde0 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 65 78 registers an ex
2cdf0 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f tension entry po
2ce00 69 6e 74 20 74 68 61 74 20 69 73 0a 2a 2a 20 20 int that is.**
2ce10 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 automati
2ce20 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20 77 68 cally invoked wh
2ce30 65 6e 65 76 65 72 20 61 20 6e 65 77 20 5b 64 61 enever a new [da
2ce40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2ce50 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 n].** i
2ce60 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 20 5b s opened using [
2ce70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
2ce80 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
2ce90 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ()],.**
2cea0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 or [sqlite3_ope
2ceb0 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b n_v2()]..**.** {
2cec0 48 31 32 36 34 32 7d 20 44 75 70 6c 69 63 61 74 H12642} Duplicat
2ced0 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 72 65 e extensions are
2cee0 20 64 65 74 65 63 74 65 64 20 73 6f 20 63 61 6c detected so cal
2cef0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e ling this routin
2cf00 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75 e.** mu
2cf10 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 ltiple times wit
2cf20 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e h the same exten
2cf30 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 sion is harmless
2cf40 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 33 7d ..**.** {H12643}
2cf50 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 This routine st
2cf60 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 ores a pointer t
2cf70 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 o the extension
2cf80 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20 20 in an array.**
2cf90 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20 that is
2cfa0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
2cfb0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
2cfc0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 34 7d ..**.** {H12644}
2cfd0 20 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e Automatic exten
2cfe0 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f sions apply acro
2cff0 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a ss all threads..
2d000 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 */.int sqlite3_a
2d010 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f uto_extension(vo
2d020 69 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 id (*xEntryPoint
2d030 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a )(void));../*.**
2d040 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 CAPI3REF: Reset
2d050 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e Automatic Exten
2d060 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 48 31 sion Loading {H1
2d070 32 36 36 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2660} <S20500>.*
2d080 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
2d090 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 on disables all
2d0a0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 previously regis
2d0b0 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63 0a tered automatic.
2d0c0 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 7b ** extensions. {
2d0d0 45 4e 44 7d 20 20 49 74 20 75 6e 64 6f 65 73 20 END} It undoes
2d0e0 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 61 6c the effect of al
2d0f0 6c 20 70 72 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 l prior.** [sqli
2d100 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 te3_auto_extensi
2d110 6f 6e 28 29 5d 20 63 61 6c 6c 73 2e 0a 2a 2a 0a on()] calls..**.
2d120 2a 2a 20 7b 48 31 32 36 36 31 7d 20 54 68 69 73 ** {H12661} This
2d130 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c function disabl
2d140 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c es all previousl
2d150 79 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 y registered.**
2d160 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 automat
2d170 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 2e 0a 2a ic extensions..*
2d180 2a 0a 2a 2a 20 7b 48 31 32 36 36 32 7d 20 54 68 *.** {H12662} Th
2d190 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 is function disa
2d1a0 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 63 20 65 bles automatic e
2d1b0 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c xtensions in all
2d1c0 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 threads..*/.voi
2d1d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f d sqlite3_reset_
2d1e0 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 auto_extension(v
2d1f0 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a oid);../*.******
2d200 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 EXPERIMENTAL -
2d210 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
2d220 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 e without notice
2d230 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a **************.
2d240 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 **.** The interf
2d250 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 ace to the virtu
2d260 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 al-table mechani
2d270 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 sm is currently
2d280 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f considered.** to
2d290 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c be experimental
2d2a0 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 . The interface
2d2b0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e might change in
2d2c0 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 incompatible wa
2d2d0 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 ys..** If this i
2d2e0 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 s a problem for
2d2f0 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 you, do not use
2d300 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 the interface at
2d310 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a this time..**.*
2d320 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 * When the virtu
2d330 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 al-table mechani
2d340 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 sm stabilizes, w
2d350 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 e will declare t
2d360 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 he.** interface
2d370 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 fixed, support i
2d380 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 t indefinitely,
2d390 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 and remove this
2d3a0 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a comment..*/../*.
2d3b0 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20 75 73 ** Structures us
2d3c0 65 64 20 62 79 20 74 68 65 20 76 69 72 74 75 61 ed by the virtua
2d3d0 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 l table interfac
2d3e0 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 e.*/.typedef str
2d3f0 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 uct sqlite3_vtab
2d400 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74 sqlite3_vtab;.t
2d410 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
2d420 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f lite3_index_info
2d430 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 sqlite3_index_i
2d440 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 74 72 nfo;.typedef str
2d450 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 uct sqlite3_vtab
2d460 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65 33 5f _cursor sqlite3_
2d470 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70 vtab_cursor;.typ
2d480 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
2d490 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74 te3_module sqlit
2d4a0 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a e3_module;../*.*
2d4b0 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 * CAPI3REF: Virt
2d4c0 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63 74 ual Table Object
2d4d0 20 7b 48 31 38 30 30 30 7d 20 3c 53 32 30 34 30 {H18000} <S2040
2d4e0 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 0>.** KEYWORDS:
2d4f0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 0a 2a sqlite3_module.*
2d500 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
2d510 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69 73 *.** A module is
2d520 20 61 20 63 6c 61 73 73 20 6f 66 20 76 69 72 74 a class of virt
2d530 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 61 63 ual tables. Eac
2d540 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 66 69 h module is defi
2d550 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e 73 ned.** by an ins
2d560 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f 6c tance of the fol
2d570 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 lowing structure
2d580 2e 20 20 54 68 69 73 20 73 74 72 75 63 74 75 72 . This structur
2d590 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d 6f e consists.** mo
2d5a0 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 stly of methods
2d5b0 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a for the module..
2d5c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
2d5d0 66 61 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 face is experime
2d5e0 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a ntal and is subj
2d5f0 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 ect to change or
2d600 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 .** removal in f
2d610 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
2d620 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 74 72 f SQLite..*/.str
2d630 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 uct sqlite3_modu
2d640 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 le {. int iVers
2d650 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 ion;. int (*xCr
2d660 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 eate)(sqlite3*,
2d670 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 void *pAux,.
2d680 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 int a
2d690 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 rgc, const char
2d6a0 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 *const*argv,.
2d6b0 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 sqli
2d6c0 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 te3_vtab **ppVTa
2d6d0 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e b, char**);. in
2d6e0 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 t (*xConnect)(sq
2d6f0 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 lite3*, void *pA
2d700 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 ux,.
2d710 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e int argc, con
2d720 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 st char *const*a
2d730 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 rgv,.
2d740 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 sqlite3_vtab
2d750 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a **ppVTab, char*
2d760 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 *);. int (*xBes
2d770 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f tIndex)(sqlite3_
2d780 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c vtab *pVTab, sql
2d790 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a ite3_index_info*
2d7a0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63 );. int (*xDisc
2d7b0 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f onnect)(sqlite3_
2d7c0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
2d7d0 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28 int (*xDestroy)(
2d7e0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
2d7f0 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f Tab);. int (*xO
2d800 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 pen)(sqlite3_vta
2d810 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 b *pVTab, sqlite
2d820 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 3_vtab_cursor **
2d830 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 ppCursor);. int
2d840 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 (*xClose)(sqlit
2d850 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 e3_vtab_cursor*)
2d860 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 ;. int (*xFilte
2d870 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f r)(sqlite3_vtab_
2d880 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 cursor*, int idx
2d890 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 Num, const char
2d8a0 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20 *idxStr,.
2d8b0 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 int arg
2d8c0 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 c, sqlite3_value
2d8d0 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 **argv);. int
2d8e0 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33 (*xNext)(sqlite3
2d8f0 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a _vtab_cursor*);.
2d900 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 int (*xEof)(sq
2d910 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
2d920 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f r*);. int (*xCo
2d930 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 lumn)(sqlite3_vt
2d940 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 ab_cursor*, sqli
2d950 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
2d960 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 t);. int (*xRow
2d970 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 id)(sqlite3_vtab
2d980 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 _cursor*, sqlite
2d990 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3_int64 *pRowid)
2d9a0 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74 ;. int (*xUpdat
2d9b0 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 e)(sqlite3_vtab
2d9c0 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f *, int, sqlite3_
2d9d0 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 value **, sqlite
2d9e0 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 3_int64 *);. in
2d9f0 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 t (*xBegin)(sqli
2da00 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 te3_vtab *pVTab)
2da10 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 ;. int (*xSync)
2da20 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
2da30 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 VTab);. int (*x
2da40 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f Commit)(sqlite3_
2da50 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
2da60 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 int (*xRollback)
2da70 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
2da80 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 VTab);. int (*x
2da90 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 FindFunction)(sq
2daa0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 lite3_vtab *pVta
2dab0 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e b, int nArg, con
2dac0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a st char *zName,.
2dad0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2dae0 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 void (**p
2daf0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 xFunc)(sqlite3_c
2db00 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
2db10 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
2db20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2db30 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 void **ppAr
2db40 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e g);. int (*xRen
2db50 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ame)(sqlite3_vta
2db60 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 b *pVtab, const
2db70 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a char *zNew);.};.
2db80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2db90 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 Virtual Table I
2dba0 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 ndexing Informat
2dbb0 69 6f 6e 20 7b 48 31 38 31 30 30 7d 20 3c 53 32 ion {H18100} <S2
2dbc0 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0400>.** KEYWORD
2dbd0 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 S: sqlite3_index
2dbe0 5f 69 6e 66 6f 0a 2a 2a 20 45 58 50 45 52 49 4d _info.** EXPERIM
2dbf0 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ENTAL.**.** The
2dc00 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e sqlite3_index_in
2dc10 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 fo structure and
2dc20 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75 72 its substructur
2dc30 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a es is used to.**
2dc40 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f pass informatio
2dc50 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 n into and recei
2dc60 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f ve the reply fro
2dc70 6d 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 m the xBestIndex
2dc80 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e .** method of an
2dc90 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e sqlite3_module.
2dca0 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 The fields und
2dcb0 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 er **Inputs** ar
2dcc0 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 e the.** inputs
2dcd0 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e to xBestIndex an
2dce0 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e d are read-only.
2dcf0 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 xBestIndex ins
2dd00 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 erts its.** resu
2dd10 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f lts into the **O
2dd20 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e utputs** fields.
2dd30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 .**.** The aCons
2dd40 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 traint[] array r
2dd50 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 ecords WHERE cla
2dd60 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 use constraints
2dd70 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a of the form:.**.
2dd80 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 4f ** <pre>column O
2dd90 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a 0a P expr</pre>.**.
2dda0 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d ** where OP is =
2ddb0 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 , <, <=, &
2ddc0 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20 20 gt;, or >=.
2ddd0 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f The particular o
2dde0 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 perator is.** st
2ddf0 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 ored in aConstra
2de00 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 int[].op. The i
2de10 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 ndex of the colu
2de20 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a mn is stored in.
2de30 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d ** aConstraint[]
2de40 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 .iColumn. aCons
2de50 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 traint[].usable
2de60 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a is TRUE if the.*
2de70 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 * expr on the ri
2de80 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 ght-hand side ca
2de90 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 n be evaluated (
2dea0 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e and thus the con
2deb0 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 straint.** is us
2dec0 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 able) and false
2ded0 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a if it cannot..**
2dee0 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 .** The optimize
2def0 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 r automatically
2df00 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 inverts terms of
2df10 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 the form "expr
2df20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e OP column".** an
2df30 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 d makes other si
2df40 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f mplifications to
2df50 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 the WHERE claus
2df60 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 e in an attempt
2df70 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e to.** get as man
2df80 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 y WHERE clause t
2df90 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f erms into the fo
2dfa0 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 rm shown above a
2dfb0 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 s possible..** T
2dfc0 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d he aConstraint[]
2dfd0 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f array only repo
2dfe0 72 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 rts WHERE clause
2dff0 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f terms in the co
2e000 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 rrect.** form th
2e010 61 74 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 at refer to the
2e020 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 particular virtu
2e030 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 al table being q
2e040 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e ueried..**.** In
2e050 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 formation about
2e060 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 the ORDER BY cla
2e070 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e use is stored in
2e080 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 aOrderBy[]..**
2e090 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 Each term of aOr
2e0a0 64 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 derBy records a
2e0b0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 column of the OR
2e0c0 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a DER BY clause..*
2e0d0 2a 0a 2a 2a 20 54 68 65 20 78 42 65 73 74 49 6e *.** The xBestIn
2e0e0 64 65 78 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 dex method must
2e0f0 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 fill aConstraint
2e100 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 Usage[] with inf
2e110 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 ormation.** abou
2e120 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 t what parameter
2e130 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 s to pass to xFi
2e140 6c 74 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e lter. If argvIn
2e150 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 dex>0 then.** th
2e160 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 e right-hand sid
2e170 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 e of the corresp
2e180 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 onding aConstrai
2e190 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 nt[] is evaluate
2e1a0 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 d.** and becomes
2e1b0 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 the argvIndex-t
2e1c0 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e h entry in argv.
2e1d0 20 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 If aConstraint
2e1e0 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 Usage[].omit.**
2e1f0 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 is true, then th
2e200 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 e constraint is
2e210 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 assumed to be fu
2e220 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 lly handled by t
2e230 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 he.** virtual ta
2e240 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 ble and is not c
2e250 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 hecked again by
2e260 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 SQLite..**.** Th
2e270 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 e idxNum and idx
2e280 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 Ptr values are r
2e290 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 ecorded and pass
2e2a0 65 64 20 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e ed into xFilter.
2e2b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 .** sqlite3_free
2e2c0 28 29 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 () is used to fr
2e2d0 65 65 20 69 64 78 50 74 72 20 69 66 20 6e 65 65 ee idxPtr if nee
2e2e0 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69 73 dToFreeIdxPtr is
2e2f0 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 true..**.** The
2e300 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 orderByConsumed
2e310 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70 means that outp
2e320 75 74 20 66 72 6f 6d 20 78 46 69 6c 74 65 72 20 ut from xFilter
2e330 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a will occur in.**
2e340 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 the correct ord
2e350 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 er to satisfy th
2e360 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 e ORDER BY claus
2e370 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 e so that no sep
2e380 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 arate.** sorting
2e390 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65 step is require
2e3a0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 d..**.** The est
2e3b0 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 imatedCost value
2e3c0 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 is an estimate
2e3d0 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 of the cost of d
2e3e0 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 oing the.** part
2e3f0 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 icular lookup.
2e400 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 A full scan of a
2e410 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e table with N en
2e420 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 tries should hav
2e430 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e e.** a cost of N
2e440 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 . A binary sear
2e450 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 ch of a table of
2e460 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c N entries shoul
2e470 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 d have a.** cost
2e480 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c of approximatel
2e490 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2a 0a 2a 2a 20 y log(N)..**.**
2e4a0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 This interface i
2e4b0 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 s experimental a
2e4c0 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f nd is subject to
2e4d0 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 change or.** re
2e4e0 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 moval in future
2e4f0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
2e500 74 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 te..*/.struct sq
2e510 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f lite3_index_info
2e520 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a {. /* Inputs *
2e530 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 /. int nConstra
2e540 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 2f int; /
2e550 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 * Number of entr
2e560 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 ies in aConstrai
2e570 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 nt */. struct s
2e580 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e qlite3_index_con
2e590 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 straint {. i
2e5a0 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 nt iColumn;
2e5b0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 /* Colu
2e5c0 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 mn on left-hand
2e5d0 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 side of constrai
2e5e0 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 nt */. unsig
2e5f0 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20 ned char op;
2e600 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 /* Constrai
2e610 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 nt operator */.
2e620 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 unsigned cha
2e630 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a r usable; /*
2e640 20 54 72 75 65 20 69 66 20 74 68 69 73 20 63 6f True if this co
2e650 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 61 62 nstraint is usab
2e660 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 le */. int i
2e670 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 TermOffset;
2e680 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 /* Used int
2e690 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 ernally - xBestI
2e6a0 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f ndex should igno
2e6b0 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 re */. } *aCons
2e6c0 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 traint;
2e6d0 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 /* Table of W
2e6e0 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 HERE clause cons
2e6f0 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 traints */. int
2e700 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 nOrderBy;
2e710 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 /* Numbe
2e720 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68 r of terms in th
2e730 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 e ORDER BY claus
2e740 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 e */. struct sq
2e750 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 lite3_index_orde
2e760 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 rby {. int i
2e770 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 Column;
2e780 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e /* Column n
2e790 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e umber */. un
2e7a0 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 73 63 signed char desc
2e7b0 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 ; /* True
2e7c0 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65 for DESC. False
2e7d0 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d for ASC. */. }
2e7e0 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 *aOrderBy;
2e7f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65 /* The
2e800 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 ORDER BY clause
2e810 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 */. /* Outputs
2e820 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c */. struct sql
2e830 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 ite3_index_const
2e840 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 raint_usage {.
2e850 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b int argvIndex;
2e860 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66 /* if
2e870 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 >0, constraint
2e880 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 76 20 is part of argv
2e890 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 to xFilter */.
2e8a0 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 unsigned char
2e8b0 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f omit; /* Do
2e8c0 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74 not code a test
2e8d0 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72 for this constr
2e8e0 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f aint */. } *aCo
2e8f0 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 nstraintUsage;.
2e900 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 int idxNum;
2e910 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e /* N
2e920 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69 64 umber used to id
2e930 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65 78 entify the index
2e940 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53 */. char *idxS
2e950 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 tr;
2e960 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 /* String, poss
2e970 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 ibly obtained fr
2e980 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f om sqlite3_mallo
2e990 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 c */. int needT
2e9a0 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 20 20 oFreeIdxStr;
2e9b0 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72 /* Free idxStr
2e9c0 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 using sqlite3_f
2e9d0 72 65 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f ree() if true */
2e9e0 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f . int orderByCo
2e9f0 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a nsumed; /*
2ea00 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 74 20 True if output
2ea10 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72 is already order
2ea20 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 ed */. double e
2ea30 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 stimatedCost;
2ea40 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 /* Estimated
2ea50 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68 cost of using th
2ea60 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 is index */.};.#
2ea70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
2ea80 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 DEX_CONSTRAINT_E
2ea90 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 Q 2.#define S
2eaa0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 QLITE_INDEX_CONS
2eab0 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 TRAINT_GT 4.#
2eac0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
2ead0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c DEX_CONSTRAINT_L
2eae0 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 E 8.#define S
2eaf0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 QLITE_INDEX_CONS
2eb00 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a TRAINT_LT 16.
2eb10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
2eb20 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f NDEX_CONSTRAINT_
2eb30 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 GE 32.#define
2eb40 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
2eb50 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 NSTRAINT_MATCH 6
2eb60 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 4../*.** CAPI3RE
2eb70 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 56 69 F: Register A Vi
2eb80 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c rtual Table Impl
2eb90 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 31 38 32 ementation {H182
2eba0 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 00} <S20400>.**
2ebb0 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
2ebc0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
2ebd0 69 73 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 is used to regis
2ebe0 74 65 72 20 61 20 6e 65 77 20 6d 6f 64 75 6c 65 ter a new module
2ebf0 20 6e 61 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 name with a.**
2ec00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2ec10 74 69 6f 6e 5d 2e 20 20 4d 6f 64 75 6c 65 20 6e tion]. Module n
2ec20 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65 67 ames must be reg
2ec30 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 0a 2a istered before.*
2ec40 2a 20 63 72 65 61 74 69 6e 67 20 6e 65 77 20 76 * creating new v
2ec50 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6f 6e irtual tables on
2ec60 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 the module, or
2ec70 62 65 66 6f 72 65 20 75 73 69 6e 67 0a 2a 2a 20 before using.**
2ec80 70 72 65 65 78 69 73 74 69 6e 67 20 76 69 72 74 preexisting virt
2ec90 75 61 6c 20 74 61 62 6c 65 73 20 6f 66 20 74 68 ual tables of th
2eca0 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 e module..**.**
2ecb0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 This interface i
2ecc0 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 s experimental a
2ecd0 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f nd is subject to
2ece0 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 change or.** re
2ecf0 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 moval in future
2ed00 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
2ed10 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 te..*/.SQLITE_EX
2ed20 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 PERIMENTAL int s
2ed30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f qlite3_create_mo
2ed40 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 dule(. sqlite3
2ed50 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
2ed60 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e /* SQLite con
2ed70 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 nection to regis
2ed80 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 ter module with
2ed90 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
2eda0 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 *zName,
2edb0 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d /* Name of the m
2edc0 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 odule */. const
2edd0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 sqlite3_module
2ede0 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 *, /* Methods
2edf0 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 for the module
2ee00 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 20 20 20 20 */. void *
2ee10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2ee20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 /* Client data f
2ee30 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e or xCreate/xConn
2ee40 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a ect */.);../*.**
2ee50 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 CAPI3REF: Regis
2ee60 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 ter A Virtual Ta
2ee70 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 ble Implementati
2ee80 6f 6e 20 7b 48 31 38 32 31 30 7d 20 3c 53 32 30 on {H18210} <S20
2ee90 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 400>.** EXPERIME
2eea0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 NTAL.**.** This
2eeb0 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65 6e 74 routine is ident
2eec0 69 63 61 6c 20 74 6f 20 74 68 65 20 5b 73 71 6c ical to the [sql
2eed0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 ite3_create_modu
2eee0 6c 65 28 29 5d 20 6d 65 74 68 6f 64 20 61 62 6f le()] method abo
2eef0 76 65 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 ve,.** except th
2ef00 61 74 20 69 74 20 61 6c 6c 6f 77 73 20 61 20 64 at it allows a d
2ef10 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 estructor functi
2ef20 6f 6e 20 74 6f 20 62 65 20 73 70 65 63 69 66 69 on to be specifi
2ef30 65 64 2e 20 49 74 20 69 73 0a 2a 2a 20 65 76 65 ed. It is.** eve
2ef40 6e 20 6d 6f 72 65 20 65 78 70 65 72 69 6d 65 6e n more experimen
2ef50 74 61 6c 20 74 68 61 6e 20 74 68 65 20 72 65 73 tal than the res
2ef60 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c t of the virtual
2ef70 20 74 61 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a tables API..*/.
2ef80 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e SQLITE_EXPERIMEN
2ef90 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TAL int sqlite3_
2efa0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 create_module_v2
2efb0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
2efc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
2efd0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 * SQLite connect
2efe0 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 ion to register
2eff0 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 module with */.
2f000 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
2f010 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e me, /* N
2f020 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c ame of the modul
2f030 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c e */. const sql
2f040 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 ite3_module *,
2f050 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 /* Methods for
2f060 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 the module */.
2f070 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 void *,
2f080 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 /* C
2f090 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 lient data for x
2f0a0 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 Create/xConnect
2f0b0 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 */. void(*xDest
2f0c0 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20 roy)(void*)
2f0d0 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 /* Module destru
2f0e0 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f ctor function */
2f0f0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
2f100 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 REF: Virtual Tab
2f110 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 le Instance Obje
2f120 63 74 20 7b 48 31 38 30 31 30 7d 20 3c 53 32 30 ct {H18010} <S20
2f130 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 400>.** KEYWORDS
2f140 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a : sqlite3_vtab.*
2f150 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
2f160 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c *.** Every modul
2f170 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2f180 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 uses a subclass
2f190 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e of the followin
2f1a0 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 74 g structure.** t
2f1b0 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72 o describe a par
2f1c0 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 ticular instance
2f1d0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 of the module.
2f1e0 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77 Each subclass w
2f1f0 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 ill.** be tailor
2f200 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 ed to the specif
2f210 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20 ic needs of the
2f220 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 module implement
2f230 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 ation..** The pu
2f240 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75 rpose of this su
2f250 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64 perclass is to d
2f260 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69 efine certain fi
2f270 65 6c 64 73 20 74 68 61 74 20 61 72 65 0a 2a 2a elds that are.**
2f280 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d common to all m
2f290 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 odule implementa
2f2a0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 tions..**.** Vir
2f2b0 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 tual tables meth
2f2c0 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 ods can set an e
2f2d0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 rror message by
2f2e0 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 assigning a.** s
2f2f0 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 tring obtained f
2f300 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 rom [sqlite3_mpr
2f310 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d intf()] to zErrM
2f320 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20 sg. The method
2f330 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 should.** take c
2f340 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69 are that any pri
2f350 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65 or string is fre
2f360 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 ed by a call to
2f370 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
2f380 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 .** prior to ass
2f390 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 igning a new str
2f3a0 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 ing to zErrMsg.
2f3b0 20 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 After the error
2f3c0 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 message.** is d
2f3d0 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74 elivered up to t
2f3e0 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 he client applic
2f3f0 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e ation, the strin
2f400 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 g will be automa
2f410 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 tically.** freed
2f420 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 by sqlite3_free
2f430 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d () and the zErrM
2f440 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 sg field will be
2f450 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a zeroed. Note.*
2f460 2a 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 6d * that sqlite3_m
2f470 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c printf() and sql
2f480 69 74 65 33 5f 66 72 65 65 28 29 20 61 72 65 20 ite3_free() are
2f490 75 73 65 64 20 6f 6e 20 74 68 65 20 7a 45 72 72 used on the zErr
2f4a0 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e Msg field.** sin
2f4b0 63 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 ce virtual table
2f4c0 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69 s are commonly i
2f4d0 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f mplemented in lo
2f4e0 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e adable extension
2f4f0 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f s which.** do no
2f500 74 20 68 61 76 65 20 61 63 63 65 73 73 20 74 6f t have access to
2f510 20 73 71 6c 69 74 65 33 4d 50 72 69 6e 74 66 28 sqlite3MPrintf(
2f520 29 20 6f 72 20 73 71 6c 69 74 65 33 46 72 65 65 ) or sqlite3Free
2f530 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 ()..**.** This i
2f540 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 nterface is expe
2f550 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 rimental and is
2f560 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
2f570 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 e or.** removal
2f580 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
2f590 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f es of SQLite..*/
2f5a0 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
2f5b0 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 vtab {. const s
2f5c0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 qlite3_module *p
2f5d0 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 Module; /* The
2f5e0 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 module for this
2f5f0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f virtual table */
2f600 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 . int nRef;
2f610 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2f620 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 /* Used inter
2f630 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20 nally */. char
2f640 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 *zErrMsg;
2f650 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 /* Er
2f660 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d ror message from
2f670 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 sqlite3_mprintf
2f680 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 () */. /* Virtu
2f690 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 al table impleme
2f6a0 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 ntations will ty
2f6b0 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 pically add addi
2f6c0 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f tional fields */
2f6d0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
2f6e0 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 REF: Virtual Tab
2f6f0 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63 74 le Cursor Object
2f700 20 20 7b 48 31 38 30 32 30 7d 20 3c 53 32 30 34 {H18020} <S204
2f710 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 00>.** KEYWORDS:
2f720 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 sqlite3_vtab_cu
2f730 72 73 6f 72 0a 2a 2a 20 45 58 50 45 52 49 4d 45 rsor.** EXPERIME
2f740 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 NTAL.**.** Every
2f750 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e module implemen
2f760 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 tation uses a su
2f770 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20 66 6f bclass of the fo
2f780 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 llowing structur
2f790 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 62 65 e.** to describe
2f7a0 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f cursors that po
2f7b0 69 6e 74 20 69 6e 74 6f 20 74 68 65 20 76 69 72 int into the vir
2f7c0 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 61 tual table and a
2f7d0 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f re used.** to lo
2f7e0 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76 op through the v
2f7f0 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 irtual table. C
2f800 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74 ursors are creat
2f810 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 ed using the.**
2f820 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 xOpen method of
2f830 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 the module. Eac
2f840 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 h module impleme
2f850 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 ntation will def
2f860 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 ine.** the conte
2f870 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73 nt of a cursor s
2f880 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 69 74 tructure to suit
2f890 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a its own needs..
2f8a0 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72 **.** This super
2f8b0 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e 20 class exists in
2f8c0 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20 order to define
2f8d0 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75 fields of the cu
2f8e0 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 rsor that.** are
2f8f0 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 common to all i
2f900 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a mplementations..
2f910 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
2f920 66 61 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 face is experime
2f930 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a ntal and is subj
2f940 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 ect to change or
2f950 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 .** removal in f
2f960 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
2f970 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 74 72 f SQLite..*/.str
2f980 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 uct sqlite3_vtab
2f990 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 _cursor {. sqli
2f9a0 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b te3_vtab *pVtab;
2f9b0 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c /* Virtual
2f9c0 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 table of this c
2f9d0 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 ursor */. /* Vi
2f9e0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c rtual table impl
2f9f0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c ementations will
2fa00 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 typically add a
2fa10 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
2fa20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
2fa30 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20 PI3REF: Declare
2fa40 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20 The Schema Of A
2fa50 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 48 Virtual Table {H
2fa60 31 38 32 38 30 7d 20 3c 53 32 30 34 30 30 3e 0a 18280} <S20400>.
2fa70 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
2fa80 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65 61 74 **.** The xCreat
2fa90 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20 6d e and xConnect m
2faa0 65 74 68 6f 64 73 20 6f 66 20 61 20 6d 6f 64 75 ethods of a modu
2fab0 6c 65 20 75 73 65 20 74 68 65 20 66 6f 6c 6c 6f le use the follo
2fac0 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74 6f 20 64 wing API.** to d
2fad0 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 eclare the forma
2fae0 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 t (the names and
2faf0 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 datatypes of th
2fb00 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a e columns) of.**
2fb10 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 the virtual tab
2fb20 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 les they impleme
2fb30 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 nt..**.** This i
2fb40 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 nterface is expe
2fb50 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 rimental and is
2fb60 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
2fb70 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 e or.** removal
2fb80 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
2fb90 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f es of SQLite..*/
2fba0 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 .SQLITE_EXPERIME
2fbb0 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 NTAL int sqlite3
2fbc0 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71 _declare_vtab(sq
2fbd0 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 lite3*, const ch
2fbe0 61 72 20 2a 7a 43 72 65 61 74 65 54 61 62 6c 65 ar *zCreateTable
2fbf0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2fc00 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 EF: Overload A F
2fc10 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 unction For A Vi
2fc20 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 rtual Table {H18
2fc30 33 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 300} <S20400>.**
2fc40 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
2fc50 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c .** Virtual tabl
2fc60 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61 es can provide a
2fc70 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 lternative imple
2fc80 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 mentations of fu
2fc90 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 nctions.** using
2fca0 20 74 68 65 20 78 46 69 6e 64 46 75 6e 63 74 69 the xFindFuncti
2fcb0 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42 75 74 20 on method. But
2fcc0 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 global versions
2fcd0 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f of those functio
2fce0 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 ns.** must exist
2fcf0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 in order to be
2fd00 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a overloaded..**.*
2fd10 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b 65 73 * This API makes
2fd20 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 sure a global v
2fd30 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 ersion of a func
2fd40 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72 74 tion with a part
2fd50 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 icular.** name a
2fd60 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 nd number of par
2fd70 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e 20 ameters exists.
2fd80 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 If no such func
2fd90 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 tion exists.** b
2fda0 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20 69 efore this API i
2fdb0 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 s called, a new
2fdc0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 61 function is crea
2fdd0 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d ted. The implem
2fde0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 entation.** of t
2fdf0 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 he new function
2fe00 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 61 6e always causes an
2fe10 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 exception to be
2fe20 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 thrown. So.**
2fe30 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e the new function
2fe40 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 is not good for
2fe50 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74 73 anything by its
2fe60 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a elf. Its only.*
2fe70 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f 20 * purpose is to
2fe80 62 65 20 61 20 70 6c 61 63 65 68 6f 6c 64 65 72 be a placeholder
2fe90 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 function that c
2fea0 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 an be overloaded
2feb0 0a 2a 2a 20 62 79 20 76 69 72 74 75 61 6c 20 74 .** by virtual t
2fec0 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 ables..**.** Thi
2fed0 73 20 41 50 49 20 73 68 6f 75 6c 64 20 62 65 20 s API should be
2fee0 63 6f 6e 73 69 64 65 72 65 64 20 70 61 72 74 20 considered part
2fef0 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 of the virtual t
2ff00 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 2c 0a able interface,.
2ff10 2a 2a 20 77 68 69 63 68 20 69 73 20 65 78 70 65 ** which is expe
2ff20 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 73 75 62 rimental and sub
2ff30 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a ject to change..
2ff40 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 */.SQLITE_EXPERI
2ff50 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 MENTAL int sqlit
2ff60 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 e3_overload_func
2ff70 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 tion(sqlite3*, c
2ff80 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 onst char *zFunc
2ff90 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b Name, int nArg);
2ffa0 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 ../*.** The inte
2ffb0 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 rface to the vir
2ffc0 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 tual-table mecha
2ffd0 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f nism defined abo
2ffe0 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 ve (back up.** t
2fff0 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 o a comment rema
30000 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 rkably similar t
30010 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 o this one) is c
30020 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 urrently conside
30030 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 red.** to be exp
30040 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 erimental. The
30050 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 interface might
30060 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 change in incomp
30070 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 atible ways..**
30080 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f If this is a pro
30090 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f blem for you, do
300a0 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 not use the int
300b0 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 erface at this t
300c0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 ime..**.** When
300d0 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c the virtual-tabl
300e0 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 e mechanism stab
300f0 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 ilizes, we will
30100 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 declare the.** i
30110 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 nterface fixed,
30120 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 support it indef
30130 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d initely, and rem
30140 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 ove this comment
30150 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 ..**.****** EXPE
30160 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 RIMENTAL - subje
30170 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 ct to change wit
30180 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a hout notice ****
30190 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f **********.*/../
301a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 *.** CAPI3REF: A
301b0 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 Handle To An Op
301c0 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38 30 30 7d en BLOB {H17800}
301d0 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 20 4b 45 59 <S30230>.** KEY
301e0 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e WORDS: {BLOB han
301f0 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c dle} {BLOB handl
30200 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 es}.**.** An ins
30210 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
30220 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 ject represents
30230 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 an open BLOB on
30240 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 which.** [sqlite
30250 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 3_blob_open | in
30260 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 cremental BLOB I
30270 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f /O] can be perfo
30280 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a 65 63 74 73 rmed..** Objects
30290 20 6f 66 20 74 68 69 73 20 74 79 70 65 20 61 72 of this type ar
302a0 65 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 e created by [sq
302b0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 lite3_blob_open(
302c0 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f )].** and destro
302d0 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f yed by [sqlite3_
302e0 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a blob_close()]..*
302f0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 * The [sqlite3_b
30300 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 lob_read()] and
30310 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 [sqlite3_blob_wr
30320 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ite()] interface
30330 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 s.** can be used
30340 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74 to read or writ
30350 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69 e small subsecti
30360 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e ons of the BLOB.
30370 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
30380 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 _blob_bytes()] i
30390 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
303a0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
303b0 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 0a BLOB in bytes..
303c0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
303d0 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 t sqlite3_blob s
303e0 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a qlite3_blob;../*
303f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 .** CAPI3REF: Op
30400 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e en A BLOB For In
30410 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 48 cremental I/O {H
30420 31 37 38 31 30 7d 20 3c 53 33 30 32 33 30 3e 0a 17810} <S30230>.
30430 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
30440 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 5b 42 faces opens a [B
30450 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 61 6e LOB handle | han
30460 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f 42 dle] to the BLOB
30470 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 located.** in r
30480 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 ow iRow, column
30490 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a zColumn, table z
304a0 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73 Table in databas
304b0 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 e zDb;.** in oth
304c0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73 61 er words, the sa
304d0 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77 6f 75 me BLOB that wou
304e0 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 20 62 ld be selected b
304f0 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a y:.**.** <pre>.*
30500 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f * SELECT zCo
30510 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 lumn FROM zDb.zT
30520 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f 77 69 able WHERE [rowi
30530 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f d] = iRow;.** </
30540 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a pre> {END}.**.**
30550 20 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 If the flags pa
30560 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a rameter is non-z
30570 65 72 6f 2c 20 74 68 65 20 74 68 65 20 42 4c 4f ero, the the BLO
30580 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 B is opened for
30590 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 read.** and writ
305a0 65 20 61 63 63 65 73 73 2e 20 49 66 20 69 74 20 e access. If it
305b0 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f is zero, the BLO
305c0 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 B is opened for
305d0 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a 0a read access..**.
305e0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 ** Note that the
305f0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 database name i
30600 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 s not the filena
30610 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 me that contains
30620 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
30630 20 62 75 74 20 72 61 74 68 65 72 20 74 68 65 20 but rather the
30640 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 symbolic name of
30650 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68 the database th
30660 61 74 0a 2a 2a 20 69 73 20 61 73 73 69 67 6e 65 at.** is assigne
30670 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 d when the datab
30680 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 ase is connected
30690 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e using [ATTACH].
306a0 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6d 61 69 6e .** For the main
306b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 database file,
306c0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d the database nam
306d0 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 e is "main"..**
306e0 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 2c For TEMP tables,
306f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 the database na
30700 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a me is "temp"..**
30710 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 .** On success,
30720 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 [SQLITE_OK] is r
30730 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 eturned and the
30740 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 new [BLOB handle
30750 5d 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 ] is written.**
30760 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65 to *ppBlob. Othe
30770 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 rwise an [error
30780 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
30790 64 20 61 6e 64 20 61 6e 79 20 76 61 6c 75 65 20 d and any value
307a0 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 written.** to *p
307b0 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 6e 6f 74 pBlob should not
307c0 20 62 65 20 75 73 65 64 20 62 79 20 74 68 65 20 be used by the
307d0 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68 69 73 20 caller..** This
307e0 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68 function sets th
307f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
30800 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f ection] error co
30810 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a de and message.*
30820 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 * accessible via
30830 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
30840 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
30850 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 3_errmsg()]..**.
30860 2a 2a 20 49 66 20 74 68 65 20 72 6f 77 20 74 68 ** If the row th
30870 61 74 20 61 20 42 4c 4f 42 20 68 61 6e 64 6c 65 at a BLOB handle
30880 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 6d 6f points to is mo
30890 64 69 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20 dified by an.**
308a0 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54 [UPDATE], [DELET
308b0 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 43 4f E], or by [ON CO
308c0 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d 65 66 66 NFLICT] side-eff
308d0 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ects.** then the
308e0 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 BLOB handle is
308f0 6d 61 72 6b 65 64 20 61 73 20 22 65 78 70 69 72 marked as "expir
30900 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 ed"..** This is
30910 74 72 75 65 20 69 66 20 61 6e 79 20 63 6f 6c 75 true if any colu
30920 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77 20 69 73 mn of the row is
30930 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 61 changed, even a
30940 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72 column.** other
30950 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 74 68 than the one th
30960 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 e BLOB handle is
30970 20 6f 70 65 6e 20 6f 6e 2e 0a 2a 2a 20 43 61 6c open on..** Cal
30980 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 ls to [sqlite3_b
30990 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 lob_read()] and
309a0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 [sqlite3_blob_wr
309b0 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 ite()] for.** a
309c0 65 78 70 69 72 65 64 20 42 4c 4f 42 20 68 61 6e expired BLOB han
309d0 64 6c 65 20 66 61 69 6c 20 77 69 74 68 20 61 6e dle fail with an
309e0 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 return code of
309f0 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a [SQLITE_ABORT]..
30a00 2a 2a 20 43 68 61 6e 67 65 73 20 77 72 69 74 74 ** Changes writt
30a10 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 en into a BLOB p
30a20 72 69 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 rior to the BLOB
30a30 20 65 78 70 69 72 69 6e 67 20 61 72 65 20 6e 6f expiring are no
30a40 74 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 20 62 79 t.** rollback by
30a50 20 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20 the expiration
30a60 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 of the BLOB. Su
30a70 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 ch changes will
30a80 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f eventually.** co
30a90 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72 61 6e mmit if the tran
30aa0 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 saction continue
30ab0 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e s to completion.
30ac0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
30ad0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 31 33 5d nts:.** [H17813]
30ae0 20 5b 48 31 37 38 31 34 5d 20 5b 48 31 37 38 31 [H17814] [H1781
30af0 36 5d 20 5b 48 31 37 38 31 39 5d 20 5b 48 31 37 6] [H17819] [H17
30b00 38 32 31 5d 20 5b 48 31 37 38 32 34 5d 0a 2a 2f 821] [H17824].*/
30b10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f .int sqlite3_blo
30b20 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 b_open(. sqlite
30b30 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 3*,. const char
30b40 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 *zDb,. const c
30b50 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 har *zTable,. c
30b60 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 onst char *zColu
30b70 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e mn,. sqlite3_in
30b80 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 t64 iRow,. int
30b90 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 flags,. sqlite3
30ba0 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 _blob **ppBlob.)
30bb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
30bc0 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 F: Close A BLOB
30bd0 48 61 6e 64 6c 65 20 7b 48 31 37 38 33 30 7d 20 Handle {H17830}
30be0 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 43 <S30230>.**.** C
30bf0 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 loses an open [B
30c00 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a LOB handle]..**.
30c10 2a 2a 20 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f ** Closing a BLO
30c20 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 B shall cause th
30c30 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 e current transa
30c40 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a ction to commit.
30c50 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20 ** if there are
30c60 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 no other BLOBs,
30c70 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 no pending prepa
30c80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 red statements,
30c90 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 and the.** datab
30ca0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
30cb0 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 s in [autocommit
30cc0 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 49 66 20 61 6e mode]..** If an
30cd0 79 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 y writes were ma
30ce0 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 de to the BLOB,
30cf0 74 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 they might be he
30d00 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 ld in cache.** u
30d10 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f ntil the close o
30d20 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 peration if they
30d30 20 77 69 6c 6c 20 66 69 74 2e 20 7b 45 4e 44 7d will fit. {END}
30d40 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 74 .**.** Closing t
30d50 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f he BLOB often fo
30d60 72 63 65 73 20 74 68 65 20 63 68 61 6e 67 65 73 rces the changes
30d70 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b 20 .** out to disk
30d80 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 20 49 2f and so if any I/
30d90 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 72 2c 20 O errors occur,
30da0 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 they will likely
30db0 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74 68 65 occur.** at the
30dc0 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 42 time when the B
30dd0 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 LOB is closed.
30de0 7b 48 31 37 38 33 33 7d 20 41 6e 79 20 65 72 72 {H17833} Any err
30df0 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 64 ors that occur d
30e00 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 uring.** closing
30e10 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 61 73 are reported as
30e20 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 a non-zero retu
30e30 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 rn value..**.**
30e40 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 The BLOB is clos
30e50 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c ed unconditional
30e60 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74 68 69 ly. Even if thi
30e70 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
30e80 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f s.** an error co
30e90 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20 de, the BLOB is
30ea0 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 0a 2a 2a still closed..**
30eb0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
30ec0 3a 0a 2a 2a 20 5b 48 31 37 38 33 33 5d 20 5b 48 :.** [H17833] [H
30ed0 31 37 38 33 36 5d 20 5b 48 31 37 38 33 39 5d 0a 17836] [H17839].
30ee0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
30ef0 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 lob_close(sqlite
30f00 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 3_blob *);../*.*
30f10 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 75 * CAPI3REF: Retu
30f20 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41 rn The Size Of A
30f30 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 48 31 37 n Open BLOB {H17
30f40 38 34 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 840} <S30230>.**
30f50 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20 .** Returns the
30f60 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66 size in bytes of
30f70 20 74 68 65 20 42 4c 4f 42 20 61 63 63 65 73 73 the BLOB access
30f80 69 62 6c 65 20 76 69 61 20 74 68 65 20 6f 70 65 ible via the ope
30f90 6e 0a 2a 2a 20 5b 5d 42 4c 4f 42 20 68 61 6e 64 n.** []BLOB hand
30fa0 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20 le] in its only
30fb0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
30fc0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
30fd0 20 5b 48 31 37 38 34 33 5d 0a 2a 2f 0a 69 6e 74 [H17843].*/.int
30fe0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 sqlite3_blob_by
30ff0 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 tes(sqlite3_blob
31000 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 *);../*.** CAPI
31010 33 52 45 46 3a 20 52 65 61 64 20 44 61 74 61 20 3REF: Read Data
31020 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 From A BLOB Incr
31030 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 35 ementally {H1785
31040 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 0} <S30230>.**.*
31050 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
31060 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 is used to read
31070 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 data from an ope
31080 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 n [BLOB handle]
31090 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 into a.** caller
310a0 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 -supplied buffer
310b0 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 . N bytes of dat
310c0 61 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 a are copied int
310d0 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 o buffer Z.** fr
310e0 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 om the open BLOB
310f0 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 , starting at of
31100 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a fset iOffset..**
31110 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f .** If offset iO
31120 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 ffset is less th
31130 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 an N bytes from
31140 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 the end of the B
31150 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f LOB,.** [SQLITE_
31160 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e ERROR] is return
31170 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 ed and no data i
31180 73 20 72 65 61 64 2e 20 20 49 66 20 4e 20 6f 72 s read. If N or
31190 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c iOffset is.** l
311a0 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b ess than zero, [
311b0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 SQLITE_ERROR] is
311c0 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f returned and no
311d0 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a data is read..*
311e0 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d 70 74 20 *.** An attempt
311f0 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 61 6e 20 to read from an
31200 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 expired [BLOB ha
31210 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 ndle] fails with
31220 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 an.** error cod
31230 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f e of [SQLITE_ABO
31240 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 RT]..**.** On su
31250 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b ccess, SQLITE_OK
31260 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
31270 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 5b Otherwise, an [
31280 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 error code] or a
31290 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f n [extended erro
312a0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
312b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ned..**.** Requi
312c0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 rements:.** [H17
312d0 38 35 33 5d 20 5b 48 31 37 38 35 36 5d 20 5b 48 853] [H17856] [H
312e0 31 37 38 35 39 5d 20 5b 48 31 37 38 36 32 5d 20 17859] [H17862]
312f0 5b 48 31 37 38 36 33 5d 20 5b 48 31 37 38 36 35 [H17863] [H17865
31300 5d 20 5b 48 31 37 38 36 38 5d 0a 2a 2f 0a 69 6e ] [H17868].*/.in
31310 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 t sqlite3_blob_r
31320 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ead(sqlite3_blob
31330 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 *, void *Z, int
31340 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 N, int iOffset)
31350 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
31360 46 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e F: Write Data In
31370 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d to A BLOB Increm
31380 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 37 30 7d entally {H17870}
31390 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 <S30230>.**.**
313a0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 This function is
313b0 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 used to write d
313c0 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e ata into an open
313d0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 [BLOB handle] f
313e0 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d rom a.** caller-
313f0 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e supplied buffer.
31400 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 N bytes of data
31410 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d are copied from
31420 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a the buffer Z.**
31430 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 into the open B
31440 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 LOB, starting at
31450 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e offset iOffset.
31460 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 42 .**.** If the [B
31470 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 LOB handle] pass
31480 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ed as the first
31490 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 argument was not
314a0 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 opened for.** w
314b0 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 riting (the flag
314c0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b s parameter to [
314d0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
314e0 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a n()] was zero),.
314f0 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e ** this function
31500 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
31510 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a _READONLY]..**.*
31520 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
31530 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 may only modify
31540 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 the contents of
31550 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a the BLOB; it is.
31560 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 ** not possible
31570 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 to increase the
31580 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 size of a BLOB u
31590 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a sing this API..*
315a0 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 * If offset iOff
315b0 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e set is less than
315c0 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 N bytes from th
315d0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f e end of the BLO
315e0 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 B,.** [SQLITE_ER
315f0 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ROR] is returned
31600 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 and no data is
31610 77 72 69 74 74 65 6e 2e 20 20 49 66 20 4e 20 69 written. If N i
31620 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a s.** less than z
31630 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f ero [SQLITE_ERRO
31640 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 R] is returned a
31650 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 nd no data is wr
31660 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 itten..**.** An
31670 61 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 attempt to write
31680 20 74 6f 20 61 6e 20 65 78 70 69 72 65 64 20 5b to an expired [
31690 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 BLOB handle] fai
316a0 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 ls with an.** er
316b0 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c ror code of [SQL
316c0 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20 57 72 69 ITE_ABORT]. Wri
316d0 74 65 73 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 tes to the BLOB
316e0 74 68 61 74 20 6f 63 63 75 72 72 65 64 0a 2a 2a that occurred.**
316f0 20 62 65 66 6f 72 65 20 74 68 65 20 5b 42 4c 4f before the [BLO
31700 42 20 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 65 B handle] expire
31710 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 64 d are not rolled
31720 20 62 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a 20 back by the.**
31730 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 expiration of th
31740 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67 68 e handle, though
31750 20 6f 66 20 63 6f 75 72 73 65 20 74 68 6f 73 65 of course those
31760 20 63 68 61 6e 67 65 73 20 6d 69 67 68 74 0a 2a changes might.*
31770 2a 20 68 61 76 65 20 62 65 65 6e 20 6f 76 65 72 * have been over
31780 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 73 written by the s
31790 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 65 78 tatement that ex
317a0 70 69 72 65 64 20 74 68 65 20 42 4c 4f 42 20 68 pired the BLOB h
317b0 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 6f andle.** or by o
317c0 74 68 65 72 20 69 6e 64 65 70 65 6e 64 65 6e 74 ther independent
317d0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a statements..**.
317e0 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 ** On success, S
317f0 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 QLITE_OK is retu
31800 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 rned..** Otherwi
31810 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f 72 20 63 se, an [error c
31820 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 ode] or an [exte
31830 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d nded error code]
31840 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
31850 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
31860 3a 0a 2a 2a 20 5b 48 31 37 38 37 33 5d 20 5b 48 :.** [H17873] [H
31870 31 37 38 37 34 5d 20 5b 48 31 37 38 37 35 5d 20 17874] [H17875]
31880 5b 48 31 37 38 37 36 5d 20 5b 48 31 37 38 37 37 [H17876] [H17877
31890 5d 20 5b 48 31 37 38 37 39 5d 20 5b 48 31 37 38 ] [H17879] [H178
318a0 38 32 5d 20 5b 48 31 37 38 38 35 5d 0a 2a 2a 20 82] [H17885].**
318b0 5b 48 31 37 38 38 38 5d 0a 2a 2f 0a 69 6e 74 20 [H17888].*/.int
318c0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 sqlite3_blob_wri
318d0 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 te(sqlite3_blob
318e0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a *, const void *z
318f0 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 , int n, int iOf
31900 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 fset);../*.** CA
31910 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 PI3REF: Virtual
31920 46 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 File System Obje
31930 63 74 73 20 7b 48 31 31 32 30 30 7d 20 3c 53 32 cts {H11200} <S2
31940 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 0100>.**.** A vi
31950 72 74 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d rtual filesystem
31960 20 28 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71 (VFS) is an [sq
31970 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
31980 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 t.** that SQLite
31990 20 75 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63 uses to interac
319a0 74 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e t.** with the un
319b0 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 derlying operati
319c0 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 ng system. Most
319d0 20 53 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63 SQLite builds c
319e0 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 ome with a.** si
319f0 6e 67 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53 ngle default VFS
31a00 20 74 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 that is appropr
31a10 69 61 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73 iate for the hos
31a20 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e t computer..** N
31a30 65 77 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 ew VFSes can be
31a40 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 65 registered and e
31a50 78 69 73 74 69 6e 67 20 56 46 53 65 73 20 63 61 xisting VFSes ca
31a60 6e 20 62 65 20 75 6e 72 65 67 69 73 74 65 72 65 n be unregistere
31a70 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 d..** The follow
31a80 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 61 ing interfaces a
31a90 72 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a re provided..**.
31aa0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 ** The sqlite3_v
31ab0 66 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 fs_find() interf
31ac0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
31ad0 69 6e 74 65 72 20 74 6f 20 61 20 56 46 53 20 67 inter to a VFS g
31ae0 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a iven its name..*
31af0 2a 20 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 * Names are case
31b00 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 4e sensitive..** N
31b10 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 ames are zero-te
31b20 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
31b30 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 trings..** If th
31b40 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c ere is no match,
31b50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
31b60 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 is returned..**
31b70 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e If zVfsName is N
31b80 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 ULL then the def
31b90 61 75 6c 74 20 56 46 53 20 69 73 20 72 65 74 75 ault VFS is retu
31ba0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 rned..**.** New
31bb0 56 46 53 65 73 20 61 72 65 20 72 65 67 69 73 74 VFSes are regist
31bc0 65 72 65 64 20 77 69 74 68 20 73 71 6c 69 74 65 ered with sqlite
31bd0 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 3_vfs_register()
31be0 2e 0a 2a 2a 20 45 61 63 68 20 6e 65 77 20 56 46 ..** Each new VF
31bf0 53 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 S becomes the de
31c00 66 61 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 fault VFS if the
31c10 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 makeDflt flag i
31c20 73 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 s set..** The sa
31c30 6d 65 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 me VFS can be re
31c40 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c gistered multipl
31c50 65 20 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 e times without
31c60 69 6e 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 injury..** To ma
31c70 6b 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56 ke an existing V
31c80 46 53 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61 FS into the defa
31c90 75 6c 74 20 56 46 53 2c 20 72 65 67 69 73 74 65 ult VFS, registe
31ca0 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 r it again.** wi
31cb0 74 68 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 th the makeDflt
31cc0 66 6c 61 67 20 73 65 74 2e 20 20 49 66 20 74 77 flag set. If tw
31cd0 6f 20 64 69 66 66 65 72 65 6e 74 20 56 46 53 65 o different VFSe
31ce0 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 s with the.** sa
31cf0 6d 65 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69 me name are regi
31d00 73 74 65 72 65 64 2c 20 74 68 65 20 62 65 68 61 stered, the beha
31d10 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
31d20 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 d. If a.** VFS
31d30 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69 is registered wi
31d40 74 68 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69 th a name that i
31d50 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 s NULL or an emp
31d60 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 ty string,.** th
31d70 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
31d80 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
31d90 0a 2a 2a 20 55 6e 72 65 67 69 73 74 65 72 20 61 .** Unregister a
31da0 20 56 46 53 20 77 69 74 68 20 74 68 65 20 73 71 VFS with the sq
31db0 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 lite3_vfs_unregi
31dc0 73 74 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 ster() interface
31dd0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64 65 66 61 ..** If the defa
31de0 75 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 ult VFS is unreg
31df0 69 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 istered, another
31e00 20 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 VFS is chosen a
31e10 73 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 s.** the default
31e20 2e 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f . The choice fo
31e30 72 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 r the new VFS is
31e40 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a arbitrary..**.*
31e50 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
31e60 2a 2a 20 5b 48 31 31 32 30 33 5d 20 5b 48 31 31 ** [H11203] [H11
31e70 32 30 36 5d 20 5b 48 31 31 32 30 39 5d 20 5b 48 206] [H11209] [H
31e80 31 31 32 31 32 5d 20 5b 48 31 31 32 31 35 5d 20 11212] [H11215]
31e90 5b 48 31 31 32 31 38 5d 0a 2a 2f 0a 73 71 6c 69 [H11218].*/.sqli
31ea0 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 te3_vfs *sqlite3
31eb0 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 _vfs_find(const
31ec0 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b char *zVfsName);
31ed0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 .int sqlite3_vfs
31ee0 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 _register(sqlite
31ef0 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 3_vfs*, int make
31f00 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 Dflt);.int sqlit
31f10 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 e3_vfs_unregiste
31f20 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b r(sqlite3_vfs*);
31f30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
31f40 3a 20 4d 75 74 65 78 65 73 20 7b 48 31 37 30 30 : Mutexes {H1700
31f50 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 0} <S20000>.**.*
31f60 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 * The SQLite cor
31f70 65 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 e uses these rou
31f80 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 tines for thread
31f90 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 .** synchronizat
31fa0 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74 68 65 79 ion. Though they
31fb0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f are intended fo
31fc0 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 r internal.** us
31fd0 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 e by SQLite, cod
31fe0 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 e that links aga
31ff0 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a inst SQLite is.*
32000 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 * permitted to u
32010 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 se any of these
32020 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
32030 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 The SQLite sourc
32040 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 e code contains
32050 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 multiple impleme
32060 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 ntations.** of t
32070 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69 hese mutex routi
32080 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 nes. An appropr
32090 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 iate implementat
320a0 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 ion.** is select
320b0 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ed automatically
320c0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 at compile-time
320d0 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 . The following
320e0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
320f0 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c ons are availabl
32100 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 e in the SQLite
32110 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e core:.**.** <ul>
32120 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 .** <li> SQLIT
32130 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c E_MUTEX_OS2.** <
32140 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 li> SQLITE_MUT
32150 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c EX_PTHREAD.** <l
32160 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 i> SQLITE_MUTE
32170 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 X_W32.** <li>
32180 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f SQLITE_MUTEX_NOO
32190 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a P.** </ul>.**.**
321a0 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 The SQLITE_MUTE
321b0 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 X_NOOP implement
321c0 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f ation is a set o
321d0 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 f routines.** th
321e0 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 at does no real
321f0 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 locking and is a
32200 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 ppropriate for u
32210 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c se in.** a singl
32220 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 e-threaded appli
32230 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c cation. The SQL
32240 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a ITE_MUTEX_OS2,.*
32250 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 * SQLITE_MUTEX_P
32260 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 THREAD, and SQLI
32270 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 TE_MUTEX_W32 imp
32280 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 lementations.**
32290 61 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 are appropriate
322a0 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c for use on OS/2,
322b0 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f Unix, and Windo
322c0 77 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c ws..**.** If SQL
322d0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
322e0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f with the SQLITE_
322f0 4d 55 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 MUTEX_APPDEF pre
32300 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 processor.** mac
32310 72 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 ro defined (with
32320 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 "-DSQLITE_MUTEX
32330 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 _APPDEF=1"), the
32340 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d n no mutex.** im
32350 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 plementation is
32360 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 included with th
32370 65 20 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68 e library. In th
32380 69 73 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 is case the.** a
32390 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
323a0 73 75 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 supply a custom
323b0 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 mutex implementa
323c0 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a tion using the.*
323d0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
323e0 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f _MUTEX] option o
323f0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f f the sqlite3_co
32400 6e 66 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a nfig() function.
32410 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e ** before callin
32420 67 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 g sqlite3_initia
32430 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 lize() or any ot
32440 68 65 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74 her public sqlit
32450 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 e3_.** function
32460 74 68 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 that calls sqlit
32470 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e e3_initialize().
32480 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 31 7d 20 .**.** {H17011}
32490 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 The sqlite3_mute
324a0 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e x_alloc() routin
324b0 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 e allocates a ne
324c0 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 w.** mutex and r
324d0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
324e0 20 74 6f 20 69 74 2e 20 7b 48 31 37 30 31 32 7d to it. {H17012}
324f0 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e If it returns N
32500 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e ULL.** that mean
32510 73 20 74 68 61 74 20 61 20 6d 75 74 65 78 20 63 s that a mutex c
32520 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f ould not be allo
32530 63 61 74 65 64 2e 20 7b 48 31 37 30 31 33 7d 20 cated. {H17013}
32540 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 SQLite.** will u
32550 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 nwind its stack
32560 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 and return an er
32570 72 6f 72 2e 20 7b 48 31 37 30 31 34 7d 20 54 68 ror. {H17014} Th
32580 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f e argument.** to
32590 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 sqlite3_mutex_a
325a0 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 lloc() is one of
325b0 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 these integer c
325c0 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 onstants:.**.**
325d0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 <ul>.** <li> SQ
325e0 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a LITE_MUTEX_FAST.
325f0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
32600 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a MUTEX_RECURSIVE.
32610 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
32620 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 MUTEX_STATIC_MAS
32630 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c TER.** <li> SQL
32640 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
32650 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 _MEM.** <li> SQ
32660 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
32670 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 C_MEM2.** <li>
32680 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
32690 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e TIC_PRNG.** <li>
326a0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 SQLITE_MUTEX_S
326b0 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 TATIC_LRU.** <li
326c0 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f > SQLITE_MUTEX_
326d0 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c STATIC_LRU2.** <
326e0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 /ul>.**.** {H170
326f0 31 35 7d 20 54 68 65 20 66 69 72 73 74 20 74 77 15} The first tw
32700 6f 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 o constants caus
32710 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f e sqlite3_mutex_
32720 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 alloc() to creat
32730 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 e.** a new mutex
32740 2e 20 20 54 68 65 20 6e 65 77 20 6d 75 74 65 78 . The new mutex
32750 20 69 73 20 72 65 63 75 72 73 69 76 65 20 77 68 is recursive wh
32760 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f en SQLITE_MUTEX_
32770 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 RECURSIVE.** is
32780 75 73 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 used but not nec
32790 65 73 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e essarily so when
327a0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 SQLITE_MUTEX_FA
327b0 53 54 20 69 73 20 75 73 65 64 2e 20 7b 45 4e 44 ST is used. {END
327c0 7d 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 }.** The mutex i
327d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f mplementation do
327e0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d es not need to m
327f0 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f ake a distinctio
32800 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c n.** between SQL
32810 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 ITE_MUTEX_RECURS
32820 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d IVE and SQLITE_M
32830 55 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 UTEX_FAST if it
32840 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 does.** not want
32850 20 74 6f 2e 20 20 7b 48 31 37 30 31 36 7d 20 42 to. {H17016} B
32860 75 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f ut SQLite will o
32870 6e 6c 79 20 72 65 71 75 65 73 74 20 61 20 72 65 nly request a re
32880 63 75 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e cursive mutex in
32890 0a 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 .** cases where
328a0 69 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 it really needs
328b0 6f 6e 65 2e 20 20 7b 45 4e 44 7d 20 49 66 20 61 one. {END} If a
328c0 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 faster non-recu
328d0 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 rsive mutex.** i
328e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 mplementation is
328f0 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 available on th
32900 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c e host platform,
32910 20 74 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 the mutex subsy
32920 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 stem.** might re
32930 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 turn such a mute
32940 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f x in response to
32950 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 SQLITE_MUTEX_FA
32960 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 ST..**.** {H1701
32970 37 7d 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 7} The other all
32980 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 owed parameters
32990 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 to sqlite3_mutex
329a0 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65 _alloc() each re
329b0 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 turn.** a pointe
329c0 72 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 r to a static pr
329d0 65 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e eexisting mutex.
329e0 20 7b 45 4e 44 7d 20 20 46 6f 75 72 20 73 74 61 {END} Four sta
329f0 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 0a tic mutexes are.
32a00 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65 20 63 ** used by the c
32a10 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f urrent version o
32a20 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74 75 72 f SQLite. Futur
32a30 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
32a40 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20 Lite.** may add
32a50 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 additional stati
32a60 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74 61 74 c mutexes. Stat
32a70 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 20 66 ic mutexes are f
32a80 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 or internal.** u
32a90 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c se by SQLite onl
32aa0 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 y. Applications
32ab0 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 that use SQLite
32ac0 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 0a mutexes should.
32ad0 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68 65 20 ** use only the
32ae0 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 dynamic mutexes
32af0 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 49 returned by SQLI
32b00 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f 72 TE_MUTEX_FAST or
32b10 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 .** SQLITE_MUTEX
32b20 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a _RECURSIVE..**.*
32b30 2a 20 7b 48 31 37 30 31 38 7d 20 4e 6f 74 65 20 * {H17018} Note
32b40 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 that if one of t
32b50 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 he dynamic mutex
32b60 20 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c parameters (SQL
32b70 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a ITE_MUTEX_FAST.*
32b80 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 * or SQLITE_MUTE
32b90 58 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 20 X_RECURSIVE) is
32ba0 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 used then sqlite
32bb0 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 3_mutex_alloc().
32bc0 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 ** returns a dif
32bd0 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 ferent mutex on
32be0 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 7b 48 31 every call. {H1
32bf0 37 30 33 34 7d 20 42 75 74 20 66 6f 72 20 74 68 7034} But for th
32c00 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 e static.** mute
32c10 78 20 74 79 70 65 73 2c 20 74 68 65 20 73 61 6d x types, the sam
32c20 65 20 6d 75 74 65 78 20 69 73 20 72 65 74 75 72 e mutex is retur
32c30 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63 61 6c ned on every cal
32c40 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 l that has.** th
32c50 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 e same type numb
32c60 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 er..**.** {H1701
32c70 39 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 9} The sqlite3_m
32c80 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 utex_free() rout
32c90 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 ine deallocates
32ca0 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 a previously.**
32cb0 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 allocated dynami
32cc0 63 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 30 c mutex. {H17020
32cd0 7d 20 53 51 4c 69 74 65 20 69 73 20 63 61 72 65 } SQLite is care
32ce0 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 ful to deallocat
32cf0 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d e every.** dynam
32d00 69 63 20 6d 75 74 65 78 20 74 68 61 74 20 69 74 ic mutex that it
32d10 20 61 6c 6c 6f 63 61 74 65 73 2e 20 7b 41 31 37 allocates. {A17
32d20 30 32 31 7d 20 54 68 65 20 64 79 6e 61 6d 69 63 021} The dynamic
32d30 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f mutexes must no
32d40 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 t be in.** use w
32d50 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 hen they are dea
32d60 6c 6c 6f 63 61 74 65 64 2e 20 7b 41 31 37 30 32 llocated. {A1702
32d70 32 7d 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 2} Attempting to
32d80 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 deallocate a st
32d90 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 atic.** mutex re
32da0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e sults in undefin
32db0 65 64 20 62 65 68 61 76 69 6f 72 2e 20 7b 48 31 ed behavior. {H1
32dc0 37 30 32 33 7d 20 53 51 4c 69 74 65 20 6e 65 76 7023} SQLite nev
32dd0 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a er deallocates.*
32de0 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 * a static mutex
32df0 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 . {END}.**.** Th
32e00 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f e sqlite3_mutex_
32e10 65 6e 74 65 72 28 29 20 61 6e 64 20 73 71 6c 69 enter() and sqli
32e20 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 te3_mutex_try()
32e30 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 routines attempt
32e40 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61 20 6d .** to enter a m
32e50 75 74 65 78 2e 20 7b 48 31 37 30 32 34 7d 20 49 utex. {H17024} I
32e60 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 f another thread
32e70 20 69 73 20 61 6c 72 65 61 64 79 20 77 69 74 68 is already with
32e80 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a in the mutex,.**
32e90 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 sqlite3_mutex_e
32ea0 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63 nter() will bloc
32eb0 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 k and sqlite3_mu
32ec0 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72 tex_try() will r
32ed0 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f eturn.** SQLITE_
32ee0 42 55 53 59 2e 20 7b 48 31 37 30 32 35 7d 20 20 BUSY. {H17025}
32ef0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 The sqlite3_mute
32f00 78 5f 74 72 79 28 29 20 69 6e 74 65 72 66 61 63 x_try() interfac
32f10 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 e returns [SQLIT
32f20 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 E_OK].** upon su
32f30 63 63 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 ccessful entry.
32f40 20 7b 48 31 37 30 32 36 7d 20 4d 75 74 65 78 65 {H17026} Mutexe
32f50 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a s created using.
32f60 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ** SQLITE_MUTEX_
32f70 52 45 43 55 52 53 49 56 45 20 63 61 6e 20 62 65 RECURSIVE can be
32f80 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c entered multipl
32f90 65 20 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 e times by the s
32fa0 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20 7b ame thread..** {
32fb0 48 31 37 30 32 37 7d 20 49 6e 20 73 75 63 68 20 H17027} In such
32fc0 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 cases the,.** mu
32fd0 74 65 78 20 6d 75 73 74 20 62 65 20 65 78 69 74 tex must be exit
32fe0 65 64 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 ed an equal numb
32ff0 65 72 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f er of times befo
33000 72 65 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 re another threa
33010 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 20 d.** can enter.
33020 20 7b 41 31 37 30 32 38 7d 20 49 66 20 74 68 65 {A17028} If the
33030 20 73 61 6d 65 20 74 68 72 65 61 64 20 74 72 69 same thread tri
33040 65 73 20 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 es to enter any
33050 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 other.** kind of
33060 20 6d 75 74 65 78 20 6d 6f 72 65 20 74 68 61 6e mutex more than
33070 20 6f 6e 63 65 2c 20 74 68 65 20 62 65 68 61 76 once, the behav
33080 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
33090 2e 0a 2a 2a 20 7b 48 31 37 30 32 39 7d 20 53 51 ..** {H17029} SQ
330a0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 Lite will never
330b0 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 exhibit.** such
330c0 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 behavior in its
330d0 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 own use of mutex
330e0 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73 es..**.** Some s
330f0 79 73 74 65 6d 73 20 28 66 6f 72 20 65 78 61 6d ystems (for exam
33100 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 ple, Windows 95)
33110 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 do not support
33120 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a the operation.**
33130 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 implemented by
33140 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 sqlite3_mutex_tr
33150 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 y(). On those s
33160 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f ystems, sqlite3_
33170 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 mutex_try().** w
33180 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 ill always retur
33190 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 n SQLITE_BUSY.
331a0 7b 48 31 37 30 33 30 7d 20 54 68 65 20 53 51 4c {H17030} The SQL
331b0 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 ite core only ev
331c0 65 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 er uses.** sqlit
331d0 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 61 e3_mutex_try() a
331e0 73 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f s an optimizatio
331f0 6e 20 73 6f 20 74 68 69 73 20 69 73 20 61 63 63 n so this is acc
33200 65 70 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 eptable behavior
33210 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 33 31 7d ..**.** {H17031}
33220 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 The sqlite3_mut
33230 65 78 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69 ex_leave() routi
33240 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74 65 78 ne exits a mutex
33250 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 that was.** pre
33260 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20 viously entered
33270 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 by the same thre
33280 61 64 2e 20 20 7b 41 31 37 30 33 32 7d 20 54 68 ad. {A17032} Th
33290 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 e behavior.** is
332a0 20 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 undefined if th
332b0 65 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 e mutex is not c
332c0 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 urrently entered
332d0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 by the.** calli
332e0 6e 67 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 ng thread or is
332f0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c not currently al
33300 6c 6f 63 61 74 65 64 2e 20 20 7b 48 31 37 30 33 located. {H1703
33310 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 3} SQLite will.*
33320 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65 * never do eithe
33330 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 r. {END}.**.** I
33340 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 f the argument t
33350 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f o sqlite3_mutex_
33360 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 65 33 enter(), sqlite3
33370 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 6f 72 _mutex_try(), or
33380 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 .** sqlite3_mute
33390 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61 20 4e x_leave() is a N
333a0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 ULL pointer, the
333b0 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f 75 74 n all three rout
333c0 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 20 61 ines.** behave a
333d0 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 s no-ops..**.**
333e0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
333f0 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d e3_mutex_held()]
33400 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 and [sqlite3_mu
33410 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a tex_notheld()]..
33420 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 */.sqlite3_mutex
33430 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f *sqlite3_mutex_
33440 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 alloc(int);.void
33450 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 sqlite3_mutex_f
33460 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 ree(sqlite3_mute
33470 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 x*);.void sqlite
33480 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71 3_mutex_enter(sq
33490 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 lite3_mutex*);.i
334a0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 nt sqlite3_mutex
334b0 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 _try(sqlite3_mut
334c0 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 ex*);.void sqlit
334d0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 e3_mutex_leave(s
334e0 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a qlite3_mutex*);.
334f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
33500 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20 4f Mutex Methods O
33510 62 6a 65 63 74 20 7b 48 31 37 31 32 30 7d 20 3c bject {H17120} <
33520 53 32 30 31 33 30 3e 0a 2a 2a 20 45 58 50 45 52 S20130>.** EXPER
33530 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e IMENTAL.**.** An
33540 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
33550 73 20 73 74 72 75 63 74 75 72 65 20 64 65 66 69 s structure defi
33560 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 nes the low-leve
33570 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 l routines.** us
33580 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 ed to allocate a
33590 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a nd use mutexes..
335a0 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 **.** Usually, t
335b0 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 he default mutex
335c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
335d0 20 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c provided by SQL
335e0 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 ite are.** suffi
335f0 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 cient, however t
33600 68 65 20 75 73 65 72 20 68 61 73 20 74 68 65 20 he user has the
33610 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 option of substi
33620 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a tuting a custom.
33630 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
33640 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 n for specialize
33650 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 d deployments or
33660 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69 systems for whi
33670 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 ch SQLite.** doe
33680 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 s not provide a
33690 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 suitable impleme
336a0 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 ntation. In this
336b0 20 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a case, the user.
336c0 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 70 ** creates and p
336d0 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 opulates an inst
336e0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 ance of this str
336f0 75 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a ucture to pass.*
33700 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e * to sqlite3_con
33710 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 fig() along with
33720 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e the [SQLITE_CON
33730 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f FIG_MUTEX] optio
33740 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c n..** Additional
33750 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 ly, an instance
33760 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 of this structur
33770 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 e can be used as
33780 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 an.** output va
33790 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72 riable when quer
337a0 79 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20 ying the system
337b0 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 for the current
337c0 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 mutex.** impleme
337d0 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 ntation, using t
337e0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 he [SQLITE_CONFI
337f0 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 G_GETMUTEX] opti
33800 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d on..**.** The xM
33810 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 utexInit method
33820 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 defined by this
33830 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 structure is inv
33840 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 oked as.** part
33850 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61 of system initia
33860 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20 lization by the
33870 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
33880 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a ze() function..*
33890 2a 20 7b 48 31 37 30 30 31 7d 20 54 68 65 20 78 * {H17001} The x
338a0 4d 75 74 65 78 49 6e 69 74 20 72 6f 75 74 69 6e MutexInit routin
338b0 65 20 73 68 61 6c 6c 20 62 65 20 63 61 6c 6c 65 e shall be calle
338c0 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 63 65 d by SQLite once
338d0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 65 66 66 for each.** eff
338e0 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 5b ective call to [
338f0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
33900 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ze()]..**.** The
33910 20 78 4d 75 74 65 78 45 6e 64 20 6d 65 74 68 6f xMutexEnd metho
33920 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 d defined by thi
33930 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69 s structure is i
33940 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 nvoked as.** par
33950 74 20 6f 66 20 73 79 73 74 65 6d 20 73 68 75 74 t of system shut
33960 64 6f 77 6e 20 62 79 20 74 68 65 20 73 71 6c 69 down by the sqli
33970 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 66 te3_shutdown() f
33980 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 unction. The.**
33990 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
339a0 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20 69 73 f this method is
339b0 20 65 78 70 65 63 74 65 64 20 74 6f 20 72 65 6c expected to rel
339c0 65 61 73 65 20 61 6c 6c 20 6f 75 74 73 74 61 6e ease all outstan
339d0 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 72 63 65 ding.** resource
339e0 73 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 s obtained by th
339f0 65 20 6d 75 74 65 78 20 6d 65 74 68 6f 64 73 20 e mutex methods
33a00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 implementation,
33a10 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 especially.** th
33a20 6f 73 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 ose obtained by
33a30 74 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d the xMutexInit m
33a40 65 74 68 6f 64 2e 20 7b 48 31 37 30 30 33 7d 20 ethod. {H17003}
33a50 54 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 0a The xMutexEnd().
33a60 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 ** interface sha
33a70 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 6f 6e ll be invoked on
33a80 63 65 20 66 6f 72 20 65 61 63 68 20 63 61 6c 6c ce for each call
33a90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 to [sqlite3_shu
33aa0 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 tdown()]..**.**
33ab0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 73 65 The remaining se
33ac0 76 65 6e 20 6d 65 74 68 6f 64 73 20 64 65 66 69 ven methods defi
33ad0 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75 ned by this stru
33ae0 63 74 75 72 65 20 28 78 4d 75 74 65 78 41 6c 6c cture (xMutexAll
33af0 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 46 72 65 oc,.** xMutexFre
33b00 65 2c 20 78 4d 75 74 65 78 45 6e 74 65 72 2c 20 e, xMutexEnter,
33b10 78 4d 75 74 65 78 54 72 79 2c 20 78 4d 75 74 65 xMutexTry, xMute
33b20 78 4c 65 61 76 65 2c 20 78 4d 75 74 65 78 48 65 xLeave, xMutexHe
33b30 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 74 65 78 ld and.** xMutex
33b40 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c 65 6d 65 Notheld) impleme
33b50 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 nt the following
33b60 20 69 6e 74 65 72 66 61 63 65 73 20 28 72 65 73 interfaces (res
33b70 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a 2a pectively):.**.*
33b80 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e * <ul>.** <li>
33b90 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 [sqlite3_mutex
33ba0 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e 0a _alloc()] </li>.
33bb0 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 ** <li> [sqli
33bc0 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 te3_mutex_free()
33bd0 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 ] </li>.** <li
33be0 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 > [sqlite3_mute
33bf0 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f 6c 69 3e x_enter()] </li>
33c00 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c .** <li> [sql
33c10 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 ite3_mutex_try()
33c20 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 ] </li>.** <li
33c30 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 > [sqlite3_mute
33c40 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f 6c 69 3e x_leave()] </li>
33c50 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c .** <li> [sql
33c60 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 ite3_mutex_held(
33c70 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c )] </li>.** <l
33c80 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 i> [sqlite3_mut
33c90 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 20 3c 2f ex_notheld()] </
33ca0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a li>.** </ul>.**.
33cb0 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 ** The only diff
33cc0 65 72 65 6e 63 65 20 69 73 20 74 68 61 74 20 74 erence is that t
33cd0 68 65 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 he public sqlite
33ce0 33 5f 58 58 58 20 66 75 6e 63 74 69 6f 6e 73 20 3_XXX functions
33cf0 65 6e 75 6d 65 72 61 74 65 64 0a 2a 2a 20 61 62 enumerated.** ab
33d00 6f 76 65 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e ove silently ign
33d10 6f 72 65 20 61 6e 79 20 69 6e 76 6f 63 61 74 69 ore any invocati
33d20 6f 6e 73 20 74 68 61 74 20 70 61 73 73 20 61 20 ons that pass a
33d30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 NULL pointer ins
33d40 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 76 61 6c tead.** of a val
33d50 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 2e id mutex handle.
33d60 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 The implementat
33d70 69 6f 6e 73 20 6f 66 20 74 68 65 20 6d 65 74 68 ions of the meth
33d80 6f 64 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 ods defined.** b
33d90 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 y this structure
33da0 20 61 72 65 20 6e 6f 74 20 72 65 71 75 69 72 65 are not require
33db0 64 20 74 6f 20 68 61 6e 64 6c 65 20 74 68 69 73 d to handle this
33dc0 20 63 61 73 65 2c 20 74 68 65 20 72 65 73 75 6c case, the resul
33dd0 74 73 0a 2a 2a 20 6f 66 20 70 61 73 73 69 6e 67 ts.** of passing
33de0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
33df0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 76 61 6c instead of a val
33e00 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 20 id mutex handle
33e10 61 72 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a are undefined.**
33e20 20 28 69 2e 65 2e 20 69 74 20 69 73 20 61 63 63 (i.e. it is acc
33e30 65 70 74 61 62 6c 65 20 74 6f 20 70 72 6f 76 69 eptable to provi
33e40 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 de an implementa
33e50 74 69 6f 6e 20 74 68 61 74 20 73 65 67 66 61 75 tion that segfau
33e60 6c 74 73 20 69 66 0a 2a 2a 20 69 74 20 69 73 20 lts if.** it is
33e70 70 61 73 73 65 64 20 61 20 4e 55 4c 4c 20 70 6f passed a NULL po
33e80 69 6e 74 65 72 29 2e 0a 2a 2f 0a 74 79 70 65 64 inter)..*/.typed
33e90 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
33ea0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 3_mutex_methods
33eb0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
33ec0 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 thods;.struct sq
33ed0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
33ee0 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78 4d ods {. int (*xM
33ef0 75 74 65 78 49 6e 69 74 29 28 76 6f 69 64 29 3b utexInit)(void);
33f00 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 45 . int (*xMutexE
33f10 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 73 71 6c nd)(void);. sql
33f20 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d ite3_mutex *(*xM
33f30 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29 3b utexAlloc)(int);
33f40 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 . void (*xMutex
33f50 46 72 65 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 Free)(sqlite3_mu
33f60 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 tex *);. void (
33f70 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 28 73 71 *xMutexEnter)(sq
33f80 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a lite3_mutex *);.
33f90 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 54 72 int (*xMutexTr
33fa0 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 y)(sqlite3_mutex
33fb0 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d *);. void (*xM
33fc0 75 74 65 78 4c 65 61 76 65 29 28 73 71 6c 69 74 utexLeave)(sqlit
33fd0 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 e3_mutex *);. i
33fe0 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 6c 64 29 nt (*xMutexHeld)
33ff0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a (sqlite3_mutex *
34000 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 );. int (*xMute
34010 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69 74 65 xNotheld)(sqlite
34020 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a 0a 3_mutex *);.};..
34030 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
34040 4d 75 74 65 78 20 56 65 72 69 66 69 63 61 74 69 Mutex Verificati
34050 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31 37 on Routines {H17
34060 30 38 30 7d 20 3c 53 32 30 31 33 30 3e 20 3c 53 080} <S20130> <S
34070 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 30800>.**.** The
34080 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 sqlite3_mutex_h
34090 65 6c 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65 eld() and sqlite
340a0 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 3_mutex_notheld(
340b0 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 ) routines.** ar
340c0 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 e intended for u
340d0 73 65 20 69 6e 73 69 64 65 20 61 73 73 65 72 74 se inside assert
340e0 28 29 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 7b () statements. {
340f0 48 31 37 30 38 31 7d 20 54 68 65 20 53 51 4c 69 H17081} The SQLi
34100 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 te core.** never
34110 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 uses these rout
34120 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 69 ines except insi
34130 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 61 de an assert() a
34140 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a nd applications.
34150 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 74 ** are advised t
34160 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 o follow the lea
34170 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20 d of the core.
34180 7b 48 31 37 30 38 32 7d 20 54 68 65 20 63 6f 72 {H17082} The cor
34190 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 e only.** provid
341a0 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f es implementatio
341b0 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 ns for these rou
341c0 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73 tines when it is
341d0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 compiled.** wit
341e0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42 h the SQLITE_DEB
341f0 55 47 20 66 6c 61 67 2e 20 20 7b 41 31 37 30 38 UG flag. {A1708
34200 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 7} External mute
34210 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e x implementation
34220 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 s.** are only re
34230 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 quired to provid
34240 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 e these routines
34250 20 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 if SQLITE_DEBUG
34260 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 is.** defined a
34270 6e 64 20 69 66 20 4e 44 45 42 55 47 20 69 73 20 nd if NDEBUG is
34280 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a not defined..**.
34290 2a 2a 20 7b 48 31 37 30 38 33 7d 20 54 68 65 73 ** {H17083} Thes
342a0 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c e routines shoul
342b0 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 d return true if
342c0 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68 the mutex in th
342d0 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 eir argument.**
342e0 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 is held or not h
342f0 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c eld, respectivel
34300 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e y, by the callin
34310 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 g thread..**.**
34320 7b 58 31 37 30 38 34 7d 20 54 68 65 20 69 6d 70 {X17084} The imp
34330 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e lementation is n
34340 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 ot required to p
34350 72 6f 76 69 64 65 64 20 76 65 72 73 69 6f 6e 73 rovided versions
34360 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 of these.** rou
34370 74 69 6e 65 73 20 74 68 61 74 20 61 63 74 75 61 tines that actua
34380 6c 6c 79 20 77 6f 72 6b 2e 20 49 66 20 74 68 65 lly work. If the
34390 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
343a0 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 does not provide
343b0 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 working.** vers
343c0 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f ions of these ro
343d0 75 74 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c utines, it shoul
343e0 64 20 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69 d at least provi
343f0 64 65 20 73 74 75 62 73 20 74 68 61 74 20 61 6c de stubs that al
34400 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 ways.** return t
34410 72 75 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20 rue so that one
34420 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75 does not get spu
34430 72 69 6f 75 73 20 61 73 73 65 72 74 69 6f 6e 20 rious assertion
34440 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 failures..**.**
34450 7b 48 31 37 30 38 35 7d 20 49 66 20 74 68 65 20 {H17085} If the
34460 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
34470 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 te3_mutex_held()
34480 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
34490 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 er then.** the r
344a0 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 outine should re
344b0 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44 7d 20 54 turn 1. {END} T
344c0 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 his seems counte
344d0 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63 r-intuitive sinc
344e0 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 e.** clearly the
344f0 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 mutex cannot be
34500 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73 held if it does
34510 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74 not exist. But
34520 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 the.** the reas
34530 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65 on the mutex doe
34540 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62 s not exist is b
34550 65 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 64 ecause the build
34560 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 is not.** using
34570 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20 77 mutexes. And w
34580 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 e do not want th
34590 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74 61 e assert() conta
345a0 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c ining the.** cal
345b0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 l to sqlite3_mut
345c0 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 69 ex_held() to fai
345d0 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f l, so a non-zero
345e0 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 return is.** th
345f0 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 68 e appropriate th
34600 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b 48 31 37 ing to do. {H17
34610 30 38 36 7d 20 54 68 65 20 73 71 6c 69 74 65 33 086} The sqlite3
34620 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 _mutex_notheld()
34630 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 .** interface sh
34640 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72 6e ould also return
34650 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61 20 1 when given a
34660 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f NULL pointer..*/
34670 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 .int sqlite3_mut
34680 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 33 5f ex_held(sqlite3_
34690 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c mutex*);.int sql
346a0 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 ite3_mutex_nothe
346b0 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ld(sqlite3_mutex
346c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
346d0 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70 65 73 REF: Mutex Types
346e0 20 7b 48 31 37 30 30 31 7d 20 3c 48 31 37 30 30 {H17001} <H1700
346f0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 0>.**.** The [sq
34700 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f lite3_mutex_allo
34710 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 c()] interface t
34720 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
34730 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20 gument.** which
34740 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 is one of these
34750 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
34760 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 74 s..**.** The set
34770 20 6f 66 20 73 74 61 74 69 63 20 6d 75 74 65 78 of static mutex
34780 65 73 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 es may change fr
34790 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65 20 72 65 om one SQLite re
347a0 6c 65 61 73 65 20 74 6f 20 74 68 65 0a 2a 2a 20 lease to the.**
347b0 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 next. Applicati
347c0 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 72 69 64 ons that overrid
347d0 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d e the built-in m
347e0 75 74 65 78 20 6c 6f 67 69 63 20 6d 75 73 74 20 utex logic must
347f0 62 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 74 be.** prepared t
34800 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65 20 61 64 o accommodate ad
34810 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 ditional static
34820 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23 64 65 66 mutexes..*/.#def
34830 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 ine SQLITE_MUTEX
34840 5f 46 41 53 54 20 20 20 20 20 20 20 20 20 20 20 _FAST
34850 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
34860 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 TE_MUTEX_RECURSI
34870 56 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 VE 1.#def
34880 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 ine SQLITE_MUTEX
34890 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 20 20 _STATIC_MASTER
348a0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
348b0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
348c0 4d 45 4d 20 20 20 20 20 20 20 33 20 20 2f 2a 20 MEM 3 /*
348d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
348e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
348f0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
34900 4d 45 4d 32 20 20 20 20 20 20 34 20 20 2f 2a 20 MEM2 4 /*
34910 4e 4f 54 20 55 53 45 44 20 2a 2f 0a 23 64 65 66 NOT USED */.#def
34920 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 ine SQLITE_MUTEX
34930 5f 53 54 41 54 49 43 5f 4f 50 45 4e 20 20 20 20 _STATIC_OPEN
34940 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 42 4 /* sqlite3B
34950 74 72 65 65 4f 70 65 6e 28 29 20 2a 2f 0a 23 64 treeOpen() */.#d
34960 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 efine SQLITE_MUT
34970 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 20 20 EX_STATIC_PRNG
34980 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 5 /* sqlite
34990 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 3_random() */.#d
349a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 efine SQLITE_MUT
349b0 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20 20 20 EX_STATIC_LRU
349c0 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20 70 61 6 /* lru pa
349d0 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64 65 66 69 ge list */.#defi
349e0 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ne SQLITE_MUTEX_
349f0 53 54 41 54 49 43 5f 4c 52 55 32 20 20 20 20 20 STATIC_LRU2
34a00 20 37 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 7 /* lru page
34a10 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 list */../*.** C
34a20 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 API3REF: Retriev
34a30 65 20 74 68 65 20 6d 75 74 65 78 20 66 6f 72 20 e the mutex for
34a40 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 a database conne
34a50 63 74 69 6f 6e 20 7b 48 31 37 30 30 32 7d 20 3c ction {H17002} <
34a60 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 H17000>.**.** Th
34a70 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 is interface ret
34a80 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
34a90 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
34aa0 78 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 0a x] object that .
34ab0 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73 20 61 63 ** serializes ac
34ac0 63 65 73 73 20 74 6f 20 74 68 65 20 5b 64 61 74 cess to the [dat
34ad0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
34ae0 5d 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 61 ] given in the a
34af0 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 rgument.** when
34b00 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d the [threading m
34b10 6f 64 65 5d 20 69 73 20 53 65 72 69 61 6c 69 7a ode] is Serializ
34b20 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 74 ed..** If the [t
34b30 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 hreading mode] i
34b40 73 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 s Single-thread
34b50 6f 72 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 or Multi-thread
34b60 74 68 65 6e 20 74 68 69 73 0a 2a 2a 20 72 6f 75 then this.** rou
34b70 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e tine returns a N
34b80 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a ULL pointer..*/.
34b90 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 sqlite3_mutex *s
34ba0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 28 qlite3_db_mutex(
34bb0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
34bc0 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 77 2d * CAPI3REF: Low-
34bd0 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f 66 Level Control Of
34be0 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 20 Database Files
34bf0 7b 48 31 31 33 30 30 7d 20 3c 53 33 30 38 30 30 {H11300} <S30800
34c00 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 31 7d >.**.** {H11301}
34c10 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 The [sqlite3_fi
34c20 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e le_control()] in
34c30 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 terface makes a
34c40 64 69 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 direct call to t
34c50 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 he.** xFileContr
34c60 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 ol method for th
34c70 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
34c80 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 thods] object as
34c90 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 sociated.** with
34ca0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 a particular da
34cb0 74 61 62 61 73 65 20 69 64 65 6e 74 69 66 69 65 tabase identifie
34cc0 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 d by the second
34cd0 61 72 67 75 6d 65 6e 74 2e 20 7b 48 31 31 33 30 argument. {H1130
34ce0 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 2} The.** name o
34cf0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 f the database i
34d00 73 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 s the name assig
34d10 6e 65 64 20 74 6f 20 74 68 65 20 64 61 74 61 62 ned to the datab
34d20 61 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61 ase by the.** <a
34d30 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61 href="lang_atta
34d40 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c ch.html">ATTACH<
34d50 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 /a> SQL command
34d60 74 68 61 74 20 6f 70 65 6e 65 64 20 74 68 65 0a that opened the.
34d70 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 7b 48 31 ** database. {H1
34d80 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74 72 6f 6c 1303} To control
34d90 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 the main databa
34da0 73 65 20 66 69 6c 65 2c 20 75 73 65 20 74 68 65 se file, use the
34db0 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a 20 name "main".**
34dc0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 or a NULL pointe
34dd0 72 2e 20 7b 48 31 31 33 30 34 7d 20 54 68 65 20 r. {H11304} The
34de0 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 third and fourth
34df0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 parameters to t
34e00 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 his routine.** a
34e10 72 65 20 70 61 73 73 65 64 20 64 69 72 65 63 74 re passed direct
34e20 6c 79 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 ly through to th
34e30 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 e second and thi
34e40 72 64 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 rd parameters of
34e50 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65 43 6f 6e .** the xFileCon
34e60 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 7b 48 trol method. {H
34e70 31 31 33 30 35 7d 20 54 68 65 20 72 65 74 75 72 11305} The retur
34e80 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 78 n value of the x
34e90 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d FileControl.** m
34ea0 65 74 68 6f 64 20 62 65 63 6f 6d 65 73 20 74 68 ethod becomes th
34eb0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
34ec0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a f this routine..
34ed0 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 36 7d 20 49 **.** {H11306} I
34ee0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 f the second par
34ef0 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d 65 29 ameter (zDbName)
34f00 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 does not match
34f10 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a the name of any.
34f20 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 ** open database
34f30 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49 file, then SQLI
34f40 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65 74 75 TE_ERROR is retu
34f50 72 6e 65 64 2e 20 7b 48 31 31 33 30 37 7d 20 54 rned. {H11307} T
34f60 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 his error.** cod
34f70 65 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 e is not remembe
34f80 72 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 red and will not
34f90 20 62 65 20 72 65 63 61 6c 6c 65 64 20 62 79 20 be recalled by
34fa0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 [sqlite3_errcode
34fb0 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 ()].** or [sqlit
34fc0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20 7b 41 e3_errmsg()]. {A
34fd0 31 31 33 30 38 7d 20 54 68 65 20 75 6e 64 65 72 11308} The under
34fe0 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72 lying xFileContr
34ff0 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a ol method might.
35000 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 53 ** also return S
35010 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 7b 41 QLITE_ERROR. {A
35020 31 31 33 30 39 7d 20 54 68 65 72 65 20 69 73 20 11309} There is
35030 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 74 69 6e no way to distin
35040 67 75 69 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a guish between.**
35050 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a 44 an incorrect zD
35060 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c bName and an SQL
35070 49 54 45 5f 45 52 52 4f 52 20 72 65 74 75 72 6e ITE_ERROR return
35080 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c from the underl
35090 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e ying.** xFileCon
350a0 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b 45 4e trol method. {EN
350b0 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 D}.**.** See als
350c0 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c o: [SQLITE_FCNTL
350d0 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69 _LOCKSTATE].*/.i
350e0 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f nt sqlite3_file_
350f0 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a control(sqlite3*
35100 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 , const char *zD
35110 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76 bName, int op, v
35120 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
35130 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 PI3REF: Testing
35140 49 6e 74 65 72 66 61 63 65 20 7b 48 31 31 34 30 Interface {H1140
35150 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 0} <S30800>.**.*
35160 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 65 * The sqlite3_te
35170 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 20 69 6e 74 st_control() int
35180 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
35190 6f 20 72 65 61 64 20 6f 75 74 20 69 6e 74 65 72 o read out inter
351a0 6e 61 6c 0a 2a 2a 20 73 74 61 74 65 20 6f 66 20 nal.** state of
351b0 53 51 4c 69 74 65 20 61 6e 64 20 74 6f 20 69 6e SQLite and to in
351c0 6a 65 63 74 20 66 61 75 6c 74 73 20 69 6e 74 6f ject faults into
351d0 20 53 51 4c 69 74 65 20 66 6f 72 20 74 65 73 74 SQLite for test
351e0 69 6e 67 0a 2a 2a 20 70 75 72 70 6f 73 65 73 2e ing.** purposes.
351f0 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 The first para
35200 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70 65 72 meter is an oper
35210 61 74 69 6f 6e 20 63 6f 64 65 20 74 68 61 74 20 ation code that
35220 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 74 68 determines.** th
35230 65 20 6e 75 6d 62 65 72 2c 20 6d 65 61 6e 69 6e e number, meanin
35240 67 2c 20 61 6e 64 20 6f 70 65 72 61 74 69 6f 6e g, and operation
35250 20 6f 66 20 61 6c 6c 20 73 75 62 73 65 71 75 65 of all subseque
35260 6e 74 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a nt parameters..*
35270 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
35280 61 63 65 20 69 73 20 6e 6f 74 20 66 6f 72 20 75 ace is not for u
35290 73 65 20 62 79 20 61 70 70 6c 69 63 61 74 69 6f se by applicatio
352a0 6e 73 2e 20 20 49 74 20 65 78 69 73 74 73 20 73 ns. It exists s
352b0 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20 76 65 72 olely.** for ver
352c0 69 66 79 69 6e 67 20 74 68 65 20 63 6f 72 72 65 ifying the corre
352d0 63 74 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 ct operation of
352e0 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 the SQLite libra
352f0 72 79 2e 20 20 44 65 70 65 6e 64 69 6e 67 0a 2a ry. Depending.*
35300 2a 20 6f 6e 20 68 6f 77 20 74 68 65 20 53 51 4c * on how the SQL
35310 69 74 65 20 6c 69 62 72 61 72 79 20 69 73 20 63 ite library is c
35320 6f 6d 70 69 6c 65 64 2c 20 74 68 69 73 20 69 6e ompiled, this in
35330 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 6e 6f terface might no
35340 74 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 t exist..**.** T
35350 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 he details of th
35360 65 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 e operation code
35370 73 2c 20 74 68 65 69 72 20 6d 65 61 6e 69 6e 67 s, their meaning
35380 73 2c 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 s, the parameter
35390 73 0a 2a 2a 20 74 68 65 79 20 74 61 6b 65 2c 20 s.** they take,
353a0 61 6e 64 20 77 68 61 74 20 74 68 65 79 20 64 6f and what they do
353b0 20 61 72 65 20 61 6c 6c 20 73 75 62 6a 65 63 74 are all subject
353c0 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f to change witho
353d0 75 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20 55 6e ut notice..** Un
353e0 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 20 74 68 65 like most of the
353f0 20 53 51 4c 69 74 65 20 41 50 49 2c 20 74 68 69 SQLite API, thi
35400 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f s function is no
35410 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 0a t guaranteed to.
35420 2a 2a 20 6f 70 65 72 61 74 65 20 63 6f 6e 73 69 ** operate consi
35430 73 74 65 6e 74 6c 79 20 66 72 6f 6d 20 6f 6e 65 stently from one
35440 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 release to the
35450 6e 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c next..*/.int sql
35460 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f ite3_test_contro
35470 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a l(int op, ...);.
35480 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
35490 20 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 Testing Interfa
354a0 63 65 20 4f 70 65 72 61 74 69 6f 6e 20 43 6f 64 ce Operation Cod
354b0 65 73 20 7b 48 31 31 34 31 30 7d 20 3c 48 31 31 es {H11410} <H11
354c0 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 400>.**.** These
354d0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 constants are t
354e0 68 65 20 76 61 6c 69 64 20 6f 70 65 72 61 74 69 he valid operati
354f0 6f 6e 20 63 6f 64 65 20 70 61 72 61 6d 65 74 65 on code paramete
35500 72 73 20 75 73 65 64 0a 2a 2a 20 61 73 20 74 68 rs used.** as th
35510 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
35520 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 to [sqlite3_tes
35530 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a 2a t_control()]..**
35540 0a 2a 2a 20 54 68 65 73 65 20 70 61 72 61 6d 65 .** These parame
35550 74 65 72 73 20 61 6e 64 20 74 68 65 69 72 20 6d ters and their m
35560 65 61 6e 69 6e 67 73 20 61 72 65 20 73 75 62 6a eanings are subj
35570 65 63 74 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a ect to change.**
35580 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e without notice.
35590 20 20 54 68 65 73 65 20 76 61 6c 75 65 73 20 61 These values a
355a0 72 65 20 66 6f 72 20 74 65 73 74 69 6e 67 20 70 re for testing p
355b0 75 72 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a 2a urposes only..**
355c0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 Applications sh
355d0 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 61 6e 79 ould not use any
355e0 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 of these parame
355f0 74 65 72 73 20 6f 72 20 74 68 65 0a 2a 2a 20 5b ters or the.** [
35600 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e sqlite3_test_con
35610 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 trol()] interfac
35620 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e..*/.#define SQ
35630 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 LITE_TESTCTRL_PR
35640 4e 47 5f 53 41 56 45 20 20 20 20 20 20 20 20 20 NG_SAVE
35650 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 5.#define
35660 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c SQLITE_TESTCTRL
35670 5f 50 52 4e 47 5f 52 45 53 54 4f 52 45 20 20 20 _PRNG_RESTORE
35680 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 6.#def
35690 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 ine SQLITE_TESTC
356a0 54 52 4c 5f 50 52 4e 47 5f 52 45 53 45 54 20 20 TRL_PRNG_RESET
356b0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 7.#
356c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 define SQLITE_TE
356d0 53 54 43 54 52 4c 5f 42 49 54 56 45 43 5f 54 45 STCTRL_BITVEC_TE
356e0 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ST
356f0 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
35700 5f 54 45 53 54 43 54 52 4c 5f 46 41 55 4c 54 5f _TESTCTRL_FAULT_
35710 49 4e 53 54 41 4c 4c 20 20 20 20 20 20 20 20 20 INSTALL
35720 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 9.#define SQL
35730 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 45 4e ITE_TESTCTRL_BEN
35740 49 47 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f 4b 53 IGN_MALLOC_HOOKS
35750 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 10.#define
35760 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f SQLITE_TESTCTRL_
35770 50 45 4e 44 49 4e 47 5f 42 59 54 45 20 20 20 20 PENDING_BYTE
35780 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 11../*.*
35790 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 69 * CAPI3REF: SQLi
357a0 74 65 20 52 75 6e 74 69 6d 65 20 53 74 61 74 75 te Runtime Statu
357b0 73 20 7b 48 31 37 32 30 30 7d 20 3c 53 36 30 32 s {H17200} <S602
357c0 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 00>.** EXPERIMEN
357d0 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 TAL.**.** This i
357e0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
357f0 20 74 6f 20 72 65 74 72 69 65 76 65 20 72 75 6e to retrieve run
35800 74 69 6d 65 20 73 74 61 74 75 73 20 69 6e 66 6f time status info
35810 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 rmation.** about
35820 20 74 68 65 20 70 72 65 66 6f 72 6d 61 6e 63 65 the preformance
35830 20 6f 66 20 53 51 4c 69 74 65 2c 20 61 6e 64 20 of SQLite, and
35840 6f 70 74 69 6f 6e 61 6c 6c 79 20 74 6f 20 72 65 optionally to re
35850 73 65 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 68 set various.** h
35860 69 67 68 77 61 74 65 72 20 6d 61 72 6b 73 2e 20 ighwater marks.
35870 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
35880 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ent is an intege
35890 72 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 r code for.** th
358a0 65 20 73 70 65 63 69 66 69 63 20 70 61 72 61 6d e specific param
358b0 65 74 65 72 20 74 6f 20 6d 65 61 73 75 72 65 2e eter to measure.
358c0 20 20 52 65 63 6f 67 6e 69 7a 65 64 20 69 6e 74 Recognized int
358d0 65 67 65 72 20 63 6f 64 65 73 0a 2a 2a 20 61 72 eger codes.** ar
358e0 65 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 5b 53 e of the form [S
358f0 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d QLITE_STATUS_MEM
35900 4f 52 59 5f 55 53 45 44 20 7c 20 53 51 4c 49 54 ORY_USED | SQLIT
35910 45 5f 53 54 41 54 55 53 5f 2e 2e 2e 5d 2e 0a 2a E_STATUS_...]..*
35920 2a 20 54 68 65 20 63 75 72 72 65 6e 74 20 76 61 * The current va
35930 6c 75 65 20 6f 66 20 74 68 65 20 70 61 72 61 6d lue of the param
35940 65 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 eter is returned
35950 20 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e into *pCurrent.
35960 0a 2a 2a 20 54 68 65 20 68 69 67 68 65 73 74 20 .** The highest
35970 72 65 63 6f 72 64 65 64 20 76 61 6c 75 65 20 69 recorded value i
35980 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 s returned in *p
35990 48 69 67 68 77 61 74 65 72 2e 20 20 49 66 20 74 Highwater. If t
359a0 68 65 0a 2a 2a 20 72 65 73 65 74 46 6c 61 67 20 he.** resetFlag
359b0 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 is true, then th
359c0 65 20 68 69 67 68 65 73 74 20 72 65 63 6f 72 64 e highest record
359d0 20 76 61 6c 75 65 20 69 73 20 72 65 73 65 74 20 value is reset
359e0 61 66 74 65 72 0a 2a 2a 20 2a 70 48 69 67 68 77 after.** *pHighw
359f0 61 74 65 72 20 69 73 20 77 72 69 74 74 65 6e 2e ater is written.
35a00 20 53 6f 6d 65 20 70 61 72 61 6d 65 74 65 72 73 Some parameters
35a10 20 64 6f 20 6e 6f 74 20 72 65 63 6f 72 64 20 74 do not record t
35a20 68 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 76 61 he highest.** va
35a30 6c 75 65 2e 20 20 46 6f 72 20 74 68 6f 73 65 20 lue. For those
35a40 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6e 6f parameters.** no
35a50 74 68 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e thing is written
35a60 20 69 6e 74 6f 20 2a 70 48 69 67 68 77 61 74 65 into *pHighwate
35a70 72 20 61 6e 64 20 74 68 65 20 72 65 73 65 74 46 r and the resetF
35a80 6c 61 67 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a lag is ignored..
35a90 2a 2a 20 4f 74 68 65 72 20 70 61 72 61 6d 65 74 ** Other paramet
35aa0 65 72 73 20 72 65 63 6f 72 64 20 6f 6e 6c 79 20 ers record only
35ab0 74 68 65 20 68 69 67 68 77 61 74 65 72 20 6d 61 the highwater ma
35ac0 72 6b 20 61 6e 64 20 6e 6f 74 20 74 68 65 20 63 rk and not the c
35ad0 75 72 72 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 2e urrent.** value.
35ae0 20 20 46 6f 72 20 74 68 65 73 65 20 6c 61 74 74 For these latt
35af0 65 72 20 70 61 72 61 6d 65 74 65 72 73 20 6e 6f er parameters no
35b00 74 68 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e thing is written
35b10 20 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e into *pCurrent.
35b20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
35b30 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 ine returns SQLI
35b40 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 TE_OK on success
35b50 20 61 6e 64 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a and a non-zero.
35b60 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ** [error code]
35b70 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a on failure..**.*
35b80 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 * This routine i
35b90 73 20 74 68 72 65 61 64 73 61 66 65 20 62 75 74 s threadsafe but
35ba0 20 69 73 20 6e 6f 74 20 61 74 6f 6d 69 63 2e 20 is not atomic.
35bb0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 This routine ca
35bc0 6e 0a 2a 2a 20 63 61 6c 6c 65 64 20 77 68 69 6c n.** called whil
35bd0 65 20 6f 74 68 65 72 20 74 68 72 65 61 64 73 20 e other threads
35be0 61 72 65 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 are running the
35bf0 73 61 6d 65 20 6f 72 20 64 69 66 66 65 72 65 6e same or differen
35c00 74 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 t SQLite.** inte
35c10 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 rfaces. However
35c20 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 the values retu
35c30 72 6e 65 64 20 69 6e 20 2a 70 43 75 72 72 65 6e rned in *pCurren
35c40 74 20 61 6e 64 0a 2a 2a 20 2a 70 48 69 67 68 77 t and.** *pHighw
35c50 61 74 65 72 20 72 65 66 6c 65 63 74 20 74 68 65 ater reflect the
35c60 20 73 74 61 74 75 73 20 6f 66 20 53 51 4c 69 74 status of SQLit
35c70 65 20 61 74 20 64 69 66 66 65 72 65 6e 74 20 70 e at different p
35c80 6f 69 6e 74 73 20 69 6e 20 74 69 6d 65 0a 2a 2a oints in time.**
35c90 20 61 6e 64 20 69 74 20 69 73 20 70 6f 73 73 69 and it is possi
35ca0 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 ble that another
35cb0 20 74 68 72 65 61 64 20 6d 69 67 68 74 20 63 68 thread might ch
35cc0 61 6e 67 65 20 74 68 65 20 70 61 72 61 6d 65 74 ange the paramet
35cd0 65 72 0a 2a 2a 20 69 6e 20 62 65 74 77 65 65 6e er.** in between
35ce0 20 74 68 65 20 74 69 6d 65 73 20 77 68 65 6e 20 the times when
35cf0 2a 70 43 75 72 72 65 6e 74 20 61 6e 64 20 2a 70 *pCurrent and *p
35d00 48 69 67 68 77 61 74 65 72 20 61 72 65 20 77 72 Highwater are wr
35d10 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 itten..**.** See
35d20 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
35d30 64 62 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2f 0a db_status()].*/.
35d40 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e SQLITE_EXPERIMEN
35d50 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TAL int sqlite3_
35d60 73 74 61 74 75 73 28 69 6e 74 20 6f 70 2c 20 69 status(int op, i
35d70 6e 74 20 2a 70 43 75 72 72 65 6e 74 2c 20 69 6e nt *pCurrent, in
35d80 74 20 2a 70 48 69 67 68 77 61 74 65 72 2c 20 69 t *pHighwater, i
35d90 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a nt resetFlag);..
35da0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
35db0 20 53 74 61 74 75 73 20 50 61 72 61 6d 65 74 65 Status Paramete
35dc0 72 73 20 7b 48 31 37 32 35 30 7d 20 3c 48 31 37 rs {H17250} <H17
35dd0 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 200>.** EXPERIME
35de0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 NTAL.**.** These
35df0 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
35e00 74 73 20 64 65 73 69 67 6e 61 74 65 20 76 61 72 ts designate var
35e10 69 6f 75 73 20 72 75 6e 2d 74 69 6d 65 20 73 74 ious run-time st
35e20 61 74 75 73 20 70 61 72 61 6d 65 74 65 72 73 0a atus parameters.
35e30 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 72 ** that can be r
35e40 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
35e50 74 65 33 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a te3_status()]..*
35e60 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 *.** <dl>.** <dt
35e70 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d >SQLITE_STATUS_M
35e80 45 4d 4f 52 59 5f 55 53 45 44 3c 2f 64 74 3e 0a EMORY_USED</dt>.
35e90 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 ** <dd>This para
35ea0 6d 65 74 65 72 20 69 73 20 74 68 65 20 63 75 72 meter is the cur
35eb0 72 65 6e 74 20 61 6d 6f 75 6e 74 20 6f 66 20 6d rent amount of m
35ec0 65 6d 6f 72 79 20 63 68 65 63 6b 65 64 20 6f 75 emory checked ou
35ed0 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 t.** using [sqli
35ee0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 65 te3_malloc()], e
35ef0 69 74 68 65 72 20 64 69 72 65 63 74 6c 79 20 6f ither directly o
35f00 72 20 69 6e 64 69 72 65 63 74 6c 79 2e 20 20 54 r indirectly. T
35f10 68 65 0a 2a 2a 20 66 69 67 75 72 65 20 69 6e 63 he.** figure inc
35f20 6c 75 64 65 73 20 63 61 6c 6c 73 20 6d 61 64 65 ludes calls made
35f30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c to [sqlite3_mal
35f40 6c 6f 63 28 29 5d 20 62 79 20 74 68 65 20 61 70 loc()] by the ap
35f50 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 61 6e 64 plication.** and
35f60 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 internal memory
35f70 20 75 73 61 67 65 20 62 79 20 74 68 65 20 53 51 usage by the SQ
35f80 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 53 Lite library. S
35f90 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 0a 2a 2a cratch memory.**
35fa0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b controlled by [
35fb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
35fc0 52 41 54 43 48 5d 20 61 6e 64 20 61 75 78 69 6c RATCH] and auxil
35fd0 69 61 72 79 20 70 61 67 65 2d 63 61 63 68 65 0a iary page-cache.
35fe0 2a 2a 20 6d 65 6d 6f 72 79 20 63 6f 6e 74 72 6f ** memory contro
35ff0 6c 6c 65 64 20 62 79 20 5b 53 51 4c 49 54 45 5f lled by [SQLITE_
36000 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
36010 5d 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 ] is not include
36020 64 20 69 6e 0a 2a 2a 20 74 68 69 73 20 70 61 72 d in.** this par
36030 61 6d 65 74 65 72 2e 20 20 54 68 65 20 61 6d 6f ameter. The amo
36040 75 6e 74 20 72 65 74 75 72 6e 65 64 20 69 73 20 unt returned is
36050 74 68 65 20 73 75 6d 20 6f 66 20 74 68 65 20 61 the sum of the a
36060 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 73 69 7a llocation.** siz
36070 65 73 20 61 73 20 72 65 70 6f 72 74 65 64 20 62 es as reported b
36080 79 20 74 68 65 20 78 53 69 7a 65 20 6d 65 74 68 y the xSize meth
36090 6f 64 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 6d od in [sqlite3_m
360a0 65 6d 5f 6d 65 74 68 6f 64 73 5d 2e 3c 2f 64 64 em_methods].</dd
360b0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
360c0 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 TE_STATUS_MALLOC
360d0 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 _SIZE</dt>.** <d
360e0 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 d>This parameter
360f0 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 72 records the lar
36100 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f gest memory allo
36110 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 0a 2a cation request.*
36120 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c * handed to [sql
36130 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f ite3_malloc()] o
36140 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c r [sqlite3_reall
36150 6f 63 28 29 5d 20 28 6f 72 20 74 68 65 69 72 0a oc()] (or their.
36160 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 65 71 75 69 ** internal equi
36170 76 61 6c 65 6e 74 73 29 2e 20 20 4f 6e 6c 79 20 valents). Only
36180 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
36190 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 ed in the.** *pH
361a0 69 67 68 77 61 74 65 72 20 70 61 72 61 6d 65 74 ighwater paramet
361b0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 er to [sqlite3_s
361c0 74 61 74 75 73 28 29 5d 20 69 73 20 6f 66 20 69 tatus()] is of i
361d0 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 nterest. .** Th
361e0 65 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 e value written
361f0 69 6e 74 6f 20 74 68 65 20 2a 70 43 75 72 72 65 into the *pCurre
36200 6e 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nt parameter is
36210 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a undefined.</dd>.
36220 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
36230 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 _STATUS_PAGECACH
36240 45 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c E_USED</dt>.** <
36250 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 dd>This paramete
36260 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 r returns the nu
36270 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 75 73 mber of pages us
36280 65 64 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a ed out of the.**
36290 20 5b 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f [pagecache memo
362a0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 74 68 ry allocator] th
362b0 61 74 20 77 61 73 20 63 6f 6e 66 69 67 75 72 65 at was configure
362c0 64 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 53 51 4c d using .** [SQL
362d0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
362e0 41 43 48 45 5d 2e 20 20 54 68 65 0a 2a 2a 20 76 ACHE]. The.** v
362f0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 alue returned is
36300 20 69 6e 20 70 61 67 65 73 2c 20 6e 6f 74 20 69 in pages, not i
36310 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 0a 2a 2a n bytes.</dd>.**
36320 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 .** <dt>SQLITE_S
36330 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f TATUS_PAGECACHE_
36340 4f 56 45 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a OVERFLOW</dt>.**
36350 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 <dd>This parame
36360 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 ter returns the
36370 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
36380 6f 66 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a of page cache.**
36390 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 68 69 63 allocation whic
363a0 68 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 73 h could not be s
363b0 74 61 74 69 73 66 69 65 64 20 62 79 20 74 68 65 tatisfied by the
363c0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
363d0 50 41 47 45 43 41 43 48 45 5d 0a 2a 2a 20 62 75 PAGECACHE].** bu
363e0 66 66 65 72 20 61 6e 64 20 77 68 65 72 65 20 66 ffer and where f
363f0 6f 72 63 65 64 20 74 6f 20 6f 76 65 72 66 6c 6f orced to overflo
36400 77 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 w to [sqlite3_ma
36410 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 0a 2a 2a lloc()]. The.**
36420 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 returned value
36430 69 6e 63 6c 75 64 65 73 20 61 6c 6c 6f 63 61 74 includes allocat
36440 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 66 6c ions that overfl
36450 6f 77 65 64 20 62 65 63 61 75 73 65 20 74 68 65 owed because the
36460 79 0a 2a 2a 20 77 68 65 72 65 20 74 6f 6f 20 6c y.** where too l
36470 61 72 67 65 20 28 74 68 65 79 20 77 65 72 65 20 arge (they were
36480 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 larger than the
36490 22 73 7a 22 20 70 61 72 61 6d 65 74 65 72 20 74 "sz" parameter t
364a0 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e o.** [SQLITE_CON
364b0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 29 20 FIG_PAGECACHE])
364c0 61 6e 64 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 and allocations
364d0 74 68 61 74 20 6f 76 65 72 66 6c 6f 77 65 64 20 that overflowed
364e0 62 65 63 61 75 73 65 0a 2a 2a 20 6e 6f 20 73 70 because.** no sp
364f0 61 63 65 20 77 61 73 20 6c 65 66 74 20 69 6e 20 ace was left in
36500 74 68 65 20 70 61 67 65 20 63 61 63 68 65 2e 3c the page cache.<
36510 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
36520 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 QLITE_STATUS_PAG
36530 45 43 41 43 48 45 5f 53 49 5a 45 3c 2f 64 74 3e ECACHE_SIZE</dt>
36540 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 .** <dd>This par
36550 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 ameter records t
36560 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 he largest memor
36570 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 y allocation req
36580 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 uest.** handed t
36590 6f 20 5b 70 61 67 65 63 61 63 68 65 20 6d 65 6d o [pagecache mem
365a0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20 ory allocator].
365b0 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 Only the value
365c0 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a returned in the.
365d0 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 ** *pHighwater p
365e0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
365f0 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 ite3_status()] i
36600 73 20 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 s of interest.
36610 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 .** The value wr
36620 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a itten into the *
36630 70 43 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 pCurrent paramet
36640 65 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e er is undefined.
36650 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
36660 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 SQLITE_STATUS_SC
36670 52 41 54 43 48 5f 55 53 45 44 3c 2f 64 74 3e 0a RATCH_USED</dt>.
36680 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 ** <dd>This para
36690 6d 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 meter returns th
366a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 6c 6c 6f e number of allo
366b0 63 61 74 69 6f 6e 73 20 75 73 65 64 20 6f 75 74 cations used out
366c0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 63 72 61 of the.** [scra
366d0 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 tch memory alloc
366e0 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 65 64 ator] configured
366f0 20 75 73 69 6e 67 0a 2a 2a 20 5b 53 51 4c 49 54 using.** [SQLIT
36700 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
36710 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 ]. The value re
36720 74 75 72 6e 65 64 20 69 73 20 69 6e 20 61 6c 6c turned is in all
36730 6f 63 61 74 69 6f 6e 73 2c 20 6e 6f 74 0a 2a 2a ocations, not.**
36740 20 69 6e 20 62 79 74 65 73 2e 20 20 53 69 6e 63 in bytes. Sinc
36750 65 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 e a single threa
36760 64 20 6d 61 79 20 6f 6e 6c 79 20 68 61 76 65 20 d may only have
36770 6f 6e 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f one scratch allo
36780 63 61 74 69 6f 6e 0a 2a 2a 20 6f 75 74 73 74 61 cation.** outsta
36790 6e 64 69 6e 67 20 61 74 20 74 69 6d 65 2c 20 74 nding at time, t
367a0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 61 6c his parameter al
367b0 73 6f 20 72 65 70 6f 72 74 73 20 74 68 65 20 6e so reports the n
367c0 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 umber of threads
367d0 0a 2a 2a 20 75 73 69 6e 67 20 73 63 72 61 74 63 .** using scratc
367e0 68 20 6d 65 6d 6f 72 79 20 61 74 20 74 68 65 20 h memory at the
367f0 73 61 6d 65 20 74 69 6d 65 2e 3c 2f 64 64 3e 0a same time.</dd>.
36800 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
36810 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f _STATUS_SCRATCH_
36820 4f 56 45 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a OVERFLOW</dt>.**
36830 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 <dd>This parame
36840 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 ter returns the
36850 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
36860 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 of scratch memor
36870 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 y.** allocation
36880 77 68 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74 20 which could not
36890 62 65 20 73 74 61 74 69 73 66 69 65 64 20 62 79 be statisfied by
368a0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e the [SQLITE_CON
368b0 46 49 47 5f 53 43 52 41 54 43 48 5d 0a 2a 2a 20 FIG_SCRATCH].**
368c0 62 75 66 66 65 72 20 61 6e 64 20 77 68 65 72 65 buffer and where
368d0 20 66 6f 72 63 65 64 20 74 6f 20 6f 76 65 72 66 forced to overf
368e0 6c 6f 77 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f low to [sqlite3_
368f0 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 malloc()]. The
36900 76 61 6c 75 65 73 0a 2a 2a 20 72 65 74 75 72 6e values.** return
36910 65 64 20 69 6e 63 6c 75 64 65 20 6f 76 65 72 66 ed include overf
36920 6c 6f 77 73 20 62 65 63 61 75 73 65 20 74 68 65 lows because the
36930 20 72 65 71 75 65 73 74 65 64 20 61 6c 6c 6f 63 requested alloc
36940 61 74 69 6f 6e 20 77 61 73 20 74 6f 6f 0a 2a 2a ation was too.**
36950 20 6c 61 72 67 65 72 20 28 74 68 61 74 20 69 73 larger (that is
36960 2c 20 62 65 63 61 75 73 65 20 74 68 65 20 72 65 , because the re
36970 71 75 65 73 74 65 64 20 61 6c 6c 6f 63 61 74 69 quested allocati
36980 6f 6e 20 77 61 73 20 6c 61 72 67 65 72 20 74 68 on was larger th
36990 61 6e 20 74 68 65 0a 2a 2a 20 22 73 7a 22 20 70 an the.** "sz" p
369a0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 53 51 4c arameter to [SQL
369b0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
369c0 43 48 5d 29 20 61 6e 64 20 62 65 63 61 75 73 65 CH]) and because
369d0 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 no scratch buff
369e0 65 72 0a 2a 2a 20 73 6c 6f 74 73 20 77 65 72 65 er.** slots were
369f0 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 3c available..** <
36a00 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
36a10 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 QLITE_STATUS_SCR
36a20 41 54 43 48 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a ATCH_SIZE</dt>.*
36a30 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d * <dd>This param
36a40 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 eter records the
36a50 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 largest memory
36a60 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 allocation reque
36a70 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 st.** handed to
36a80 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 [scratch memory
36a90 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20 20 4f 6e 6c allocator]. Onl
36aa0 79 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 y the value retu
36ab0 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 2a rned in the.** *
36ac0 70 48 69 67 68 77 61 74 65 72 20 70 61 72 61 6d pHighwater param
36ad0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
36ae0 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20 6f 66 _status()] is of
36af0 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a 20 interest. .**
36b00 54 68 65 20 76 61 6c 75 65 20 77 72 69 74 74 65 The value writte
36b10 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43 75 72 n into the *pCur
36b20 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72 20 69 rent parameter i
36b30 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 s undefined.</dd
36b40 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
36b50 54 45 5f 53 54 41 54 55 53 5f 50 41 52 53 45 52 TE_STATUS_PARSER
36b60 5f 53 54 41 43 4b 3c 2f 64 74 3e 0a 2a 2a 20 3c _STACK</dt>.** <
36b70 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 dd>This paramete
36b80 72 20 72 65 63 6f 72 64 73 20 74 68 65 20 64 65 r records the de
36b90 65 70 65 73 74 20 70 61 72 73 65 72 20 73 74 61 epest parser sta
36ba0 63 6b 2e 20 20 49 74 20 69 73 20 6f 6e 6c 79 0a ck. It is only.
36bb0 2a 2a 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 ** meaningful if
36bc0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
36bd0 6c 65 64 20 77 69 74 68 20 5b 59 59 54 52 41 43 led with [YYTRAC
36be0 4b 4d 41 58 53 54 41 43 4b 44 45 50 54 48 5d 2e KMAXSTACKDEPTH].
36bf0 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a </dd>.** </dl>.*
36c00 2a 0a 2a 2a 20 4e 65 77 20 73 74 61 74 75 73 20 *.** New status
36c10 70 61 72 61 6d 65 74 65 72 73 20 6d 61 79 20 62 parameters may b
36c20 65 20 61 64 64 65 64 20 66 72 6f 6d 20 74 69 6d e added from tim
36c30 65 20 74 6f 20 74 69 6d 65 2e 0a 2a 2f 0a 23 64 e to time..*/.#d
36c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 efine SQLITE_STA
36c50 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 TUS_MEMORY_USED
36c60 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 0.#defi
36c70 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 ne SQLITE_STATUS
36c80 5f 50 41 47 45 43 41 43 48 45 5f 55 53 45 44 20 _PAGECACHE_USED
36c90 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
36ca0 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 SQLITE_STATUS_PA
36cb0 47 45 43 41 43 48 45 5f 4f 56 45 52 46 4c 4f 57 GECACHE_OVERFLOW
36cc0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
36cd0 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 ITE_STATUS_SCRAT
36ce0 43 48 5f 55 53 45 44 20 20 20 20 20 20 20 20 20 CH_USED
36cf0 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
36d00 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f _STATUS_SCRATCH_
36d10 4f 56 45 52 46 4c 4f 57 20 20 20 20 20 34 0a 23 OVERFLOW 4.#
36d20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 define SQLITE_ST
36d30 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f 53 49 5a 45 ATUS_MALLOC_SIZE
36d40 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 5.#def
36d50 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 ine SQLITE_STATU
36d60 53 5f 50 41 52 53 45 52 5f 53 54 41 43 4b 20 20 S_PARSER_STACK
36d70 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 6.#define
36d80 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 SQLITE_STATUS_P
36d90 41 47 45 43 41 43 48 45 5f 53 49 5a 45 20 20 20 AGECACHE_SIZE
36da0 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 7.#define SQ
36db0 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 LITE_STATUS_SCRA
36dc0 54 43 48 5f 53 49 5a 45 20 20 20 20 20 20 20 20 TCH_SIZE
36dd0 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 8../*.** CAPI3R
36de0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
36df0 6e 65 63 74 69 6f 6e 20 53 74 61 74 75 73 20 7b nection Status {
36e00 48 31 37 35 30 30 7d 20 3c 53 36 30 32 30 30 3e H17500} <S60200>
36e10 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
36e20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
36e30 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
36e40 20 72 65 74 72 69 65 76 65 20 72 75 6e 74 69 6d retrieve runtim
36e50 65 20 73 74 61 74 75 73 20 69 6e 66 6f 72 6d 61 e status informa
36e60 74 69 6f 6e 20 0a 2a 2a 20 61 62 6f 75 74 20 61 tion .** about a
36e70 20 73 69 6e 67 6c 65 20 5b 64 61 74 61 62 61 73 single [databas
36e80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 e connection].
36e90 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
36ea0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 64 61 74 nt is the.** dat
36eb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
36ec0 20 6f 62 6a 65 63 74 20 74 6f 20 62 65 20 69 6e object to be in
36ed0 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 terrogated. The
36ee0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
36ef0 0a 2a 2a 20 69 73 20 74 68 65 20 70 61 72 61 6d .** is the param
36f00 65 74 65 72 20 74 6f 20 69 6e 74 65 72 72 6f 67 eter to interrog
36f10 61 74 65 2e 20 20 43 75 72 72 65 6e 74 6c 79 2c ate. Currently,
36f20 20 74 68 65 20 6f 6e 6c 79 20 61 6c 6c 6f 77 65 the only allowe
36f30 64 20 76 61 6c 75 65 0a 2a 2a 20 66 6f 72 20 74 d value.** for t
36f40 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
36f50 74 65 72 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 ter is [SQLITE_D
36f60 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44 BSTATUS_LOOKASID
36f70 45 5f 55 53 45 44 5d 2e 0a 2a 2a 20 41 64 64 69 E_USED]..** Addi
36f80 74 69 6f 6e 61 6c 20 6f 70 74 69 6f 6e 73 20 77 tional options w
36f90 69 6c 6c 20 6c 69 6b 65 6c 79 20 61 70 70 65 61 ill likely appea
36fa0 72 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 r in future rele
36fb0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
36fc0 2a 2a 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e **.** The curren
36fd0 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 72 t value of the r
36fe0 65 71 75 65 73 74 65 64 20 70 61 72 61 6d 65 74 equested paramet
36ff0 65 72 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e er is written in
37000 74 6f 20 2a 70 43 75 72 0a 2a 2a 20 61 6e 64 20 to *pCur.** and
37010 74 68 65 20 68 69 67 68 65 73 74 20 69 6e 73 74 the highest inst
37020 61 6e 74 61 6e 65 6f 75 73 20 76 61 6c 75 65 20 antaneous value
37030 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 is written into
37040 2a 70 48 69 77 74 72 2e 20 20 49 66 0a 2a 2a 20 *pHiwtr. If.**
37050 74 68 65 20 72 65 73 65 74 46 6c 67 20 69 73 20 the resetFlg is
37060 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 68 true, then the h
37070 69 67 68 65 73 74 20 69 6e 73 74 61 6e 74 61 6e ighest instantan
37080 65 6f 75 73 20 76 61 6c 75 65 20 69 73 0a 2a 2a eous value is.**
37090 20 72 65 73 65 74 20 62 61 63 6b 20 64 6f 77 6e reset back down
370a0 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 to the current
370b0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 value..**.** See
370c0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
370d0 73 74 61 74 75 73 28 29 5d 20 61 6e 64 20 5b 73 status()] and [s
370e0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 qlite3_stmt_stat
370f0 75 73 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 us()]..*/.SQLITE
37100 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e _EXPERIMENTAL in
37110 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 t sqlite3_db_sta
37120 74 75 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e tus(sqlite3*, in
37130 74 20 6f 70 2c 20 69 6e 74 20 2a 70 43 75 72 2c t op, int *pCur,
37140 20 69 6e 74 20 2a 70 48 69 77 74 72 2c 20 69 6e int *pHiwtr, in
37150 74 20 72 65 73 65 74 46 6c 67 29 3b 0a 0a 2f 2a t resetFlg);../*
37160 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 .** CAPI3REF: St
37170 61 74 75 73 20 50 61 72 61 6d 65 74 65 72 73 20 atus Parameters
37180 66 6f 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e for database con
37190 6e 65 63 74 69 6f 6e 73 20 7b 48 31 37 35 32 30 nections {H17520
371a0 7d 20 3c 48 31 37 35 30 30 3e 0a 2a 2a 20 45 58 } <H17500>.** EX
371b0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
371c0 20 53 74 61 74 75 73 20 76 65 72 62 73 20 66 6f Status verbs fo
371d0 72 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 r [sqlite3_db_st
371e0 61 74 75 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 3c atus()]..**.** <
371f0 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 dl>.** <dt>SQLIT
37200 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 E_DBSTATUS_LOOKA
37210 53 49 44 45 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a SIDE_USED</dt>.*
37220 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d * <dd>This param
37230 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 65 eter returns the
37240 20 6e 75 6d 62 65 72 20 6f 66 20 6c 6f 6f 6b 61 number of looka
37250 73 69 64 65 20 6d 65 6d 6f 72 79 20 73 6c 6f 74 side memory slot
37260 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 63 s currently.** c
37270 68 65 63 6b 65 64 20 6f 75 74 2e 3c 2f 64 64 3e hecked out.</dd>
37280 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 .** </dl>.*/.#de
37290 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 53 54 fine SQLITE_DBST
372a0 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55 ATUS_LOOKASIDE_U
372b0 53 45 44 20 20 20 20 20 30 0a 0a 0a 2f 2a 0a 2a SED 0.../*.*
372c0 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 * CAPI3REF: Prep
372d0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 53 ared Statement S
372e0 74 61 74 75 73 20 7b 48 31 37 35 35 30 7d 20 3c tatus {H17550} <
372f0 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S60200>.** EXPER
37300 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 61 IMENTAL.**.** Ea
37310 63 68 20 70 72 65 70 61 72 65 64 20 73 74 61 74 ch prepared stat
37320 65 6d 65 6e 74 20 6d 61 69 6e 74 61 69 6e 73 20 ement maintains
37330 76 61 72 69 6f 75 73 0a 2a 2a 20 5b 53 51 4c 49 various.** [SQLI
37340 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f TE_STMTSTATUS_SO
37350 52 54 20 7c 20 63 6f 75 6e 74 65 72 73 5d 20 74 RT | counters] t
37360 68 61 74 20 6d 65 61 73 75 72 65 20 74 68 65 20 hat measure the
37370 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 74 69 6d number.** of tim
37380 65 73 20 69 74 20 68 61 73 20 70 65 72 66 6f 72 es it has perfor
37390 6d 65 64 20 73 70 65 63 69 66 69 63 20 6f 70 65 med specific ope
373a0 72 61 74 69 6f 6e 73 2e 20 20 54 68 65 73 65 20 rations. These
373b0 63 6f 75 6e 74 65 72 73 20 63 61 6e 0a 2a 2a 20 counters can.**
373c0 62 65 20 75 73 65 64 20 74 6f 20 6d 6f 6e 69 74 be used to monit
373d0 6f 72 20 74 68 65 20 70 65 72 66 6f 72 6d 61 6e or the performan
373e0 63 65 20 63 68 61 72 61 63 74 65 72 69 73 74 69 ce characteristi
373f0 63 73 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 cs of the prepar
37400 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 ed.** statements
37410 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 . For example,
37420 69 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 if the number of
37430 20 74 61 62 6c 65 20 73 74 65 70 73 20 67 72 65 table steps gre
37440 61 74 6c 79 20 65 78 63 65 65 64 73 0a 2a 2a 20 atly exceeds.**
37450 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 61 the number of ta
37460 62 6c 65 20 73 65 61 72 63 68 65 73 20 6f 72 20 ble searches or
37470 72 65 73 75 6c 74 20 72 6f 77 73 2c 20 74 68 61 result rows, tha
37480 74 20 77 6f 75 6c 64 20 74 65 6e 64 20 74 6f 20 t would tend to
37490 69 6e 64 69 63 61 74 65 0a 2a 2a 20 74 68 61 74 indicate.** that
374a0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
374b0 61 74 65 6d 65 6e 74 20 69 73 20 75 73 69 6e 67 atement is using
374c0 20 61 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 a full table sc
374d0 61 6e 20 72 61 74 68 65 72 20 74 68 61 6e 0a 2a an rather than.*
374e0 2a 20 61 6e 20 69 6e 64 65 78 2e 20 20 0a 2a 2a * an index. .**
374f0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
37500 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 ce is used to re
37510 74 72 69 65 76 65 20 61 6e 64 20 72 65 73 65 74 trieve and reset
37520 20 63 6f 75 6e 74 65 72 20 76 61 6c 75 65 73 20 counter values
37530 66 72 6f 6d 0a 2a 2a 20 61 20 5b 70 72 65 70 61 from.** a [prepa
37540 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 red statement].
37550 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
37560 65 6e 74 20 69 73 20 74 68 65 20 70 72 65 70 61 ent is the prepa
37570 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a red statement.**
37580 20 6f 62 6a 65 63 74 20 74 6f 20 62 65 20 69 6e object to be in
37590 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 terrogated. The
375a0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
375b0 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 .** is an intege
375c0 72 20 63 6f 64 65 20 66 6f 72 20 61 20 73 70 65 r code for a spe
375d0 63 69 66 69 63 20 5b 53 51 4c 49 54 45 5f 53 54 cific [SQLITE_ST
375e0 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 20 7c 20 MTSTATUS_SORT |
375f0 63 6f 75 6e 74 65 72 5d 0a 2a 2a 20 74 6f 20 62 counter].** to b
37600 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 e interrogated.
37610 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e 74 20 .** The current
37620 76 61 6c 75 65 20 6f 66 20 74 68 65 20 72 65 71 value of the req
37630 75 65 73 74 65 64 20 63 6f 75 6e 74 65 72 20 69 uested counter i
37640 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 s returned..** I
37650 66 20 74 68 65 20 72 65 73 65 74 46 6c 67 20 69 f the resetFlg i
37660 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 s true, then the
37670 20 63 6f 75 6e 74 65 72 20 69 73 20 72 65 73 65 counter is rese
37680 74 20 74 6f 20 7a 65 72 6f 20 61 66 74 65 72 20 t to zero after
37690 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 this.** interfac
376a0 65 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a e call returns..
376b0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
376c0 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 [sqlite3_status(
376d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
376e0 64 62 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2f db_status()]..*/
376f0 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 .SQLITE_EXPERIME
37700 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 NTAL int sqlite3
37710 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 73 71 6c _stmt_status(sql
37720 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
37730 6f 70 2c 69 6e 74 20 72 65 73 65 74 46 6c 67 29 op,int resetFlg)
37740 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
37750 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d 65 F: Status Parame
37760 74 65 72 73 20 66 6f 72 20 70 72 65 70 61 72 65 ters for prepare
37770 64 20 73 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 d statements {H1
37780 37 35 37 30 7d 20 3c 48 31 37 35 35 30 3e 0a 2a 7570} <H17550>.*
37790 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
377a0 2a 0a 2a 2a 20 54 68 65 73 65 20 70 72 65 70 72 *.** These prepr
377b0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 20 64 ocessor macros d
377c0 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f efine integer co
377d0 64 65 73 20 74 68 61 74 20 6e 61 6d 65 20 63 6f des that name co
377e0 75 6e 74 65 72 0a 2a 2a 20 76 61 6c 75 65 73 20 unter.** values
377f0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
37800 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d the [sqlite3_stm
37810 74 5f 73 74 61 74 75 73 28 29 5d 20 69 6e 74 65 t_status()] inte
37820 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65 20 6d 65 rface..** The me
37830 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 anings of the va
37840 72 69 6f 75 73 20 63 6f 75 6e 74 65 72 73 20 61 rious counters a
37850 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a re as follows:.*
37860 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 *.** <dl>.** <dt
37870 3e 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 >SQLITE_STMTSTAT
37880 55 53 5f 46 55 4c 4c 53 43 41 4e 5f 53 54 45 50 US_FULLSCAN_STEP
37890 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
378a0 73 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 s is the number
378b0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 53 51 of times that SQ
378c0 4c 69 74 65 20 68 61 73 20 73 74 65 70 70 65 64 Lite has stepped
378d0 20 66 6f 72 77 61 72 64 20 69 6e 0a 2a 2a 20 61 forward in.** a
378e0 20 74 61 62 6c 65 20 61 73 20 70 61 72 74 20 6f table as part o
378f0 66 20 61 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 f a full table s
37900 63 61 6e 2e 20 20 4c 61 72 67 65 20 6e 75 6d 62 can. Large numb
37910 65 72 73 20 66 6f 72 20 74 68 69 73 20 63 6f 75 ers for this cou
37920 6e 74 65 72 0a 2a 2a 20 6d 61 79 20 69 6e 64 69 nter.** may indi
37930 63 61 74 65 20 6f 70 70 6f 72 74 75 6e 69 74 69 cate opportuniti
37940 65 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e es for performan
37950 63 65 20 69 6d 70 72 6f 76 65 6d 65 6e 74 20 74 ce improvement t
37960 68 72 6f 75 67 68 20 0a 2a 2a 20 63 61 72 65 66 hrough .** caref
37970 75 6c 20 75 73 65 20 6f 66 20 69 6e 64 69 63 65 ul use of indice
37980 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 s.</dd>.**.** <d
37990 74 3e 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 t>SQLITE_STMTSTA
379a0 54 55 53 5f 53 4f 52 54 3c 2f 64 74 3e 0a 2a 2a TUS_SORT</dt>.**
379b0 20 3c 64 64 3e 54 68 69 73 20 69 73 20 74 68 65 <dd>This is the
379c0 20 6e 75 6d 62 65 72 20 6f 66 20 73 6f 72 74 20 number of sort
379d0 6f 70 65 72 61 74 69 6f 6e 73 20 74 68 61 74 20 operations that
379e0 68 61 76 65 20 6f 63 63 75 72 72 65 64 2e 0a 2a have occurred..*
379f0 2a 20 41 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c * A non-zero val
37a00 75 65 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 ue in this count
37a10 65 72 20 6d 61 79 20 69 6e 64 69 63 61 74 65 20 er may indicate
37a20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 an opportunity t
37a30 6f 0a 2a 2a 20 69 6d 70 72 6f 76 65 6d 65 6e 74 o.** improvement
37a40 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 74 68 72 performance thr
37a50 6f 75 67 68 20 63 61 72 65 66 75 6c 20 75 73 65 ough careful use
37a60 20 6f 66 20 69 6e 64 69 63 65 73 2e 3c 2f 64 64 of indices.</dd
37a70 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f >.**.** </dl>.*/
37a80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
37a90 53 54 4d 54 53 54 41 54 55 53 5f 46 55 4c 4c 53 STMTSTATUS_FULLS
37aa0 43 41 4e 5f 53 54 45 50 20 20 20 20 20 31 0a 23 CAN_STEP 1.#
37ab0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 define SQLITE_ST
37ac0 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 20 20 20 MTSTATUS_SORT
37ad0 20 20 20 20 20 20 20 20 20 20 20 32 0a 0a 2f 2a 2../*
37ae0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 75 .** CAPI3REF: Cu
37af0 73 74 6f 6d 20 50 61 67 65 20 43 61 63 68 65 20 stom Page Cache
37b00 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 50 45 52 49 Object.** EXPERI
37b10 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 MENTAL.**.** The
37b20 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 20 sqlite3_pcache
37b30 74 79 70 65 20 69 73 20 6f 70 61 71 75 65 2e 20 type is opaque.
37b40 20 49 74 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 It is implement
37b50 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 6c 75 ed by.** the plu
37b60 67 67 61 62 6c 65 20 6d 6f 64 75 6c 65 2e 20 20 ggable module.
37b70 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
37b80 68 61 73 20 6e 6f 20 6b 6e 6f 77 6c 65 64 67 65 has no knowledge
37b90 20 6f 66 0a 2a 2a 20 69 74 73 20 73 69 7a 65 20 of.** its size
37ba0 6f 72 20 69 6e 74 65 72 6e 61 6c 20 73 74 72 75 or internal stru
37bb0 63 74 75 72 65 20 61 6e 64 20 6e 65 76 65 72 20 cture and never
37bc0 64 65 61 6c 73 20 77 69 74 68 20 74 68 65 0a 2a deals with the.*
37bd0 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 * sqlite3_pcache
37be0 20 6f 62 6a 65 63 74 20 65 78 63 65 70 74 20 62 object except b
37bf0 79 20 68 6f 6c 64 69 6e 67 20 61 6e 64 20 70 61 y holding and pa
37c00 73 73 69 6e 67 20 70 6f 69 6e 74 65 72 73 0a 2a ssing pointers.*
37c10 2a 20 74 6f 20 74 68 65 20 6f 62 6a 65 63 74 2e * to the object.
37c20 0a 2a 2a 0a 2a 2a 20 53 65 65 20 5b 73 71 6c 69 .**.** See [sqli
37c30 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
37c40 64 73 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ds] for addition
37c50 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
37c60 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
37c70 74 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 t sqlite3_pcache
37c80 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 3b sqlite3_pcache;
37c90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
37ca0 3a 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 44 65 : Application De
37cb0 66 69 6e 65 64 20 50 61 67 65 20 43 61 63 68 65 fined Page Cache
37cc0 2e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 ..** EXPERIMENTA
37cd0 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c L.**.** The [sql
37ce0 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 ite3_config]([SQ
37cf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
37d00 48 45 5d 2c 20 2e 2e 2e 29 20 69 6e 74 65 72 66 HE], ...) interf
37d10 61 63 65 20 63 61 6e 0a 2a 2a 20 72 65 67 69 73 ace can.** regis
37d20 74 65 72 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 ter an alternati
37d30 76 65 20 70 61 67 65 20 63 61 63 68 65 20 69 6d ve page cache im
37d40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 62 79 20 plementation by
37d50 70 61 73 73 69 6e 67 20 69 6e 20 61 6e 20 0a 2a passing in an .*
37d60 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 * instance of th
37d70 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 e sqlite3_pcache
37d80 5f 6d 65 74 68 6f 64 73 20 73 74 72 75 63 74 75 _methods structu
37d90 72 65 2e 20 54 68 65 20 6d 61 6a 6f 72 69 74 79 re. The majority
37da0 20 6f 66 20 74 68 65 20 0a 2a 2a 20 68 65 61 70 of the .** heap
37db0 20 6d 65 6d 6f 72 79 20 75 73 65 64 20 62 79 20 memory used by
37dc0 73 71 6c 69 74 65 20 69 73 20 75 73 65 64 20 62 sqlite is used b
37dd0 79 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 y the page cache
37de0 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 20 72 to cache data r
37df0 65 61 64 20 0a 2a 2a 20 66 72 6f 6d 2c 20 6f 72 ead .** from, or
37e00 20 72 65 61 64 79 20 74 6f 20 62 65 20 77 72 69 ready to be wri
37e10 74 74 65 6e 20 74 6f 2c 20 74 68 65 20 64 61 74 tten to, the dat
37e20 61 62 61 73 65 20 66 69 6c 65 2e 20 42 79 20 69 abase file. By i
37e30 6d 70 6c 65 6d 65 6e 74 69 6e 67 20 61 20 0a 2a mplementing a .*
37e40 2a 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 * custom page ca
37e50 63 68 65 20 75 73 69 6e 67 20 74 68 69 73 20 41 che using this A
37e60 50 49 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 PI, an applicati
37e70 6f 6e 20 63 61 6e 20 63 6f 6e 74 72 6f 6c 20 6d on can control m
37e80 6f 72 65 20 0a 2a 2a 20 70 72 65 63 69 73 65 6c ore .** precisel
37e90 79 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 y the amount of
37ea0 6d 65 6d 6f 72 79 20 63 6f 6e 73 75 6d 65 64 20 memory consumed
37eb0 62 79 20 73 71 6c 69 74 65 2c 20 74 68 65 20 77 by sqlite, the w
37ec0 61 79 20 69 6e 20 77 68 69 63 68 20 0a 2a 2a 20 ay in which .**
37ed0 73 61 69 64 20 6d 65 6d 6f 72 79 20 69 73 20 61 said memory is a
37ee0 6c 6c 6f 63 61 74 65 64 20 61 6e 64 20 72 65 6c llocated and rel
37ef0 65 61 73 65 64 2c 20 61 6e 64 20 74 68 65 20 70 eased, and the p
37f00 6f 6c 69 63 69 65 73 20 75 73 65 64 20 74 6f 20 olicies used to
37f10 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 20 65 78 .** determine ex
37f20 61 63 74 6c 79 20 77 68 69 63 68 20 70 61 72 74 actly which part
37f30 73 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 s of a database
37f40 66 69 6c 65 20 61 72 65 20 63 61 63 68 65 64 20 file are cached
37f50 61 6e 64 20 66 6f 72 20 0a 2a 2a 20 68 6f 77 20 and for .** how
37f60 6c 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 long..**.** The
37f70 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 contents of the
37f80 73 74 72 75 63 74 75 72 65 20 61 72 65 20 63 6f structure are co
37f90 70 69 65 64 20 74 6f 20 61 6e 20 69 6e 74 65 72 pied to an inter
37fa0 6e 61 6c 20 62 75 66 66 65 72 20 62 79 20 73 71 nal buffer by sq
37fb0 6c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 74 lite.** within t
37fc0 68 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 he call to [sqli
37fd0 74 65 33 5f 63 6f 6e 66 69 67 5d 2e 0a 2a 2a 0a te3_config]..**.
37fe0 2a 2a 20 54 68 65 20 78 49 6e 69 74 28 29 20 6d ** The xInit() m
37ff0 65 74 68 6f 64 20 69 73 20 63 61 6c 6c 65 64 20 ethod is called
38000 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63 61 once for each ca
38010 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69 ll to [sqlite3_i
38020 6e 69 74 69 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 nitialize()].**
38030 28 75 73 75 61 6c 6c 79 20 6f 6e 6c 79 20 6f 6e (usually only on
38040 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 ce during the li
38050 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 70 72 fetime of the pr
38060 6f 63 65 73 73 29 2e 20 49 74 20 69 73 20 70 61 ocess). It is pa
38070 73 73 65 64 0a 2a 2a 20 61 20 63 6f 70 79 20 6f ssed.** a copy o
38080 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 63 f the sqlite3_pc
38090 61 63 68 65 5f 6d 65 74 68 6f 64 73 2e 70 41 72 ache_methods.pAr
380a0 67 20 76 61 6c 75 65 2e 20 49 74 20 63 61 6e 20 g value. It can
380b0 62 65 20 75 73 65 64 20 74 6f 20 73 65 74 0a 2a be used to set.*
380c0 2a 20 75 70 20 67 6c 6f 62 61 6c 20 73 74 72 75 * up global stru
380d0 63 74 75 72 65 73 20 61 6e 64 20 6d 75 74 65 78 ctures and mutex
380e0 65 73 20 72 65 71 75 69 72 65 64 20 62 79 20 74 es required by t
380f0 68 65 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 he custom page c
38100 61 63 68 65 20 0a 2a 2a 20 69 6d 70 6c 65 6d 65 ache .** impleme
38110 6e 74 61 74 69 6f 6e 2e 20 54 68 65 20 78 53 68 ntation. The xSh
38120 75 74 64 6f 77 6e 28 29 20 6d 65 74 68 6f 64 20 utdown() method
38130 69 73 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 is called from w
38140 69 74 68 69 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 ithin .** [sqlit
38150 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2c 20 e3_shutdown()],
38160 69 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 if the applicati
38170 6f 6e 20 69 6e 76 6f 6b 65 73 20 74 68 69 73 20 on invokes this
38180 41 50 49 2e 20 49 74 20 63 61 6e 20 62 65 20 75 API. It can be u
38190 73 65 64 0a 2a 2a 20 74 6f 20 63 6c 65 61 6e 20 sed.** to clean
381a0 75 70 20 61 6e 79 20 6f 75 74 73 74 61 6e 64 69 up any outstandi
381b0 6e 67 20 72 65 73 6f 75 72 63 65 73 20 62 65 66 ng resources bef
381c0 6f 72 65 20 70 72 6f 63 65 73 73 20 73 68 75 74 ore process shut
381d0 64 6f 77 6e 2c 20 69 66 20 72 65 71 75 69 72 65 down, if require
381e0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 72 d..**.** The xCr
381f0 65 61 74 65 28 29 20 6d 65 74 68 6f 64 20 69 73 eate() method is
38200 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 used to constru
38210 63 74 20 61 20 6e 65 77 20 63 61 63 68 65 20 69 ct a new cache i
38220 6e 73 74 61 6e 63 65 2e 20 54 68 65 0a 2a 2a 20 nstance. The.**
38230 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2c first parameter,
38240 20 73 7a 50 61 67 65 2c 20 69 73 20 74 68 65 20 szPage, is the
38250 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66 size in bytes of
38260 20 74 68 65 20 70 61 67 65 73 20 74 68 61 74 20 the pages that
38270 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 6c 6f 63 must.** be alloc
38280 61 74 65 64 20 62 79 20 74 68 65 20 63 61 63 68 ated by the cach
38290 65 2e 20 73 7a 50 61 67 65 20 77 69 6c 6c 20 6e e. szPage will n
382a0 6f 74 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66 ot be a power of
382b0 20 74 77 6f 2e 20 54 68 65 0a 2a 2a 20 73 65 63 two. The.** sec
382c0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 62 50 ond argument, bP
382d0 75 72 67 65 61 62 6c 65 2c 20 69 73 20 74 72 75 urgeable, is tru
382e0 65 20 69 66 20 74 68 65 20 63 61 63 68 65 20 62 e if the cache b
382f0 65 69 6e 67 20 63 72 65 61 74 65 64 20 77 69 6c eing created wil
38300 6c 0a 2a 2a 20 62 65 20 75 73 65 64 20 74 6f 20 l.** be used to
38310 63 61 63 68 65 20 64 61 74 61 62 61 73 65 20 70 cache database p
38320 61 67 65 73 20 72 65 61 64 20 66 72 6f 6d 20 61 ages read from a
38330 20 66 69 6c 65 20 73 74 6f 72 65 64 20 6f 6e 20 file stored on
38340 64 69 73 6b 2c 20 6f 72 0a 2a 2a 20 66 61 6c 73 disk, or.** fals
38350 65 20 69 66 20 69 74 20 69 73 20 75 73 65 64 20 e if it is used
38360 66 6f 72 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 for an in-memory
38370 20 64 61 74 61 62 61 73 65 2e 20 54 68 65 20 63 database. The c
38380 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
38390 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 ion.** does not
383a0 68 61 76 65 20 74 6f 20 64 6f 20 61 6e 79 74 68 have to do anyth
383b0 69 6e 67 20 73 70 65 63 69 61 6c 20 62 61 73 65 ing special base
383c0 64 20 6f 6e 20 74 68 65 20 76 61 6c 75 65 20 6f d on the value o
383d0 66 20 62 50 75 72 67 65 61 62 6c 65 2c 0a 2a 2a f bPurgeable,.**
383e0 20 69 74 20 69 73 20 70 75 72 65 6c 79 20 61 64 it is purely ad
383f0 76 69 73 6f 72 79 2e 20 0a 2a 2a 0a 2a 2a 20 54 visory. .**.** T
38400 68 65 20 78 43 61 63 68 65 73 69 7a 65 28 29 20 he xCachesize()
38410 6d 65 74 68 6f 64 20 6d 61 79 20 62 65 20 63 61 method may be ca
38420 6c 6c 65 64 20 61 74 20 61 6e 79 20 74 69 6d 65 lled at any time
38430 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 73 65 by SQLite to se
38440 74 20 74 68 65 0a 2a 2a 20 73 75 67 67 65 73 74 t the.** suggest
38450 65 64 20 6d 61 78 69 6d 75 6d 20 63 61 63 68 65 ed maximum cache
38460 2d 73 69 7a 65 20 28 6e 75 6d 62 65 72 20 6f 66 -size (number of
38470 20 70 61 67 65 73 20 73 74 6f 72 65 64 20 62 79 pages stored by
38480 29 20 74 68 65 20 63 61 63 68 65 0a 2a 2a 20 69 ) the cache.** i
38490 6e 73 74 61 6e 63 65 20 70 61 73 73 65 64 20 61 nstance passed a
384a0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
384b0 6d 65 6e 74 2e 20 54 68 69 73 20 69 73 20 74 68 ment. This is th
384c0 65 20 76 61 6c 75 65 20 63 6f 6e 66 69 67 75 72 e value configur
384d0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 ed using.** the
384e0 53 51 4c 69 74 65 20 22 5b 50 52 41 47 4d 41 20 SQLite "[PRAGMA
384f0 63 61 63 68 65 5f 73 69 7a 65 5d 22 20 63 6f 6d cache_size]" com
38500 6d 61 6e 64 2e 20 41 73 20 77 69 74 68 20 74 68 mand. As with th
38510 65 20 62 50 75 72 67 65 61 62 6c 65 20 70 61 72 e bPurgeable par
38520 61 6d 65 74 65 72 2c 0a 2a 2a 20 74 68 65 20 69 ameter,.** the i
38530 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 mplementation is
38540 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f not required to
38550 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 73 70 65 do anything spe
38560 63 69 61 6c 20 77 69 74 68 20 74 68 69 73 0a 2a cial with this.*
38570 2a 20 76 61 6c 75 65 2c 20 69 74 20 69 73 20 61 * value, it is a
38580 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a dvisory only..**
38590 0a 2a 2a 20 54 68 65 20 78 50 61 67 65 63 6f 75 .** The xPagecou
385a0 6e 74 28 29 20 6d 65 74 68 6f 64 20 73 68 6f 75 nt() method shou
385b0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 6e 75 ld return the nu
385c0 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 63 75 mber of pages cu
385d0 72 72 65 6e 74 6c 79 0a 2a 2a 20 73 74 6f 72 65 rrently.** store
385e0 64 20 69 6e 20 74 68 65 20 63 61 63 68 65 20 73 d in the cache s
385f0 75 70 70 6c 69 65 64 20 61 73 20 61 6e 20 61 72 upplied as an ar
38600 67 75 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a 2a 20 54 gument..** .** T
38610 68 65 20 78 46 65 74 63 68 28 29 20 6d 65 74 68 he xFetch() meth
38620 6f 64 20 69 73 20 75 73 65 64 20 74 6f 20 66 65 od is used to fe
38630 74 63 68 20 61 20 70 61 67 65 20 61 6e 64 20 72 tch a page and r
38640 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 eturn a pointer
38650 74 6f 20 69 74 2e 20 0a 2a 2a 20 41 20 27 70 61 to it. .** A 'pa
38660 67 65 27 2c 20 69 6e 20 74 68 69 73 20 63 6f 6e ge', in this con
38670 74 65 78 74 2c 20 69 73 20 61 20 62 75 66 66 65 text, is a buffe
38680 72 20 6f 66 20 73 7a 50 61 67 65 20 62 79 74 65 r of szPage byte
38690 73 20 61 6c 69 67 6e 65 64 20 61 74 20 61 6e 0a s aligned at an.
386a0 2a 2a 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 ** 8-byte bounda
386b0 72 79 2e 20 54 68 65 20 70 61 67 65 20 74 6f 20 ry. The page to
386c0 62 65 20 66 65 74 63 68 65 64 20 69 73 20 64 65 be fetched is de
386d0 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 termined by the
386e0 6b 65 79 2e 20 54 68 65 0a 2a 2a 20 6d 69 6d 69 key. The.** mimi
386f0 6d 75 6d 20 6b 65 79 20 76 61 6c 75 65 20 69 73 mum key value is
38700 20 31 2e 20 41 66 74 65 72 20 69 74 20 68 61 73 1. After it has
38710 20 62 65 65 6e 20 72 65 74 72 69 65 76 65 64 20 been retrieved
38720 75 73 69 6e 67 20 78 46 65 74 63 68 2c 20 74 68 using xFetch, th
38730 65 20 70 61 67 65 20 0a 2a 2a 20 69 73 20 63 6f e page .** is co
38740 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 70 nsidered to be p
38750 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 inned..**.** If
38760 74 68 65 20 72 65 71 75 65 73 74 65 64 20 70 61 the requested pa
38770 67 65 20 69 73 20 61 6c 72 65 61 64 79 20 69 6e ge is already in
38780 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 2c the page cache,
38790 20 74 68 65 6e 20 61 20 70 6f 69 6e 74 65 72 20 then a pointer
387a0 74 6f 0a 2a 2a 20 74 68 65 20 63 61 63 68 65 64 to.** the cached
387b0 20 62 75 66 66 65 72 20 73 68 6f 75 6c 64 20 62 buffer should b
387c0 65 20 72 65 74 75 72 6e 65 64 20 77 69 74 68 20 e returned with
387d0 69 74 73 20 63 6f 6e 74 65 6e 74 73 20 69 6e 74 its contents int
387e0 61 63 74 2e 20 49 66 20 74 68 65 0a 2a 2a 20 70 act. If the.** p
387f0 61 67 65 20 69 73 20 6e 6f 74 20 61 6c 72 65 61 age is not alrea
38800 64 79 20 69 6e 20 74 68 65 20 63 61 63 68 65 2c dy in the cache,
38810 20 74 68 65 6e 20 74 68 65 20 65 78 70 65 63 74 then the expect
38820 65 64 20 62 65 68 61 76 69 6f 75 72 20 6f 66 20 ed behaviour of
38830 74 68 65 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 the.** cache is
38840 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 determined by th
38850 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 63 e value of the c
38860 72 65 61 74 65 46 6c 61 67 20 70 61 72 61 6d 65 reateFlag parame
38870 74 65 72 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f ter passed.** to
38880 20 78 46 65 74 63 68 2c 20 61 63 63 6f 72 64 69 xFetch, accordi
38890 6e 67 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 ng to the follow
388a0 69 6e 67 20 74 61 62 6c 65 3a 0a 2a 2a 0a 2a 2a ing table:.**.**
388b0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 31 <table border=1
388c0 20 77 69 64 74 68 3d 38 35 25 20 61 6c 69 67 6e width=85% align
388d0 3d 63 65 6e 74 65 72 3e 0a 2a 2a 20 20 20 3c 74 =center>.** <t
388e0 72 3e 3c 74 68 3e 63 72 65 61 74 65 46 6c 61 67 r><th>createFlag
388f0 3c 74 68 3e 45 78 70 65 63 74 65 64 20 42 65 68 <th>Expected Beh
38900 61 76 69 6f 75 72 0a 2a 2a 20 20 20 3c 74 72 3e aviour.** <tr>
38910 3c 74 64 3e 30 3c 74 64 3e 4e 55 4c 4c 20 73 68 <td>0<td>NULL sh
38920 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 ould be returned
38930 2e 20 4e 6f 20 6e 65 77 20 63 61 63 68 65 20 65 . No new cache e
38940 6e 74 72 79 20 69 73 20 63 72 65 61 74 65 64 2e ntry is created.
38950 0a 2a 2a 20 20 20 3c 74 72 3e 3c 74 64 3e 31 3c .** <tr><td>1<
38960 74 64 3e 49 66 20 63 72 65 61 74 65 46 6c 61 67 td>If createFlag
38970 20 69 73 20 73 65 74 20 74 6f 20 31 2c 20 74 68 is set to 1, th
38980 69 73 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 is indicates tha
38990 74 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 t .**
389a0 20 20 20 20 20 53 51 4c 69 74 65 20 69 73 20 68 SQLite is h
389b0 6f 6c 64 69 6e 67 20 70 69 6e 6e 65 64 20 70 61 olding pinned pa
389c0 67 65 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 ges that can be
389d0 75 6e 70 69 6e 6e 65 64 0a 2a 2a 20 20 20 20 20 unpinned.**
389e0 20 20 20 20 20 20 20 20 20 20 20 62 79 20 77 72 by wr
389f0 69 74 69 6e 67 20 74 68 65 69 72 20 63 6f 6e 74 iting their cont
38a00 65 6e 74 73 20 74 6f 20 74 68 65 20 64 61 74 61 ents to the data
38a10 62 61 73 65 20 66 69 6c 65 20 28 61 0a 2a 2a 20 base file (a.**
38a20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 72 r
38a30 65 6c 61 74 69 76 65 6c 79 20 65 78 70 65 6e 73 elatively expens
38a40 69 76 65 20 6f 70 65 72 61 74 69 6f 6e 29 2e 20 ive operation).
38a50 49 6e 20 74 68 69 73 20 73 69 74 75 61 74 69 6f In this situatio
38a60 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 n the.**
38a70 20 20 20 20 20 20 20 20 63 61 63 68 65 20 69 6d cache im
38a80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73 plementation has
38a90 20 74 77 6f 20 63 68 6f 69 63 65 73 3a 20 69 74 two choices: it
38aa0 20 63 61 6e 20 72 65 74 75 72 6e 20 4e 55 4c 4c can return NULL
38ab0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 ,.**
38ac0 20 20 20 20 69 6e 20 77 68 69 63 68 20 63 61 73 in which cas
38ad0 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 74 e SQLite will at
38ae0 74 65 6d 70 74 20 74 6f 20 75 6e 70 69 6e 20 6f tempt to unpin o
38af0 6e 65 20 6f 72 20 6d 6f 72 65 20 0a 2a 2a 20 20 ne or more .**
38b00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 70 61 pa
38b10 67 65 73 20 62 65 66 6f 72 65 20 72 65 2d 72 65 ges before re-re
38b20 71 75 65 73 74 69 6e 67 20 74 68 65 20 73 61 6d questing the sam
38b30 65 20 70 61 67 65 2c 20 6f 72 20 69 74 20 63 61 e page, or it ca
38b40 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 n.**
38b50 20 20 20 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e allocate a n
38b60 65 77 20 70 61 67 65 20 61 6e 64 20 72 65 74 75 ew page and retu
38b70 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 rn a pointer to
38b80 69 74 2e 20 49 66 20 61 20 6e 65 77 0a 2a 2a 20 it. If a new.**
38b90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 70 p
38ba0 61 67 65 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 age is allocated
38bb0 2c 20 74 68 65 6e 20 74 68 65 20 66 69 72 73 74 , then the first
38bc0 20 73 69 7a 65 6f 66 28 76 6f 69 64 2a 29 20 62 sizeof(void*) b
38bd0 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 ytes of.**
38be0 20 20 20 20 20 20 20 20 20 20 69 74 20 28 61 74 it (at
38bf0 20 6c 65 61 73 74 29 20 6d 75 73 74 20 62 65 20 least) must be
38c00 7a 65 72 6f 65 64 20 62 65 66 6f 72 65 20 69 74 zeroed before it
38c10 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
38c20 20 20 20 3c 74 72 3e 3c 74 64 3e 32 3c 74 64 3e <tr><td>2<td>
38c30 49 66 20 63 72 65 61 74 65 46 6c 61 67 20 69 73 If createFlag is
38c40 20 73 65 74 20 74 6f 20 32 2c 20 74 68 65 6e 20 set to 2, then
38c50 53 51 4c 69 74 65 20 69 73 20 6e 6f 74 20 68 6f SQLite is not ho
38c60 6c 64 69 6e 67 20 61 6e 79 0a 2a 2a 20 20 20 20 lding any.**
38c70 20 20 20 20 20 20 20 20 20 20 20 20 70 69 6e 6e pinn
38c80 65 64 20 70 61 67 65 73 20 61 73 73 6f 63 69 61 ed pages associa
38c90 74 65 64 20 77 69 74 68 20 74 68 65 20 73 70 65 ted with the spe
38ca0 63 69 66 69 63 20 63 61 63 68 65 20 70 61 73 73 cific cache pass
38cb0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 ed.**
38cc0 20 20 20 20 20 61 73 20 74 68 65 20 66 69 72 73 as the firs
38cd0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 46 t argument to xF
38ce0 65 74 63 68 28 29 20 74 68 61 74 20 63 61 6e 20 etch() that can
38cf0 62 65 20 75 6e 70 69 6e 6e 65 64 2e 20 54 68 65 be unpinned. The
38d00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 .**
38d10 20 20 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 cache impleme
38d20 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 61 ntation should a
38d30 74 74 65 6d 70 74 20 74 6f 20 61 6c 6c 6f 63 61 ttempt to alloca
38d40 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 te a new.**
38d50 20 20 20 20 20 20 20 20 20 20 20 63 61 63 68 65 cache
38d60 20 65 6e 74 72 79 20 61 6e 64 20 72 65 74 75 72 entry and retur
38d70 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 n a pointer to i
38d80 74 2e 20 41 67 61 69 6e 2c 20 74 68 65 20 66 69 t. Again, the fi
38d90 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 rst.**
38da0 20 20 20 20 20 20 73 69 7a 65 6f 66 28 76 6f 69 sizeof(voi
38db0 64 2a 29 20 62 79 74 65 73 20 6f 66 20 74 68 65 d*) bytes of the
38dc0 20 70 61 67 65 20 73 68 6f 75 6c 64 20 62 65 20 page should be
38dd0 7a 65 72 6f 65 64 20 62 65 66 6f 72 65 20 0a 2a zeroed before .*
38de0 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *
38df0 20 69 74 20 69 73 20 72 65 74 75 72 6e 65 64 2e it is returned.
38e00 20 49 66 20 74 68 65 20 78 46 65 74 63 68 28 29 If the xFetch()
38e10 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
38e20 4e 55 4c 4c 20 77 68 65 6e 20 0a 2a 2a 20 20 20 NULL when .**
38e30 20 20 20 20 20 20 20 20 20 20 20 20 20 63 72 65 cre
38e40 61 74 65 46 6c 61 67 3d 3d 32 2c 20 53 51 4c 69 ateFlag==2, SQLi
38e50 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 te assumes that
38e60 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
38e70 69 6f 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 ion .**
38e80 20 20 20 20 20 20 20 66 61 69 6c 65 64 20 61 6e failed an
38e90 64 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 d returns SQLITE
38ea0 5f 4e 4f 4d 45 4d 20 74 6f 20 74 68 65 20 75 73 _NOMEM to the us
38eb0 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a er..** </table>.
38ec0 2a 2a 0a 2a 2a 20 78 55 6e 70 69 6e 28 29 20 69 **.** xUnpin() i
38ed0 73 20 63 61 6c 6c 65 64 20 62 79 20 53 51 4c 69 s called by SQLi
38ee0 74 65 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 te with a pointe
38ef0 72 20 74 6f 20 61 20 63 75 72 72 65 6e 74 6c 79 r to a currently
38f00 20 70 69 6e 6e 65 64 20 70 61 67 65 0a 2a 2a 20 pinned page.**
38f10 61 73 20 69 74 73 20 73 65 63 6f 6e 64 20 61 72 as its second ar
38f20 67 75 6d 65 6e 74 2e 20 49 66 20 74 68 65 20 74 gument. If the t
38f30 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2c 20 hird parameter,
38f40 64 69 73 63 61 72 64 2c 20 69 73 20 6e 6f 6e 2d discard, is non-
38f50 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 zero,.** then th
38f60 65 20 70 61 67 65 20 73 68 6f 75 6c 64 20 62 65 e page should be
38f70 20 65 76 69 63 74 65 64 20 66 72 6f 6d 20 74 68 evicted from th
38f80 65 20 63 61 63 68 65 2e 20 49 6e 20 74 68 69 73 e cache. In this
38f90 20 63 61 73 65 20 53 51 4c 69 74 65 20 0a 2a 2a case SQLite .**
38fa0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 assumes that th
38fb0 65 20 6e 65 78 74 20 74 69 6d 65 20 74 68 65 20 e next time the
38fc0 70 61 67 65 20 69 73 20 72 65 74 72 69 65 76 65 page is retrieve
38fd0 64 20 66 72 6f 6d 20 74 68 65 20 63 61 63 68 65 d from the cache
38fe0 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 78 46 using.** the xF
38ff0 65 74 63 68 28 29 20 6d 65 74 68 6f 64 2c 20 69 etch() method, i
39000 74 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 t will be zeroed
39010 2e 20 49 66 20 74 68 65 20 64 69 73 63 61 72 64 . If the discard
39020 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a parameter is.**
39030 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 zero, then the
39040 70 61 67 65 20 69 73 20 63 6f 6e 73 69 64 65 72 page is consider
39050 65 64 20 74 6f 20 62 65 20 75 6e 70 69 6e 6e 65 ed to be unpinne
39060 64 2e 20 54 68 65 20 63 61 63 68 65 20 69 6d 70 d. The cache imp
39070 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6d lementation.** m
39080 61 79 20 63 68 6f 6f 73 65 20 74 6f 20 72 65 63 ay choose to rec
39090 6c 61 69 6d 20 28 66 72 65 65 20 6f 72 20 72 65 laim (free or re
390a0 63 79 63 6c 65 29 20 75 6e 70 69 6e 6e 65 64 20 cycle) unpinned
390b0 70 61 67 65 73 20 61 74 20 61 6e 79 20 74 69 6d pages at any tim
390c0 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 73 73 e..** SQLite ass
390d0 75 6d 65 73 20 74 68 61 74 20 6e 65 78 74 20 74 umes that next t
390e0 69 6d 65 20 74 68 65 20 70 61 67 65 20 69 73 20 ime the page is
390f0 72 65 74 72 69 65 76 65 64 20 66 72 6f 6d 20 74 retrieved from t
39100 68 65 20 63 61 63 68 65 0a 2a 2a 20 69 74 20 77 he cache.** it w
39110 69 6c 6c 20 65 69 74 68 65 72 20 62 65 20 7a 65 ill either be ze
39120 72 6f 65 64 2c 20 6f 72 20 63 6f 6e 74 61 69 6e roed, or contain
39130 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 20 74 the same data t
39140 68 61 74 20 69 74 20 64 69 64 20 77 68 65 6e 20 hat it did when
39150 69 74 0a 2a 2a 20 77 61 73 20 75 6e 70 69 6e 6e it.** was unpinn
39160 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 ed..**.** The ca
39170 63 68 65 20 69 73 20 6e 6f 74 20 72 65 71 75 69 che is not requi
39180 72 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 61 red to perform a
39190 6e 79 20 72 65 66 65 72 65 6e 63 65 20 63 6f 75 ny reference cou
391a0 6e 74 69 6e 67 2e 20 41 20 73 69 6e 67 6c 65 20 nting. A single
391b0 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 55 6e 70 .** call to xUnp
391c0 69 6e 28 29 20 75 6e 70 69 6e 73 20 74 68 65 20 in() unpins the
391d0 70 61 67 65 20 72 65 67 61 72 64 6c 65 73 73 20 page regardless
391e0 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 of the number of
391f0 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 0a 2a 2a prior calls .**
39200 20 74 6f 20 78 46 65 74 63 68 28 29 2e 0a 2a 2a to xFetch()..**
39210 0a 2a 2a 20 54 68 65 20 78 52 65 6b 65 79 28 29 .** The xRekey()
39220 20 6d 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 method is used
39230 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6b 65 to change the ke
39240 79 20 76 61 6c 75 65 20 61 73 73 6f 63 69 61 74 y value associat
39250 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 70 ed with the.** p
39260 61 67 65 20 70 61 73 73 65 64 20 61 73 20 74 68 age passed as th
39270 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
39280 74 20 66 72 6f 6d 20 6f 6c 64 4b 65 79 20 74 6f t from oldKey to
39290 20 6e 65 77 4b 65 79 2e 20 49 66 20 74 68 65 20 newKey. If the
392a0 63 61 63 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 cache.** previou
392b0 73 6c 79 20 63 6f 6e 74 61 69 6e 73 20 61 6e 20 sly contains an
392c0 65 6e 74 72 79 20 61 73 73 6f 63 69 61 74 65 64 entry associated
392d0 20 77 69 74 68 20 6e 65 77 4b 65 79 2c 20 69 74 with newKey, it
392e0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 69 should be.** di
392f0 73 63 61 72 64 65 64 2e 20 41 6e 79 20 70 72 69 scarded. Any pri
39300 6f 72 20 63 61 63 68 65 20 65 6e 74 72 79 20 61 or cache entry a
39310 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 6e ssociated with n
39320 65 77 4b 65 79 20 69 73 20 67 75 61 72 61 6e 74 ewKey is guarant
39330 65 65 64 20 6e 6f 74 0a 2a 2a 20 74 6f 20 62 65 eed not.** to be
39340 20 70 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 pinned..**.** W
39350 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 hen SQLite calls
39360 20 74 68 65 20 78 54 72 75 6e 63 61 74 65 28 29 the xTruncate()
39370 20 6d 65 74 68 6f 64 2c 20 74 68 65 20 63 61 63 method, the cac
39380 68 65 20 6d 75 73 74 20 64 69 73 63 61 72 64 20 he must discard
39390 61 6c 6c 0a 2a 2a 20 65 78 69 73 74 69 6e 67 20 all.** existing
393a0 63 61 63 68 65 20 65 6e 74 72 69 65 73 20 77 69 cache entries wi
393b0 74 68 20 70 61 67 65 20 6e 75 6d 62 65 72 73 20 th page numbers
393c0 28 6b 65 79 73 29 20 67 72 65 61 74 65 72 20 74 (keys) greater t
393d0 68 61 6e 20 6f 72 20 65 71 75 61 6c 0a 2a 2a 20 han or equal.**
393e0 74 6f 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 to the value of
393f0 74 68 65 20 69 4c 69 6d 69 74 20 70 61 72 61 6d the iLimit param
39400 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 78 eter passed to x
39410 54 72 75 6e 63 61 74 65 28 29 2e 20 49 66 20 61 Truncate(). If a
39420 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 70 ny.** of these p
39430 61 67 65 73 20 61 72 65 20 70 69 6e 6e 65 64 2c ages are pinned,
39440 20 74 68 65 79 20 61 72 65 20 69 6d 70 6c 69 63 they are implic
39450 69 74 6c 79 20 75 6e 70 69 6e 6e 65 64 2c 20 6d itly unpinned, m
39460 65 61 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 74 eaning that.** t
39470 68 65 79 20 63 61 6e 20 62 65 20 73 61 66 65 6c hey can be safel
39480 79 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 0a y discarded..**.
39490 2a 2a 20 54 68 65 20 78 44 65 73 74 72 6f 79 28 ** The xDestroy(
394a0 29 20 6d 65 74 68 6f 64 20 69 73 20 75 73 65 64 ) method is used
394b0 20 74 6f 20 64 65 6c 65 74 65 20 61 20 63 61 63 to delete a cac
394c0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 he allocated by
394d0 78 43 72 65 61 74 65 28 29 2e 0a 2a 2a 20 41 6c xCreate()..** Al
394e0 6c 20 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f l resources asso
394f0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
39500 73 70 65 63 69 66 69 65 64 20 63 61 63 68 65 20 specified cache
39510 73 68 6f 75 6c 64 20 62 65 20 66 72 65 65 64 2e should be freed.
39520 20 41 66 74 65 72 0a 2a 2a 20 63 61 6c 6c 69 6e After.** callin
39530 67 20 74 68 65 20 78 44 65 73 74 72 6f 79 28 29 g the xDestroy()
39540 20 6d 65 74 68 6f 64 2c 20 53 51 4c 69 74 65 20 method, SQLite
39550 63 6f 6e 73 69 64 65 72 73 20 74 68 65 20 5b 73 considers the [s
39560 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a 5d 0a qlite3_pcache*].
39570 2a 2a 20 68 61 6e 64 6c 65 20 69 6e 76 61 6c 69 ** handle invali
39580 64 2c 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 d, and will not
39590 75 73 65 20 69 74 20 77 69 74 68 20 61 6e 79 20 use it with any
395a0 6f 74 68 65 72 20 73 71 6c 69 74 65 33 5f 70 63 other sqlite3_pc
395b0 61 63 68 65 5f 6d 65 74 68 6f 64 73 0a 2a 2a 20 ache_methods.**
395c0 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 functions..*/.ty
395d0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
395e0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
395f0 6f 64 73 20 73 71 6c 69 74 65 33 5f 70 63 61 63 ods sqlite3_pcac
39600 68 65 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 he_methods;.stru
39610 63 74 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 ct sqlite3_pcach
39620 65 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f e_methods {. vo
39630 69 64 20 2a 70 41 72 67 3b 0a 20 20 69 6e 74 20 id *pArg;. int
39640 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b (*xInit)(void*);
39650 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 . void (*xShutd
39660 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 0a 20 20 73 own)(void*);. s
39670 71 6c 69 74 65 33 5f 70 63 61 63 68 65 20 2a 28 qlite3_pcache *(
39680 2a 78 43 72 65 61 74 65 29 28 69 6e 74 20 73 7a *xCreate)(int sz
39690 50 61 67 65 2c 20 69 6e 74 20 62 50 75 72 67 65 Page, int bPurge
396a0 61 62 6c 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a able);. void (*
396b0 78 43 61 63 68 65 73 69 7a 65 29 28 73 71 6c 69 xCachesize)(sqli
396c0 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 69 6e 74 te3_pcache*, int
396d0 20 6e 43 61 63 68 65 73 69 7a 65 29 3b 0a 20 20 nCachesize);.
396e0 69 6e 74 20 28 2a 78 50 61 67 65 63 6f 75 6e 74 int (*xPagecount
396f0 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 )(sqlite3_pcache
39700 2a 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 46 *);. void *(*xF
39710 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 70 63 etch)(sqlite3_pc
39720 61 63 68 65 2a 2c 20 75 6e 73 69 67 6e 65 64 20 ache*, unsigned
39730 6b 65 79 2c 20 69 6e 74 20 63 72 65 61 74 65 46 key, int createF
39740 6c 61 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 lag);. void (*x
39750 55 6e 70 69 6e 29 28 73 71 6c 69 74 65 33 5f 70 Unpin)(sqlite3_p
39760 63 61 63 68 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 cache*, void*, i
39770 6e 74 20 64 69 73 63 61 72 64 29 3b 0a 20 20 76 nt discard);. v
39780 6f 69 64 20 28 2a 78 52 65 6b 65 79 29 28 73 71 oid (*xRekey)(sq
39790 6c 69 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 76 lite3_pcache*, v
397a0 6f 69 64 2a 2c 20 75 6e 73 69 67 6e 65 64 20 6f oid*, unsigned o
397b0 6c 64 4b 65 79 2c 20 75 6e 73 69 67 6e 65 64 20 ldKey, unsigned
397c0 6e 65 77 4b 65 79 29 3b 0a 20 20 76 6f 69 64 20 newKey);. void
397d0 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c (*xTruncate)(sql
397e0 69 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 75 6e ite3_pcache*, un
397f0 73 69 67 6e 65 64 20 69 4c 69 6d 69 74 29 3b 0a signed iLimit);.
39800 20 20 76 6f 69 64 20 28 2a 78 44 65 73 74 72 6f void (*xDestro
39810 79 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 y)(sqlite3_pcach
39820 65 2a 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 e*);.};../*.** C
39830 41 50 49 33 52 45 46 3a 20 4f 6e 6c 69 6e 65 20 API3REF: Online
39840 42 61 63 6b 75 70 20 4f 62 6a 65 63 74 0a 2a 2a Backup Object.**
39850 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
39860 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
39870 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 20 72 65 backup object re
39880 63 6f 72 64 73 20 73 74 61 74 65 20 69 6e 66 6f cords state info
39890 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 6e rmation about an
398a0 20 6f 6e 67 6f 69 6e 67 0a 2a 2a 20 6f 6e 6c 69 ongoing.** onli
398b0 6e 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 ne backup operat
398c0 69 6f 6e 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ion. The sqlite
398d0 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 20 3_backup object
398e0 69 73 20 63 72 65 61 74 65 64 20 62 79 0a 2a 2a is created by.**
398f0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
39900 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 te3_backup_init(
39910 29 5d 20 61 6e 64 20 69 73 20 64 65 73 74 72 6f )] and is destro
39920 79 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f yed by a call to
39930 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 .** [sqlite3_bac
39940 6b 75 70 5f 66 69 6e 69 73 68 28 29 5d 2e 0a 2a kup_finish()]..*
39950 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 5b *.** See Also: [
39960 55 73 69 6e 67 20 74 68 65 20 53 51 4c 69 74 65 Using the SQLite
39970 20 4f 6e 6c 69 6e 65 20 42 61 63 6b 75 70 20 41 Online Backup A
39980 50 49 5d 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 PI].*/.typedef s
39990 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 61 truct sqlite3_ba
399a0 63 6b 75 70 20 73 71 6c 69 74 65 33 5f 62 61 63 ckup sqlite3_bac
399b0 6b 75 70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 kup;../*.** CAPI
399c0 33 52 45 46 3a 20 4f 6e 6c 69 6e 65 20 42 61 63 3REF: Online Bac
399d0 6b 75 70 20 41 50 49 2e 0a 2a 2a 20 45 58 50 45 kup API..** EXPE
399e0 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
399f0 68 69 73 20 41 50 49 20 69 73 20 75 73 65 64 20 his API is used
39a00 74 6f 20 6f 76 65 72 77 72 69 74 65 20 74 68 65 to overwrite the
39a10 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 6f 6e 65 contents of one
39a20 20 64 61 74 61 62 61 73 65 20 77 69 74 68 20 74 database with t
39a30 68 61 74 0a 2a 2a 20 6f 66 20 61 6e 6f 74 68 65 hat.** of anothe
39a40 72 2e 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 r. It is useful
39a50 65 69 74 68 65 72 20 66 6f 72 20 63 72 65 61 74 either for creat
39a60 69 6e 67 20 62 61 63 6b 75 70 73 20 6f 66 20 64 ing backups of d
39a70 61 74 61 62 61 73 65 73 20 6f 72 0a 2a 2a 20 66 atabases or.** f
39a80 6f 72 20 63 6f 70 79 69 6e 67 20 69 6e 2d 6d 65 or copying in-me
39a90 6d 6f 72 79 20 64 61 74 61 62 61 73 65 73 20 74 mory databases t
39aa0 6f 20 6f 72 20 66 72 6f 6d 20 70 65 72 73 69 73 o or from persis
39ab0 74 65 6e 74 20 66 69 6c 65 73 2e 20 0a 2a 2a 0a tent files. .**.
39ac0 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 5b 55 73 ** See Also: [Us
39ad0 69 6e 67 20 74 68 65 20 53 51 4c 69 74 65 20 4f ing the SQLite O
39ae0 6e 6c 69 6e 65 20 42 61 63 6b 75 70 20 41 50 49 nline Backup API
39af0 5d 0a 2a 2a 0a 2a 2a 20 45 78 63 6c 75 73 69 76 ].**.** Exclusiv
39b00 65 20 61 63 63 65 73 73 20 69 73 20 72 65 71 75 e access is requ
39b10 69 72 65 64 20 74 6f 20 74 68 65 20 64 65 73 74 ired to the dest
39b20 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 ination database
39b30 20 66 6f 72 20 74 68 65 20 0a 2a 2a 20 64 75 72 for the .** dur
39b40 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 6f 70 65 ation of the ope
39b50 72 61 74 69 6f 6e 2e 20 48 6f 77 65 76 65 72 20 ration. However
39b60 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 the source datab
39b70 61 73 65 20 69 73 20 6f 6e 6c 79 0a 2a 2a 20 72 ase is only.** r
39b80 65 61 64 2d 6c 6f 63 6b 65 64 20 77 68 69 6c 65 ead-locked while
39b90 20 69 74 20 69 73 20 61 63 74 75 61 6c 6c 79 20 it is actually
39ba0 62 65 69 6e 67 20 72 65 61 64 2c 20 69 74 20 69 being read, it i
39bb0 73 20 6e 6f 74 20 6c 6f 63 6b 65 64 0a 2a 2a 20 s not locked.**
39bc0 63 6f 6e 74 69 6e 75 6f 75 73 6c 79 20 66 6f 72 continuously for
39bd0 20 74 68 65 20 65 6e 74 69 72 65 20 6f 70 65 72 the entire oper
39be0 61 74 69 6f 6e 2e 20 54 68 75 73 2c 20 74 68 65 ation. Thus, the
39bf0 20 62 61 63 6b 75 70 20 6d 61 79 20 62 65 0a 2a backup may be.*
39c00 2a 20 70 65 72 66 6f 72 6d 65 64 20 6f 6e 20 61 * performed on a
39c10 20 6c 69 76 65 20 64 61 74 61 62 61 73 65 20 77 live database w
39c20 69 74 68 6f 75 74 20 70 72 65 76 65 6e 74 69 6e ithout preventin
39c30 67 20 6f 74 68 65 72 20 75 73 65 72 73 20 66 72 g other users fr
39c40 6f 6d 0a 2a 2a 20 77 72 69 74 69 6e 67 20 74 6f om.** writing to
39c50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f the database fo
39c60 72 20 61 6e 20 65 78 74 65 6e 64 65 64 20 70 65 r an extended pe
39c70 72 69 6f 64 20 6f 66 20 74 69 6d 65 2e 0a 2a 2a riod of time..**
39c80 20 0a 2a 2a 20 54 6f 20 70 65 72 66 6f 72 6d 20 .** To perform
39c90 61 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 a backup operati
39ca0 6f 6e 3a 20 0a 2a 2a 20 20 20 3c 6f 6c 3e 0a 2a on: .** <ol>.*
39cb0 2a 20 20 20 20 20 3c 6c 69 3e 3c 62 3e 73 71 6c * <li><b>sql
39cc0 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 ite3_backup_init
39cd0 28 29 3c 2f 62 3e 20 69 73 20 63 61 6c 6c 65 64 ()</b> is called
39ce0 20 6f 6e 63 65 20 74 6f 20 69 6e 69 74 69 61 6c once to initial
39cf0 69 7a 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ize the.**
39d00 20 20 20 62 61 63 6b 75 70 2c 20 0a 2a 2a 20 20 backup, .**
39d10 20 20 20 3c 6c 69 3e 3c 62 3e 73 71 6c 69 74 65 <li><b>sqlite
39d20 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 3c 3_backup_step()<
39d30 2f 62 3e 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e /b> is called on
39d40 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 e or more times
39d50 74 6f 20 74 72 61 6e 73 66 65 72 20 0a 2a 2a 20 to transfer .**
39d60 20 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61 the data
39d70 20 62 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f between the two
39d80 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 databases, and
39d90 66 69 6e 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 3c finally.** <
39da0 6c 69 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 li><b>sqlite3_ba
39db0 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 3c 2f 62 ckup_finish()</b
39dc0 3e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 > is called to r
39dd0 65 6c 65 61 73 65 20 61 6c 6c 20 72 65 73 6f 75 elease all resou
39de0 72 63 65 73 20 0a 2a 2a 20 20 20 20 20 20 20 20 rces .**
39df0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
39e00 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 the backup oper
39e10 61 74 69 6f 6e 2e 20 0a 2a 2a 20 20 20 3c 2f 6f ation. .** </o
39e20 6c 3e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 l>.** There shou
39e30 6c 64 20 62 65 20 65 78 61 63 74 6c 79 20 6f 6e ld be exactly on
39e40 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 e call to sqlite
39e50 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 3_backup_finish(
39e60 29 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 73 75 ) for each.** su
39e70 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
39e80 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
39e90 69 6e 69 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 init()..**.** <b
39ea0 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f >sqlite3_backup_
39eb0 69 6e 69 74 28 29 3c 2f 62 3e 0a 2a 2a 0a 2a 2a init()</b>.**.**
39ec0 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 61 The first two a
39ed0 72 67 75 6d 65 6e 74 73 20 70 61 73 73 65 64 20 rguments passed
39ee0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b to [sqlite3_back
39ef0 75 70 5f 69 6e 69 74 28 29 5d 20 61 72 65 20 74 up_init()] are t
39f00 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 he database.** h
39f10 61 6e 64 6c 65 20 61 73 73 6f 63 69 61 74 65 64 andle associated
39f20 20 77 69 74 68 20 74 68 65 20 64 65 73 74 69 6e with the destin
39f30 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 20 61 ation database a
39f40 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 nd the database
39f50 6e 61 6d 65 20 0a 2a 2a 20 75 73 65 64 20 74 6f name .** used to
39f60 20 61 74 74 61 63 68 20 74 68 65 20 64 65 73 74 attach the dest
39f70 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 ination database
39f80 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 2e 20 to the handle.
39f90 54 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d The database nam
39fa0 65 0a 2a 2a 20 69 73 20 22 6d 61 69 6e 22 20 66 e.** is "main" f
39fb0 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 or the main data
39fc0 62 61 73 65 2c 20 22 74 65 6d 70 22 20 66 6f 72 base, "temp" for
39fd0 20 74 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 the temporary d
39fe0 61 74 61 62 61 73 65 2c 20 6f 72 0a 2a 2a 20 74 atabase, or.** t
39ff0 68 65 20 6e 61 6d 65 20 73 70 65 63 69 66 69 65 he name specifie
3a000 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 d as part of the
3a010 20 5b 41 54 54 41 43 48 5d 20 73 74 61 74 65 6d [ATTACH] statem
3a020 65 6e 74 20 69 66 20 74 68 65 20 64 65 73 74 69 ent if the desti
3a030 6e 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 6e 20 nation is.** an
3a040 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
3a050 65 2e 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 e. The third and
3a060 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
3a070 73 20 70 61 73 73 65 64 20 74 6f 20 0a 2a 2a 20 s passed to .**
3a080 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 sqlite3_backup_i
3a090 6e 69 74 28 29 20 69 64 65 6e 74 69 66 79 20 74 nit() identify t
3a0a0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
3a0b0 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 61 6e 64 20 nection].** and
3a0c0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 75 73 database name us
3a0d0 65 64 0a 2a 2a 20 74 6f 20 61 63 63 65 73 73 20 ed.** to access
3a0e0 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 the source datab
3a0f0 61 73 65 2e 20 54 68 65 20 76 61 6c 75 65 73 20 ase. The values
3a100 70 61 73 73 65 64 20 66 6f 72 20 74 68 65 20 73 passed for the s
3a110 6f 75 72 63 65 20 61 6e 64 20 0a 2a 2a 20 64 65 ource and .** de
3a120 73 74 69 6e 61 74 69 6f 6e 20 5b 64 61 74 61 62 stination [datab
3a130 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
3a140 70 61 72 61 6d 65 74 65 72 73 20 6d 75 73 74 20 parameters must
3a150 6e 6f 74 20 62 65 20 74 68 65 20 73 61 6d 65 2e not be the same.
3a160 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72 .**.** If an err
3a170 6f 72 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e or occurs within
3a180 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3a190 69 6e 69 74 28 29 2c 20 74 68 65 6e 20 4e 55 4c init(), then NUL
3a1a0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a L is returned.**
3a1b0 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 63 6f and an error co
3a1c0 64 65 20 61 6e 64 20 65 72 72 6f 72 20 6d 65 73 de and error mes
3a1d0 73 61 67 65 20 77 72 69 74 74 65 6e 20 69 6e 74 sage written int
3a1e0 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 o the [database
3a1f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 0a 2a 2a 20 connection] .**
3a200 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 passed as the fi
3a210 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 rst argument. Th
3a220 65 79 20 6d 61 79 20 62 65 20 72 65 74 72 69 65 ey may be retrie
3a230 76 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a ved using the.**
3a240 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
3a250 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 e()], [sqlite3_e
3a260 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 rrmsg()], and [s
3a270 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
3a280 29 5d 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a )] functions..**
3a290 20 4f 74 68 65 72 77 69 73 65 2c 20 69 66 20 73 Otherwise, if s
3a2a0 75 63 63 65 73 73 66 75 6c 2c 20 61 20 70 6f 69 uccessful, a poi
3a2b0 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 nter to an [sqli
3a2c0 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 te3_backup] obje
3a2d0 63 74 20 69 73 0a 2a 2a 20 72 65 74 75 72 6e 65 ct is.** returne
3a2e0 64 2e 20 54 68 69 73 20 70 6f 69 6e 74 65 72 20 d. This pointer
3a2f0 6d 61 79 20 62 65 20 75 73 65 64 20 77 69 74 68 may be used with
3a300 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 61 63 the sqlite3_bac
3a310 6b 75 70 5f 73 74 65 70 28 29 20 61 6e 64 0a 2a kup_step() and.*
3a320 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 * sqlite3_backup
3a330 5f 66 69 6e 69 73 68 28 29 20 66 75 6e 63 74 69 _finish() functi
3a340 6f 6e 73 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 ons to perform t
3a350 68 65 20 73 70 65 63 69 66 69 65 64 20 62 61 63 he specified bac
3a360 6b 75 70 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f kup .** operatio
3a370 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 73 71 6c 69 n..**.** <b>sqli
3a380 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
3a390 29 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 46 75 6e 63 )</b>.**.** Func
3a3a0 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 62 61 tion [sqlite3_ba
3a3b0 63 6b 75 70 5f 73 74 65 70 28 29 5d 20 69 73 20 ckup_step()] is
3a3c0 75 73 65 64 20 74 6f 20 63 6f 70 79 20 75 70 20 used to copy up
3a3d0 74 6f 20 6e 50 61 67 65 20 70 61 67 65 73 20 62 to nPage pages b
3a3e0 65 74 77 65 65 6e 20 0a 2a 2a 20 74 68 65 20 73 etween .** the s
3a3f0 6f 75 72 63 65 20 61 6e 64 20 64 65 73 74 69 6e ource and destin
3a400 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 73 2c ation databases,
3a410 20 77 68 65 72 65 20 6e 50 61 67 65 20 69 73 20 where nPage is
3a420 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 the value of the
3a430 20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 .** second para
3a440 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 meter passed to
3a450 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 sqlite3_backup_s
3a460 74 65 70 28 29 2e 20 49 66 20 6e 50 61 67 65 20 tep(). If nPage
3a470 69 73 20 61 20 6e 65 67 61 74 69 76 65 0a 2a 2a is a negative.**
3a480 20 76 61 6c 75 65 2c 20 61 6c 6c 20 72 65 6d 61 value, all rema
3a490 69 6e 69 6e 67 20 73 6f 75 72 63 65 20 70 61 67 ining source pag
3a4a0 65 73 20 61 72 65 20 63 6f 70 69 65 64 2e 20 49 es are copied. I
3a4b0 66 20 74 68 65 20 72 65 71 75 69 72 65 64 20 70 f the required p
3a4c0 61 67 65 73 20 61 72 65 20 0a 2a 2a 20 73 75 63 ages are .** suc
3a4d0 63 65 73 66 75 6c 6c 79 20 63 6f 70 69 65 64 2c cesfully copied,
3a4e0 20 62 75 74 20 74 68 65 72 65 20 61 72 65 20 73 but there are s
3a4f0 74 69 6c 6c 20 6d 6f 72 65 20 70 61 67 65 73 20 till more pages
3a500 74 6f 20 63 6f 70 79 20 62 65 66 6f 72 65 20 74 to copy before t
3a510 68 65 20 0a 2a 2a 20 62 61 63 6b 75 70 20 69 73 he .** backup is
3a520 20 63 6f 6d 70 6c 65 74 65 2c 20 69 74 20 72 65 complete, it re
3a530 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
3a540 5d 2e 20 49 66 20 6e 6f 20 65 72 72 6f 72 20 6f ]. If no error o
3a550 63 63 75 72 65 64 20 61 6e 64 20 74 68 65 72 65 ccured and there
3a560 20 0a 2a 2a 20 61 72 65 20 6e 6f 20 6d 6f 72 65 .** are no more
3a570 20 70 61 67 65 73 20 74 6f 20 63 6f 70 79 2c 20 pages to copy,
3a580 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 44 4f 4e then [SQLITE_DON
3a590 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 E] is returned.
3a5a0 49 66 20 61 6e 20 65 72 72 6f 72 20 0a 2a 2a 20 If an error .**
3a5b0 6f 63 63 75 72 73 2c 20 74 68 65 6e 20 61 6e 20 occurs, then an
3a5c0 53 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64 SQLite error cod
3a5d0 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 41 e is returned. A
3a5e0 73 20 77 65 6c 6c 20 61 73 20 5b 53 51 4c 49 54 s well as [SQLIT
3a5f0 45 5f 4f 4b 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 E_OK] and.** [SQ
3a600 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 61 20 63 61 LITE_DONE], a ca
3a610 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 ll to sqlite3_ba
3a620 63 6b 75 70 5f 73 74 65 70 28 29 20 6d 61 79 20 ckup_step() may
3a630 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 52 return [SQLITE_R
3a640 45 41 44 4f 4e 4c 59 5d 2c 0a 2a 2a 20 5b 53 51 EADONLY],.** [SQ
3a650 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 LITE_NOMEM], [SQ
3a660 4c 49 54 45 5f 42 55 53 59 5d 2c 20 5b 53 51 4c LITE_BUSY], [SQL
3a670 49 54 45 5f 4c 4f 43 4b 45 44 5d 2c 20 6f 72 20 ITE_LOCKED], or
3a680 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f an.** [SQLITE_IO
3a690 45 52 52 5f 41 43 43 45 53 53 20 7c 20 53 51 4c ERR_ACCESS | SQL
3a6a0 49 54 45 5f 49 4f 45 52 52 5f 58 58 58 5d 20 65 ITE_IOERR_XXX] e
3a6b0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
3a6c0 64 65 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c de..**.** As wel
3a6d0 6c 20 61 73 20 74 68 65 20 63 61 73 65 20 77 68 l as the case wh
3a6e0 65 72 65 20 74 68 65 20 64 65 73 74 69 6e 61 74 ere the destinat
3a6f0 69 6f 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c ion database fil
3a700 65 20 77 61 73 20 6f 70 65 6e 65 64 20 66 6f 72 e was opened for
3a710 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 .** read-only ac
3a720 63 65 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 61 cess, sqlite3_ba
3a730 63 6b 75 70 5f 73 74 65 70 28 29 20 6d 61 79 20 ckup_step() may
3a740 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 52 return [SQLITE_R
3a750 45 41 44 4f 4e 4c 59 5d 20 69 66 0a 2a 2a 20 74 EADONLY] if.** t
3a760 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 69 he destination i
3a770 73 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 s an in-memory d
3a780 61 74 61 62 61 73 65 20 77 69 74 68 20 61 20 64 atabase with a d
3a790 69 66 66 65 72 65 6e 74 20 70 61 67 65 20 73 69 ifferent page si
3a7a0 7a 65 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 ze.** from the s
3a7b0 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 2e 0a ource database..
3a7c0 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 **.** If sqlite3
3a7d0 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 63 _backup_step() c
3a7e0 61 6e 6e 6f 74 20 6f 62 74 61 69 6e 20 61 20 72 annot obtain a r
3a7f0 65 71 75 69 72 65 64 20 66 69 6c 65 2d 73 79 73 equired file-sys
3a800 74 65 6d 20 6c 6f 63 6b 2c 20 74 68 65 6e 0a 2a tem lock, then.*
3a810 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 * the [sqlite3_b
3a820 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 usy_handler | bu
3a830 73 79 2d 68 61 6e 64 6c 65 72 20 66 75 6e 63 74 sy-handler funct
3a840 69 6f 6e 5d 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b ion].** is invok
3a850 65 64 20 28 69 66 20 6f 6e 65 20 69 73 20 73 70 ed (if one is sp
3a860 65 63 69 66 69 65 64 29 2e 20 49 66 20 74 68 65 ecified). If the
3a870 20 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 .** busy-handle
3a880 72 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 r returns non-ze
3a890 72 6f 20 62 65 66 6f 72 65 20 74 68 65 20 6c 6f ro before the lo
3a8a0 63 6b 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2c ck is available,
3a8b0 20 74 68 65 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 then .** [SQLIT
3a8c0 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 E_BUSY] is retur
3a8d0 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 ned to the calle
3a8e0 72 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 r. In this case
3a8f0 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 the call to.** s
3a900 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3a910 65 70 28 29 20 63 61 6e 20 62 65 20 72 65 74 72 ep() can be retr
3a920 69 65 64 20 6c 61 74 65 72 2e 20 49 66 20 74 68 ied later. If th
3a930 65 20 73 6f 75 72 63 65 0a 2a 2a 20 5b 64 61 74 e source.** [dat
3a940 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3a950 5d 0a 2a 2a 20 69 73 20 62 65 69 6e 67 20 75 73 ].** is being us
3a960 65 64 20 74 6f 20 77 72 69 74 65 20 74 6f 20 74 ed to write to t
3a970 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 he source databa
3a980 73 65 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f se when sqlite3_
3a990 62 61 63 6b 75 70 5f 73 74 65 70 28 29 0a 2a 2a backup_step().**
3a9a0 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e is called, then
3a9b0 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5d [SQLITE_LOCKED]
3a9c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d is returned imm
3a9d0 65 64 69 61 74 65 6c 79 2e 20 41 67 61 69 6e 2c ediately. Again,
3a9e0 20 69 6e 20 74 68 69 73 0a 2a 2a 20 63 61 73 65 in this.** case
3a9f0 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c the call to sql
3aa00 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3aa10 28 29 20 63 61 6e 20 62 65 20 72 65 74 72 69 65 () can be retrie
3aa20 64 20 6c 61 74 65 72 20 6f 6e 2e 20 49 66 0a 2a d later on. If.*
3aa30 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f * [SQLITE_IOERR_
3aa40 41 43 43 45 53 53 20 7c 20 53 51 4c 49 54 45 5f ACCESS | SQLITE_
3aa50 49 4f 45 52 52 5f 58 58 58 5d 2c 20 5b 53 51 4c IOERR_XXX], [SQL
3aa60 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 6f 72 0a 2a ITE_NOMEM], or.*
3aa70 2a 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e * [SQLITE_READON
3aa80 4c 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2c LY] is returned,
3aa90 20 74 68 65 6e 20 0a 2a 2a 20 74 68 65 72 65 20 then .** there
3aaa0 69 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e 20 72 is no point in r
3aab0 65 74 72 79 69 6e 67 20 74 68 65 20 63 61 6c 6c etrying the call
3aac0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b to sqlite3_back
3aad0 75 70 5f 73 74 65 70 28 29 2e 20 54 68 65 73 65 up_step(). These
3aae0 20 0a 2a 2a 20 65 72 72 6f 72 73 20 61 72 65 20 .** errors are
3aaf0 63 6f 6e 73 69 64 65 72 65 64 20 66 61 74 61 6c considered fatal
3ab00 2e 20 41 74 20 74 68 69 73 20 70 6f 69 6e 74 20 . At this point
3ab10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
3ab20 6d 75 73 74 20 61 63 63 65 70 74 20 0a 2a 2a 20 must accept .**
3ab30 74 68 61 74 20 74 68 65 20 62 61 63 6b 75 70 20 that the backup
3ab40 6f 70 65 72 61 74 69 6f 6e 20 68 61 73 20 66 61 operation has fa
3ab50 69 6c 65 64 20 61 6e 64 20 70 61 73 73 20 74 68 iled and pass th
3ab60 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 e backup operati
3ab70 6f 6e 20 68 61 6e 64 6c 65 20 0a 2a 2a 20 74 6f on handle .** to
3ab80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 61 63 the sqlite3_bac
3ab90 6b 75 70 5f 66 69 6e 69 73 68 28 29 20 74 6f 20 kup_finish() to
3aba0 72 65 6c 65 61 73 65 20 61 73 73 6f 63 69 61 74 release associat
3abb0 65 64 20 72 65 73 6f 75 72 63 65 73 2e 0a 2a 2a ed resources..**
3abc0 0a 2a 2a 20 46 6f 6c 6c 6f 77 69 6e 67 20 74 68 .** Following th
3abd0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 e first call to
3abe0 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 sqlite3_backup_s
3abf0 74 65 70 28 29 2c 20 61 6e 20 65 78 63 6c 75 73 tep(), an exclus
3ac00 69 76 65 20 6c 6f 63 6b 20 69 73 0a 2a 2a 20 6f ive lock is.** o
3ac10 62 74 61 69 6e 65 64 20 6f 6e 20 74 68 65 20 64 btained on the d
3ac20 65 73 74 69 6e 61 74 69 6f 6e 20 66 69 6c 65 2e estination file.
3ac30 20 49 74 20 69 73 20 6e 6f 74 20 72 65 6c 65 61 It is not relea
3ac40 73 65 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 sed until either
3ac50 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 .** sqlite3_bac
3ac60 6b 75 70 5f 66 69 6e 69 73 68 28 29 20 69 73 20 kup_finish() is
3ac70 63 61 6c 6c 65 64 20 6f 72 20 74 68 65 20 62 61 called or the ba
3ac80 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 20 69 ckup operation i
3ac90 73 20 63 6f 6d 70 6c 65 74 65 20 0a 2a 2a 20 61 s complete .** a
3aca0 6e 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 nd sqlite3_backu
3acb0 70 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 73 p_step() returns
3acc0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 [SQLITE_DONE].
3acd0 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 65 61 Additionally, ea
3ace0 63 68 20 74 69 6d 65 20 0a 2a 2a 20 61 20 63 61 ch time .** a ca
3acf0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 ll to sqlite3_ba
3ad00 63 6b 75 70 5f 73 74 65 70 28 29 20 69 73 20 6d ckup_step() is m
3ad10 61 64 65 20 61 20 5b 73 68 61 72 65 64 20 6c 6f ade a [shared lo
3ad20 63 6b 5d 20 69 73 20 6f 62 74 61 69 6e 65 64 20 ck] is obtained
3ad30 6f 6e 0a 2a 2a 20 74 68 65 20 73 6f 75 72 63 65 on.** the source
3ad40 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 database file.
3ad50 54 68 69 73 20 6c 6f 63 6b 20 69 73 20 72 65 6c This lock is rel
3ad60 65 61 73 65 64 20 62 65 66 6f 72 65 20 74 68 65 eased before the
3ad70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b .** sqlite3_back
3ad80 75 70 5f 73 74 65 70 28 29 20 63 61 6c 6c 20 72 up_step() call r
3ad90 65 74 75 72 6e 73 2e 20 42 65 63 61 75 73 65 20 eturns. Because
3ada0 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 the source datab
3adb0 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 6c 6f ase is not.** lo
3adc0 63 6b 65 64 20 62 65 74 77 65 65 6e 20 63 61 6c cked between cal
3add0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 ls to sqlite3_ba
3ade0 63 6b 75 70 5f 73 74 65 70 28 29 2c 20 69 74 20 ckup_step(), it
3adf0 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65 64 20 may be modified
3ae00 6d 69 64 2d 77 61 79 0a 2a 2a 20 74 68 72 6f 75 mid-way.** throu
3ae10 67 68 20 74 68 65 20 62 61 63 6b 75 70 20 70 72 gh the backup pr
3ae20 6f 63 65 64 75 72 65 2e 20 49 66 20 74 68 65 20 ocedure. If the
3ae30 73 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 20 source database
3ae40 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 is modified by a
3ae50 6e 0a 2a 2a 20 65 78 74 65 72 6e 61 6c 20 70 72 n.** external pr
3ae60 6f 63 65 73 73 20 6f 72 20 76 69 61 20 61 20 64 ocess or via a d
3ae70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3ae80 6f 6e 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 on other than th
3ae90 65 20 6f 6e 65 20 62 65 69 6e 67 0a 2a 2a 20 75 e one being.** u
3aea0 73 65 64 20 62 79 20 74 68 65 20 62 61 63 6b 75 sed by the backu
3aeb0 70 20 6f 70 65 72 61 74 69 6f 6e 2c 20 74 68 65 p operation, the
3aec0 6e 20 74 68 65 20 62 61 63 6b 75 70 20 77 69 6c n the backup wil
3aed0 6c 20 62 65 20 74 72 61 6e 73 70 61 72 65 6e 74 l be transparent
3aee0 6c 79 0a 2a 2a 20 72 65 73 74 61 72 74 65 64 20 ly.** restarted
3aef0 62 79 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c by the next call
3af00 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b to sqlite3_back
3af10 75 70 5f 73 74 65 70 28 29 2e 20 49 66 20 74 68 up_step(). If th
3af20 65 20 73 6f 75 72 63 65 20 0a 2a 2a 20 64 61 74 e source .** dat
3af30 61 62 61 73 65 20 69 73 20 6d 6f 64 69 66 69 65 abase is modifie
3af40 64 20 62 79 20 74 68 65 20 75 73 69 6e 67 20 74 d by the using t
3af50 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
3af60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 73 20 69 connection as i
3af70 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 s used.** by the
3af80 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f backup operatio
3af90 6e 2c 20 74 68 65 6e 20 74 68 65 20 62 61 63 6b n, then the back
3afa0 75 70 20 64 61 74 61 62 61 73 65 20 69 73 20 74 up database is t
3afb0 72 61 6e 73 70 61 72 65 6e 74 6c 79 20 0a 2a 2a ransparently .**
3afc0 20 75 70 64 61 74 65 64 20 61 74 20 74 68 65 20 updated at the
3afd0 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a same time..**.**
3afe0 20 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b <b>sqlite3_back
3aff0 75 70 5f 66 69 6e 69 73 68 28 29 3c 2f 62 3e 0a up_finish()</b>.
3b000 2a 2a 0a 2a 2a 20 4f 6e 63 65 20 73 71 6c 69 74 **.** Once sqlit
3b010 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3b020 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 has returned [S
3b030 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 6f 72 20 QLITE_DONE], or
3b040 77 68 65 6e 20 74 68 65 20 0a 2a 2a 20 61 70 70 when the .** app
3b050 6c 69 63 61 74 69 6f 6e 20 77 69 73 68 65 73 20 lication wishes
3b060 74 6f 20 61 62 61 6e 64 6f 6e 20 74 68 65 20 62 to abandon the b
3b070 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 2c ackup operation,
3b080 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 61 the [sqlite3_ba
3b090 63 6b 75 70 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 ckup].** object
3b0a0 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 should be passed
3b0b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b to sqlite3_back
3b0c0 75 70 5f 66 69 6e 69 73 68 28 29 2e 20 54 68 69 up_finish(). Thi
3b0d0 73 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a s releases all.*
3b0e0 2a 20 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f * resources asso
3b0f0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
3b100 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e backup operation
3b110 2e 20 49 66 20 73 71 6c 69 74 65 33 5f 62 61 63 . If sqlite3_bac
3b120 6b 75 70 5f 73 74 65 70 28 29 0a 2a 2a 20 68 61 kup_step().** ha
3b130 73 20 6e 6f 74 20 79 65 74 20 72 65 74 75 72 6e s not yet return
3b140 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d ed [SQLITE_DONE]
3b150 2c 20 74 68 65 6e 20 61 6e 79 20 61 63 74 69 76 , then any activ
3b160 65 20 77 72 69 74 65 2d 74 72 61 6e 73 61 63 74 e write-transact
3b170 69 6f 6e 20 6f 6e 20 74 68 65 0a 2a 2a 20 64 65 ion on the.** de
3b180 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 stination databa
3b190 73 65 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 se is rolled bac
3b1a0 6b 2e 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f k. The [sqlite3_
3b1b0 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 20 69 backup] object i
3b1c0 73 20 69 6e 76 61 6c 69 64 0a 2a 2a 20 61 6e 64 s invalid.** and
3b1d0 20 6d 61 79 20 6e 6f 74 20 62 65 20 75 73 65 64 may not be used
3b1e0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c following a cal
3b1f0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 l to sqlite3_bac
3b200 6b 75 70 5f 66 69 6e 69 73 68 28 29 2e 0a 2a 2a kup_finish()..**
3b210 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 .** The value re
3b220 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
3b230 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 3_backup_finish
3b240 69 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 is [SQLITE_OK] i
3b250 66 20 6e 6f 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 f no error.** oc
3b260 63 75 72 72 65 64 2c 20 72 65 67 61 72 64 6c 65 curred, regardle
3b270 73 73 20 6f 72 20 77 68 65 74 68 65 72 20 6f 72 ss or whether or
3b280 20 6e 6f 74 20 73 71 6c 69 74 65 33 5f 62 61 63 not sqlite3_bac
3b290 6b 75 70 5f 73 74 65 70 28 29 20 77 61 73 20 63 kup_step() was c
3b2a0 61 6c 6c 65 64 0a 2a 2a 20 61 20 73 75 66 66 69 alled.** a suffi
3b2b0 63 69 65 6e 74 20 6e 75 6d 62 65 72 20 6f 66 20 cient number of
3b2c0 74 69 6d 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 times to complet
3b2d0 65 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 e the backup ope
3b2e0 72 61 74 69 6f 6e 2e 20 4f 72 2c 20 69 66 0a 2a ration. Or, if.*
3b2f0 2a 20 61 6e 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f * an out-of-memo
3b300 72 79 20 63 6f 6e 64 69 74 69 6f 6e 20 6f 72 20 ry condition or
3b310 49 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 65 64 IO error occured
3b320 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 during a call t
3b330 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 o.** sqlite3_bac
3b340 6b 75 70 5f 73 74 65 70 28 29 20 74 68 65 6e 20 kup_step() then
3b350 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 6f [SQLITE_NOMEM] o
3b360 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f r an.** [SQLITE_
3b370 49 4f 45 52 52 5f 41 43 43 45 53 53 20 7c 20 53 IOERR_ACCESS | S
3b380 51 4c 49 54 45 5f 49 4f 45 52 52 5f 58 58 58 5d QLITE_IOERR_XXX]
3b390 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 69 error code.** i
3b3a0 73 20 72 65 74 75 72 6e 65 64 2e 20 49 6e 20 74 s returned. In t
3b3b0 68 69 73 20 63 61 73 65 20 74 68 65 20 65 72 72 his case the err
3b3c0 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 or code and an e
3b3d0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 61 72 65 rror message are
3b3e0 0a 2a 2a 20 77 72 69 74 74 65 6e 20 74 6f 20 74 .** written to t
3b3f0 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 5b he destination [
3b400 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3b410 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 ion]..**.** A re
3b420 74 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f turn of [SQLITE_
3b430 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 BUSY] or [SQLITE
3b440 5f 4c 4f 43 4b 45 44 5d 20 66 72 6f 6d 20 73 71 _LOCKED] from sq
3b450 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3b460 70 28 29 20 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 p() is.** not a
3b470 70 65 72 6d 61 6e 65 6e 74 20 65 72 72 6f 72 20 permanent error
3b480 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 and does not aff
3b490 65 63 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 ect the return v
3b4a0 61 6c 75 65 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 alue of.** sqlit
3b4b0 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 e3_backup_finish
3b4c0 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 73 71 6c ()..**.** <b>sql
3b4d0 69 74 65 33 5f 62 61 63 6b 75 70 5f 72 65 6d 61 ite3_backup_rema
3b4e0 69 6e 69 6e 67 28 29 2c 20 73 71 6c 69 74 65 33 ining(), sqlite3
3b4f0 5f 62 61 63 6b 75 70 5f 70 61 67 65 63 6f 75 6e _backup_pagecoun
3b500 74 28 29 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 45 61 t()</b>.**.** Ea
3b510 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ch call to sqlit
3b520 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3b530 20 73 65 74 73 20 74 77 6f 20 76 61 6c 75 65 73 sets two values
3b540 20 73 74 6f 72 65 64 20 69 6e 74 65 72 6e 61 6c stored internal
3b550 6c 79 0a 2a 2a 20 62 79 20 61 6e 20 5b 73 71 6c ly.** by an [sql
3b560 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a ite3_backup] obj
3b570 65 63 74 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 ect. The number
3b580 6f 66 20 70 61 67 65 73 20 73 74 69 6c 6c 20 74 of pages still t
3b590 6f 20 62 65 20 62 61 63 6b 65 64 0a 2a 2a 20 75 o be backed.** u
3b5a0 70 2c 20 77 68 69 63 68 20 6d 61 79 20 62 65 20 p, which may be
3b5b0 71 75 65 72 69 65 64 20 62 79 20 73 71 6c 69 74 queried by sqlit
3b5c0 65 33 5f 62 61 63 6b 75 70 5f 72 65 6d 61 69 6e e3_backup_remain
3b5d0 69 6e 67 28 29 2c 20 61 6e 64 20 74 68 65 20 74 ing(), and the t
3b5e0 6f 74 61 6c 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f otal.** number o
3b5f0 66 20 70 61 67 65 73 20 69 6e 20 74 68 65 20 73 f pages in the s
3b600 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 20 66 ource database f
3b610 69 6c 65 2c 20 77 68 69 63 68 20 6d 61 79 20 62 ile, which may b
3b620 65 20 71 75 65 72 69 65 64 20 62 79 0a 2a 2a 20 e queried by.**
3b630 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 70 sqlite3_backup_p
3b640 61 67 65 63 6f 75 6e 74 28 29 2e 0a 2a 2a 0a 2a agecount()..**.*
3b650 2a 20 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 * The values ret
3b660 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 66 urned by these f
3b670 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 6f 6e 6c unctions are onl
3b680 79 20 75 70 64 61 74 65 64 20 62 79 0a 2a 2a 20 y updated by.**
3b690 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 sqlite3_backup_s
3b6a0 74 65 70 28 29 2e 20 49 66 20 74 68 65 20 73 6f tep(). If the so
3b6b0 75 72 63 65 20 64 61 74 61 62 61 73 65 20 69 73 urce database is
3b6c0 20 6d 6f 64 69 66 69 65 64 20 64 75 72 69 6e 67 modified during
3b6d0 20 61 20 62 61 63 6b 75 70 0a 2a 2a 20 6f 70 65 a backup.** ope
3b6e0 72 61 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 ration, then the
3b6f0 20 76 61 6c 75 65 73 20 61 72 65 20 6e 6f 74 20 values are not
3b700 75 70 64 61 74 65 64 20 74 6f 20 61 63 63 6f 75 updated to accou
3b710 6e 74 20 66 6f 72 20 61 6e 79 20 65 78 74 72 61 nt for any extra
3b720 0a 2a 2a 20 70 61 67 65 73 20 74 68 61 74 20 6e .** pages that n
3b730 65 65 64 20 74 6f 20 62 65 20 75 70 64 61 74 65 eed to be update
3b740 64 20 6f 72 20 74 68 65 20 73 69 7a 65 20 6f 66 d or the size of
3b750 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 the source data
3b760 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 63 68 61 base file.** cha
3b770 6e 67 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e nging..**.** <b>
3b780 43 6f 6e 63 75 72 72 65 6e 74 20 55 73 61 67 65 Concurrent Usage
3b790 20 6f 66 20 44 61 74 61 62 61 73 65 20 48 61 6e of Database Han
3b7a0 64 6c 65 73 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 dles</b>.**.** T
3b7b0 68 65 20 73 6f 75 72 63 65 20 5b 64 61 74 61 62 he source [datab
3b7c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
3b7d0 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 74 may be used by t
3b7e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 he application f
3b7f0 6f 72 20 6f 74 68 65 72 0a 2a 2a 20 70 75 72 70 or other.** purp
3b800 6f 73 65 73 20 77 68 69 6c 65 20 61 20 62 61 63 oses while a bac
3b810 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 kup operation is
3b820 20 75 6e 64 65 72 77 61 79 20 6f 72 20 62 65 69 underway or bei
3b830 6e 67 20 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a ng initialized..
3b840 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 ** If SQLite is
3b850 63 6f 6d 70 69 6c 65 64 20 61 6e 64 20 63 6f 6e compiled and con
3b860 66 69 67 75 72 65 64 20 74 6f 20 73 75 70 70 6f figured to suppo
3b870 72 74 20 74 68 72 65 61 64 73 61 66 65 20 64 61 rt threadsafe da
3b880 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
3b890 74 69 6f 6e 73 2c 20 74 68 65 6e 20 74 68 65 20 tions, then the
3b8a0 73 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 20 source database
3b8b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 61 79 20 62 connection may b
3b8c0 65 20 75 73 65 64 20 63 6f 6e 63 75 72 72 65 6e e used concurren
3b8d0 74 6c 79 0a 2a 2a 20 66 72 6f 6d 20 77 69 74 68 tly.** from with
3b8e0 69 6e 20 6f 74 68 65 72 20 74 68 72 65 61 64 73 in other threads
3b8f0 2e 0a 2a 2a 0a 2a 2a 20 48 6f 77 65 76 65 72 2c ..**.** However,
3b900 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
3b910 20 6d 75 73 74 20 67 75 61 72 61 6e 74 65 65 20 must guarantee
3b920 74 68 61 74 20 74 68 65 20 64 65 73 74 69 6e 61 that the destina
3b930 74 69 6f 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a tion database.**
3b940 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 connection hand
3b950 6c 65 20 69 73 20 6e 6f 74 20 70 61 73 73 65 64 le is not passed
3b960 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 41 50 to any other AP
3b970 49 20 28 62 79 20 61 6e 79 20 74 68 72 65 61 64 I (by any thread
3b980 29 20 61 66 74 65 72 20 0a 2a 2a 20 73 71 6c 69 ) after .** sqli
3b990 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 te3_backup_init(
3b9a0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 20 ) is called and
3b9b0 62 65 66 6f 72 65 20 74 68 65 20 63 6f 72 72 65 before the corre
3b9c0 73 70 6f 6e 64 69 6e 67 20 63 61 6c 6c 20 74 6f sponding call to
3b9d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b .** sqlite3_back
3b9e0 75 70 5f 66 69 6e 69 73 68 28 29 2e 20 55 6e 66 up_finish(). Unf
3b9f0 6f 72 74 75 6e 61 74 65 6c 79 20 53 51 4c 69 74 ortunately SQLit
3ba00 65 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 e does not curre
3ba10 6e 74 6c 79 20 63 68 65 63 6b 0a 2a 2a 20 66 6f ntly check.** fo
3ba20 72 20 74 68 69 73 2c 20 69 66 20 74 68 65 20 61 r this, if the a
3ba30 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 pplication does
3ba40 75 73 65 20 74 68 65 20 64 65 73 74 69 6e 61 74 use the destinat
3ba50 69 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f ion [database co
3ba60 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 66 6f 72 nnection].** for
3ba70 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 75 72 70 some other purp
3ba80 6f 73 65 20 64 75 72 69 6e 67 20 61 20 62 61 63 ose during a bac
3ba90 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 2c 20 74 kup operation, t
3baa0 68 69 6e 67 73 20 6d 61 79 20 61 70 70 65 61 72 hings may appear
3bab0 20 74 6f 0a 2a 2a 20 77 6f 72 6b 20 63 6f 72 72 to.** work corr
3bac0 65 63 74 6c 79 20 62 75 74 20 69 6e 20 66 61 63 ectly but in fac
3bad0 74 20 62 65 20 73 75 62 74 6c 79 20 6d 61 6c 66 t be subtly malf
3bae0 75 6e 63 74 69 6f 6e 69 6e 67 2e 20 20 55 73 65 unctioning. Use
3baf0 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 73 74 69 of the.** desti
3bb00 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 20 nation database
3bb10 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 connection while
3bb20 20 61 20 62 61 63 6b 75 70 20 69 73 20 69 6e 20 a backup is in
3bb30 70 72 6f 67 72 65 73 73 20 6d 69 67 68 74 0a 2a progress might.*
3bb40 2a 20 61 6c 73 6f 20 63 61 75 73 65 20 61 20 6d * also cause a m
3bb50 75 74 65 78 20 64 65 61 64 6c 6f 63 6b 2e 0a 2a utex deadlock..*
3bb60 2a 0a 2a 2a 20 46 75 72 74 68 65 72 6d 6f 72 65 *.** Furthermore
3bb70 2c 20 69 66 20 72 75 6e 6e 69 6e 67 20 69 6e 20 , if running in
3bb80 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f [shared cache mo
3bb90 64 65 5d 2c 20 74 68 65 20 61 70 70 6c 69 63 61 de], the applica
3bba0 74 69 6f 6e 20 6d 75 73 74 0a 2a 2a 20 67 75 61 tion must.** gua
3bbb0 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 rantee that the
3bbc0 73 68 61 72 65 64 20 63 61 63 68 65 20 75 73 65 shared cache use
3bbd0 64 20 62 79 20 74 68 65 20 64 65 73 74 69 6e 61 d by the destina
3bbe0 74 69 6f 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a tion database.**
3bbf0 20 69 73 20 6e 6f 74 20 61 63 63 65 73 73 65 64 is not accessed
3bc00 20 77 68 69 6c 65 20 74 68 65 20 62 61 63 6b 75 while the backu
3bc10 70 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 49 6e p is running. In
3bc20 20 70 72 61 63 74 69 63 65 20 74 68 69 73 20 6d practice this m
3bc30 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 eans.** that the
3bc40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
3bc50 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 t guarantee that
3bc60 20 74 68 65 20 66 69 6c 65 2d 73 79 73 74 65 6d the file-system
3bc70 20 66 69 6c 65 20 62 65 69 6e 67 20 0a 2a 2a 20 file being .**
3bc80 62 61 63 6b 65 64 20 75 70 20 74 6f 20 69 73 20 backed up to is
3bc90 6e 6f 74 20 61 63 63 65 73 73 65 64 20 62 79 20 not accessed by
3bca0 61 6e 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 any connection w
3bcb0 69 74 68 69 6e 20 74 68 65 20 70 72 6f 63 65 73 ithin the proces
3bcc0 73 2c 0a 2a 2a 20 6e 6f 74 20 6a 75 73 74 20 74 s,.** not just t
3bcd0 68 65 20 73 70 65 63 69 66 69 63 20 63 6f 6e 6e he specific conn
3bce0 65 63 74 69 6f 6e 20 74 68 61 74 20 77 61 73 20 ection that was
3bcf0 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 passed to sqlite
3bd00 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 2e 3_backup_init().
3bd10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 .**.** The [sqli
3bd20 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 te3_backup] obje
3bd30 63 74 20 69 74 73 65 6c 66 20 69 73 20 70 61 72 ct itself is par
3bd40 74 69 61 6c 6c 79 20 74 68 72 65 61 64 73 61 66 tially threadsaf
3bd50 65 2e 20 4d 75 6c 74 69 70 6c 65 20 0a 2a 2a 20 e. Multiple .**
3bd60 74 68 72 65 61 64 73 20 6d 61 79 20 73 61 66 65 threads may safe
3bd70 6c 79 20 6d 61 6b 65 20 6d 75 6c 74 69 70 6c 65 ly make multiple
3bd80 20 63 6f 6e 63 75 72 72 65 6e 74 20 63 61 6c 6c concurrent call
3bd90 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 s to sqlite3_bac
3bda0 6b 75 70 5f 73 74 65 70 28 29 2e 0a 2a 2a 20 48 kup_step()..** H
3bdb0 6f 77 65 76 65 72 2c 20 74 68 65 20 73 71 6c 69 owever, the sqli
3bdc0 74 65 33 5f 62 61 63 6b 75 70 5f 72 65 6d 61 69 te3_backup_remai
3bdd0 6e 69 6e 67 28 29 20 61 6e 64 20 73 71 6c 69 74 ning() and sqlit
3bde0 65 33 5f 62 61 63 6b 75 70 5f 70 61 67 65 63 6f e3_backup_pageco
3bdf0 75 6e 74 28 29 0a 2a 2a 20 41 50 49 73 20 61 72 unt().** APIs ar
3be00 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 73 e not strictly s
3be10 70 65 61 6b 69 6e 67 20 74 68 72 65 61 64 73 61 peaking threadsa
3be20 66 65 2e 20 49 66 20 74 68 65 79 20 61 72 65 20 fe. If they are
3be30 69 6e 76 6f 6b 65 64 20 61 74 20 74 68 65 0a 2a invoked at the.*
3be40 2a 20 73 61 6d 65 20 74 69 6d 65 20 61 73 20 61 * same time as a
3be50 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 69 73 nother thread is
3be60 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 invoking sqlite
3be70 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 3_backup_step()
3be80 69 74 20 69 73 0a 2a 2a 20 70 6f 73 73 69 62 6c it is.** possibl
3be90 65 20 74 68 61 74 20 74 68 65 79 20 72 65 74 75 e that they retu
3bea0 72 6e 20 69 6e 76 61 6c 69 64 20 76 61 6c 75 65 rn invalid value
3beb0 73 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 62 61 s..*/.sqlite3_ba
3bec0 63 6b 75 70 20 2a 73 71 6c 69 74 65 33 5f 62 61 ckup *sqlite3_ba
3bed0 63 6b 75 70 5f 69 6e 69 74 28 0a 20 20 73 71 6c ckup_init(. sql
3bee0 69 74 65 33 20 2a 70 44 65 73 74 2c 20 20 20 20 ite3 *pDest,
3bef0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3bf00 20 20 20 20 2f 2a 20 44 65 73 74 69 6e 61 74 69 /* Destinati
3bf10 6f 6e 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 on database hand
3bf20 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
3bf30 61 72 20 2a 7a 44 65 73 74 4e 61 6d 65 2c 20 20 ar *zDestName,
3bf40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
3bf50 2a 20 44 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 * Destination da
3bf60 74 61 62 61 73 65 20 6e 61 6d 65 20 2a 2f 0a 20 tabase name */.
3bf70 20 73 71 6c 69 74 65 33 20 2a 70 53 6f 75 72 63 sqlite3 *pSourc
3bf80 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
3bf90 20 20 20 20 20 20 20 20 2f 2a 20 53 6f 75 72 63 /* Sourc
3bfa0 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c e database handl
3bfb0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
3bfc0 72 20 2a 7a 53 6f 75 72 63 65 4e 61 6d 65 20 20 r *zSourceName
3bfd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
3bfe0 20 53 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 Source database
3bff0 20 6e 61 6d 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 name */.);.int
3c000 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 sqlite3_backup_s
3c010 74 65 70 28 73 71 6c 69 74 65 33 5f 62 61 63 6b tep(sqlite3_back
3c020 75 70 20 2a 70 2c 20 69 6e 74 20 6e 50 61 67 65 up *p, int nPage
3c030 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
3c040 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 73 71 6c ackup_finish(sql
3c050 69 74 65 33 5f 62 61 63 6b 75 70 20 2a 70 29 3b ite3_backup *p);
3c060 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 61 63 .int sqlite3_bac
3c070 6b 75 70 5f 72 65 6d 61 69 6e 69 6e 67 28 73 71 kup_remaining(sq
3c080 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 2a 70 29 lite3_backup *p)
3c090 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 61 ;.int sqlite3_ba
3c0a0 63 6b 75 70 5f 70 61 67 65 63 6f 75 6e 74 28 73 ckup_pagecount(s
3c0b0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 2a 70 qlite3_backup *p
3c0c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
3c0d0 45 46 3a 20 55 6e 6c 6f 63 6b 20 4e 6f 74 69 66 EF: Unlock Notif
3c0e0 69 63 61 74 69 6f 6e 0a 2a 2a 20 45 58 50 45 52 ication.** EXPER
3c0f0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 57 68 IMENTAL.**.** Wh
3c100 65 6e 20 72 75 6e 6e 69 6e 67 20 69 6e 20 73 68 en running in sh
3c110 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 2c ared-cache mode,
3c120 20 61 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 a database oper
3c130 61 74 69 6f 6e 20 6d 61 79 20 66 61 69 6c 20 77 ation may fail w
3c140 69 74 68 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 ith.** an [SQLIT
3c150 45 5f 4c 4f 43 4b 45 44 5d 20 65 72 72 6f 72 20 E_LOCKED] error
3c160 69 66 20 74 68 65 20 72 65 71 75 69 72 65 64 20 if the required
3c170 6c 6f 63 6b 73 20 6f 6e 20 74 68 65 20 73 68 61 locks on the sha
3c180 72 65 64 2d 63 61 63 68 65 20 6f 72 0a 2a 2a 20 red-cache or.**
3c190 69 6e 64 69 76 69 64 75 61 6c 20 74 61 62 6c 65 individual table
3c1a0 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 68 61 s within the sha
3c1b0 72 65 64 2d 63 61 63 68 65 20 63 61 6e 6e 6f 74 red-cache cannot
3c1c0 20 62 65 20 6f 62 74 61 69 6e 65 64 2e 20 53 65 be obtained. Se
3c1d0 65 0a 2a 2a 20 5b 53 51 4c 69 74 65 20 53 68 61 e.** [SQLite Sha
3c1e0 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 20 red-Cache Mode]
3c1f0 66 6f 72 20 61 20 64 65 73 63 72 69 70 74 69 6f for a descriptio
3c200 6e 20 6f 66 20 73 68 61 72 65 64 2d 63 61 63 68 n of shared-cach
3c210 65 20 6c 6f 63 6b 69 6e 67 2e 20 0a 2a 2a 20 54 e locking. .** T
3c220 68 69 73 20 41 50 49 20 6d 61 79 20 62 65 20 75 his API may be u
3c230 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 sed to register
3c240 61 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 a callback that
3c250 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f SQLite will invo
3c260 6b 65 20 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 ke .** when the
3c270 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 connection curre
3c280 6e 74 6c 79 20 68 6f 6c 64 69 6e 67 20 74 68 65 ntly holding the
3c290 20 72 65 71 75 69 72 65 64 20 6c 6f 63 6b 20 72 required lock r
3c2a0 65 6c 69 6e 71 75 69 73 68 65 73 20 69 74 2e 0a elinquishes it..
3c2b0 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f ** This API is o
3c2c0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 nly available if
3c2d0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 the library was
3c2e0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
3c2f0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e he.** [SQLITE_EN
3c300 41 42 4c 45 5f 55 4e 4c 4f 43 4b 5f 4e 4f 54 49 ABLE_UNLOCK_NOTI
3c310 46 59 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 FY] C-preprocess
3c320 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 or symbol define
3c330 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 d..**.** See Als
3c340 6f 3a 20 5b 55 73 69 6e 67 20 74 68 65 20 53 51 o: [Using the SQ
3c350 4c 69 74 65 20 55 6e 6c 6f 63 6b 20 4e 6f 74 69 Lite Unlock Noti
3c360 66 69 63 61 74 69 6f 6e 20 46 65 61 74 75 72 65 fication Feature
3c370 5d 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 2d ]..**.** Shared-
3c380 63 61 63 68 65 20 6c 6f 63 6b 73 20 61 72 65 20 cache locks are
3c390 72 65 6c 65 61 73 65 64 20 77 68 65 6e 20 61 20 released when a
3c3a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3c3b0 69 6f 6e 20 63 6f 6e 63 6c 75 64 65 73 0a 2a 2a ion concludes.**
3c3c0 20 69 74 73 20 63 75 72 72 65 6e 74 20 74 72 61 its current tra
3c3d0 6e 73 61 63 74 69 6f 6e 2c 20 65 69 74 68 65 72 nsaction, either
3c3e0 20 62 79 20 63 6f 6d 6d 69 74 74 69 6e 67 20 69 by committing i
3c3f0 74 20 6f 72 20 72 6f 6c 6c 69 6e 67 20 69 74 20 t or rolling it
3c400 62 61 63 6b 2e 20 0a 2a 2a 0a 2a 2a 20 57 68 65 back. .**.** Whe
3c410 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 28 n a connection (
3c420 6b 6e 6f 77 6e 20 61 73 20 74 68 65 20 62 6c 6f known as the blo
3c430 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 29 cked connection)
3c440 20 66 61 69 6c 73 20 74 6f 20 6f 62 74 61 69 6e fails to obtain
3c450 20 61 0a 2a 2a 20 73 68 61 72 65 64 2d 63 61 63 a.** shared-cac
3c460 68 65 20 6c 6f 63 6b 20 61 6e 64 20 53 51 4c 49 he lock and SQLI
3c470 54 45 5f 4c 4f 43 4b 45 44 20 69 73 20 72 65 74 TE_LOCKED is ret
3c480 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c urned to the cal
3c490 6c 65 72 2c 20 74 68 65 0a 2a 2a 20 69 64 65 6e ler, the.** iden
3c4a0 74 69 74 79 20 6f 66 20 74 68 65 20 64 61 74 61 tity of the data
3c4b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
3c4c0 28 74 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f (the blocking co
3c4d0 6e 6e 65 63 74 69 6f 6e 29 20 74 68 61 74 0a 2a nnection) that.*
3c4e0 2a 20 68 61 73 20 6c 6f 63 6b 65 64 20 74 68 65 * has locked the
3c4f0 20 72 65 71 75 69 72 65 64 20 72 65 73 6f 75 72 required resour
3c500 63 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 74 ce is stored int
3c510 65 72 6e 61 6c 6c 79 2e 20 41 66 74 65 72 20 61 ernally. After a
3c520 6e 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f n .** applicatio
3c530 6e 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 n receives an SQ
3c540 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 65 72 72 6f LITE_LOCKED erro
3c550 72 2c 20 69 74 20 6d 61 79 20 63 61 6c 6c 20 74 r, it may call t
3c560 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 6e he.** sqlite3_un
3c570 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 6d 65 lock_notify() me
3c580 74 68 6f 64 20 77 69 74 68 20 74 68 65 20 62 6c thod with the bl
3c590 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e ocked connection
3c5a0 20 68 61 6e 64 6c 65 20 61 73 20 0a 2a 2a 20 74 handle as .** t
3c5b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
3c5c0 74 20 74 6f 20 72 65 67 69 73 74 65 72 20 66 6f t to register fo
3c5d0 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 r a callback tha
3c5e0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 t will be invoke
3c5f0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 62 6c d.** when the bl
3c600 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f ocking connectio
3c610 6e 73 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 ns current trans
3c620 61 63 74 69 6f 6e 20 69 73 20 63 6f 6e 63 6c 75 action is conclu
3c630 64 65 64 2e 20 54 68 65 0a 2a 2a 20 63 61 6c 6c ded. The.** call
3c640 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
3c650 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 from within the
3c660 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 20 6f [sqlite3_step] o
3c670 72 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 r [sqlite3_close
3c680 5d 0a 2a 2a 20 63 61 6c 6c 20 74 68 61 74 20 63 ].** call that c
3c690 6f 6e 63 6c 75 64 65 73 20 74 68 65 20 62 6c 6f oncludes the blo
3c6a0 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e cking connection
3c6b0 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 0a 2a s transaction..*
3c6c0 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f *.** If sqlite3_
3c6d0 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 unlock_notify()
3c6e0 69 73 20 63 61 6c 6c 65 64 20 69 6e 20 61 20 6d is called in a m
3c6f0 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 ulti-threaded ap
3c700 70 6c 69 63 61 74 69 6f 6e 2c 0a 2a 2a 20 74 68 plication,.** th
3c710 65 72 65 20 69 73 20 61 20 63 68 61 6e 63 65 20 ere is a chance
3c720 74 68 61 74 20 74 68 65 20 62 6c 6f 63 6b 69 6e that the blockin
3c730 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 69 6c g connection wil
3c740 6c 20 68 61 76 65 20 61 6c 72 65 61 64 79 0a 2a l have already.*
3c750 2a 20 63 6f 6e 63 6c 75 64 65 64 20 69 74 73 20 * concluded its
3c760 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 79 20 74 transaction by t
3c770 68 65 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f he time sqlite3_
3c780 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 unlock_notify()
3c790 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 49 is invoked..** I
3c7a0 66 20 74 68 69 73 20 68 61 70 70 65 6e 73 2c 20 f this happens,
3c7b0 74 68 65 6e 20 74 68 65 20 73 70 65 63 69 66 69 then the specifi
3c7c0 65 64 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 ed callback is i
3c7d0 6e 76 6f 6b 65 64 20 69 6d 6d 65 64 69 61 74 65 nvoked immediate
3c7e0 6c 79 2c 0a 2a 2a 20 66 72 6f 6d 20 77 69 74 68 ly,.** from with
3c7f0 69 6e 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 in the call to s
3c800 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f qlite3_unlock_no
3c810 74 69 66 79 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 tify()..**.** If
3c820 20 74 68 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e the blocked con
3c830 6e 65 63 74 69 6f 6e 20 69 73 20 61 74 74 65 6d nection is attem
3c840 70 74 69 6e 67 20 74 6f 20 6f 62 74 61 69 6e 20 pting to obtain
3c850 61 20 77 72 69 74 65 2d 6c 6f 63 6b 20 6f 6e 20 a write-lock on
3c860 61 0a 2a 2a 20 73 68 61 72 65 64 2d 63 61 63 68 a.** shared-cach
3c870 65 20 74 61 62 6c 65 2c 20 61 6e 64 20 6d 6f 72 e table, and mor
3c880 65 20 74 68 61 6e 20 6f 6e 65 20 6f 74 68 65 72 e than one other
3c890 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 connection curr
3c8a0 65 6e 74 6c 79 20 68 6f 6c 64 73 0a 2a 2a 20 61 ently holds.** a
3c8b0 20 72 65 61 64 2d 6c 6f 63 6b 20 6f 6e 20 74 68 read-lock on th
3c8c0 65 20 73 61 6d 65 20 74 61 62 6c 65 2c 20 74 68 e same table, th
3c8d0 65 6e 20 53 51 4c 69 74 65 20 61 72 62 69 74 72 en SQLite arbitr
3c8e0 61 72 69 6c 79 20 73 65 6c 65 63 74 73 20 6f 6e arily selects on
3c8f0 65 20 6f 66 20 0a 2a 2a 20 74 68 65 20 6f 74 68 e of .** the oth
3c900 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 er connections t
3c910 6f 20 75 73 65 20 61 73 20 74 68 65 20 62 6c 6f o use as the blo
3c920 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e cking connection
3c930 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 6d 61 ..**.** There ma
3c940 79 20 62 65 20 61 74 20 6d 6f 73 74 20 6f 6e 65 y be at most one
3c950 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 unlock-notify c
3c960 61 6c 6c 62 61 63 6b 20 72 65 67 69 73 74 65 72 allback register
3c970 65 64 20 62 79 20 61 20 0a 2a 2a 20 62 6c 6f 63 ed by a .** bloc
3c980 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 ked connection.
3c990 49 66 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 If sqlite3_unloc
3c9a0 6b 5f 6e 6f 74 69 66 79 28 29 20 69 73 20 63 61 k_notify() is ca
3c9b0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a lled when the.**
3c9c0 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 74 blocked connect
3c9d0 69 6f 6e 20 61 6c 72 65 61 64 79 20 68 61 73 20 ion already has
3c9e0 61 20 72 65 67 69 73 74 65 72 65 64 20 75 6e 6c a registered unl
3c9f0 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 ock-notify callb
3ca00 61 63 6b 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ack,.** then the
3ca10 20 6e 65 77 20 63 61 6c 6c 62 61 63 6b 20 72 65 new callback re
3ca20 70 6c 61 63 65 73 20 74 68 65 20 6f 6c 64 2e 20 places the old.
3ca30 49 66 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 If sqlite3_unloc
3ca40 6b 5f 6e 6f 74 69 66 79 28 29 20 69 73 0a 2a 2a k_notify() is.**
3ca50 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e called with a N
3ca60 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 73 20 69 ULL pointer as i
3ca70 74 73 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 ts second argume
3ca80 6e 74 2c 20 74 68 65 6e 20 61 6e 79 20 65 78 69 nt, then any exi
3ca90 73 74 69 6e 67 0a 2a 2a 20 75 6e 6c 6f 63 6b 2d sting.** unlock-
3caa0 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 notify callback
3cab0 69 73 20 63 61 6e 63 65 6c 6c 65 64 2e 20 54 68 is cancelled. Th
3cac0 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 e blocked connec
3cad0 74 69 6f 6e 73 20 0a 2a 2a 20 75 6e 6c 6f 63 6b tions .** unlock
3cae0 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b -notify callback
3caf0 20 6d 61 79 20 61 6c 73 6f 20 62 65 20 63 61 6e may also be can
3cb00 63 65 6c 65 64 20 62 79 20 63 6c 6f 73 69 6e 67 celed by closing
3cb10 20 74 68 65 20 62 6c 6f 63 6b 65 64 0a 2a 2a 20 the blocked.**
3cb20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 connection using
3cb30 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
3cb40 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 6e )]..**.** The un
3cb50 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c lock-notify call
3cb60 62 61 63 6b 20 69 73 20 6e 6f 74 20 72 65 65 6e back is not reen
3cb70 74 72 61 6e 74 2e 20 49 66 20 61 6e 20 61 70 70 trant. If an app
3cb80 6c 69 63 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 lication invokes
3cb90 0a 2a 2a 20 61 6e 79 20 73 71 6c 69 74 65 33 5f .** any sqlite3_
3cba0 78 78 78 20 41 50 49 20 66 75 6e 63 74 69 6f 6e xxx API function
3cbb0 73 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 61 6e s from within an
3cbc0 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 unlock-notify c
3cbd0 61 6c 6c 62 61 63 6b 2c 20 61 0a 2a 2a 20 63 72 allback, a.** cr
3cbe0 61 73 68 20 6f 72 20 64 65 61 64 6c 6f 63 6b 20 ash or deadlock
3cbf0 6d 61 79 20 62 65 20 74 68 65 20 72 65 73 75 6c may be the resul
3cc00 74 2e 0a 2a 2a 0a 2a 2a 20 55 6e 6c 65 73 73 20 t..**.** Unless
3cc10 64 65 61 64 6c 6f 63 6b 20 69 73 20 64 65 74 65 deadlock is dete
3cc20 63 74 65 64 20 28 73 65 65 20 62 65 6c 6f 77 29 cted (see below)
3cc30 2c 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b , sqlite3_unlock
3cc40 5f 6e 6f 74 69 66 79 28 29 20 61 6c 77 61 79 73 _notify() always
3cc50 0a 2a 2a 20 72 65 74 75 72 6e 73 20 53 51 4c 49 .** returns SQLI
3cc60 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e TE_OK..**.** <b>
3cc70 43 61 6c 6c 62 61 63 6b 20 49 6e 76 6f 63 61 74 Callback Invocat
3cc80 69 6f 6e 20 44 65 74 61 69 6c 73 3c 2f 62 3e 0a ion Details</b>.
3cc90 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 75 6e **.** When an un
3cca0 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c lock-notify call
3ccb0 62 61 63 6b 20 69 73 20 72 65 67 69 73 74 65 72 back is register
3ccc0 65 64 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 ed, the applicat
3ccd0 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 20 0a ion provides a .
3cce0 2a 2a 20 73 69 6e 67 6c 65 20 76 6f 69 64 2a 20 ** single void*
3ccf0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 pointer that is
3cd00 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 63 61 passed to the ca
3cd10 6c 6c 62 61 63 6b 20 77 68 65 6e 20 69 74 20 69 llback when it i
3cd20 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 48 6f s invoked..** Ho
3cd30 77 65 76 65 72 2c 20 74 68 65 20 73 69 67 6e 61 wever, the signa
3cd40 74 75 72 65 20 6f 66 20 74 68 65 20 63 61 6c 6c ture of the call
3cd50 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 61 6c back function al
3cd60 6c 6f 77 73 20 53 51 4c 69 74 65 20 74 6f 20 70 lows SQLite to p
3cd70 61 73 73 0a 2a 2a 20 69 74 20 61 6e 20 61 72 72 ass.** it an arr
3cd80 61 79 20 6f 66 20 76 6f 69 64 2a 20 63 6f 6e 74 ay of void* cont
3cd90 65 78 74 20 70 6f 69 6e 74 65 72 73 2e 20 54 68 ext pointers. Th
3cda0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
3cdb0 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 61 6e passed to.** an
3cdc0 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 unlock-notify c
3cdd0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 70 6f 69 allback is a poi
3cde0 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 nter to an array
3cdf0 20 6f 66 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 of void* pointe
3ce00 72 73 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 rs,.** and the s
3ce10 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d econd is the num
3ce20 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 ber of entries i
3ce30 6e 20 74 68 65 20 61 72 72 61 79 2e 0a 2a 2a 0a n the array..**.
3ce40 2a 2a 20 57 68 65 6e 20 61 20 62 6c 6f 63 6b 69 ** When a blocki
3ce50 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 ng connections t
3ce60 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f ransaction is co
3ce70 6e 63 6c 75 64 65 64 2c 20 74 68 65 72 65 20 6d ncluded, there m
3ce80 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 74 68 ay be.** more th
3ce90 61 6e 20 6f 6e 65 20 62 6c 6f 63 6b 65 64 20 63 an one blocked c
3cea0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 68 onnection that h
3ceb0 61 73 20 72 65 67 69 73 74 65 72 65 64 20 66 6f as registered fo
3cec0 72 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 r an unlock-noti
3ced0 66 79 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 20 fy.** callback.
3cee0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 73 If two or more s
3cef0 75 63 68 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e uch blocked conn
3cf00 65 63 74 69 6f 6e 73 20 68 61 76 65 20 73 70 65 ections have spe
3cf10 63 69 66 69 65 64 20 74 68 65 0a 2a 2a 20 73 61 cified the.** sa
3cf20 6d 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 me callback func
3cf30 74 69 6f 6e 2c 20 74 68 65 6e 20 69 6e 73 74 65 tion, then inste
3cf40 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 ad of invoking t
3cf50 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
3cf60 74 69 6f 6e 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 tion.** multiple
3cf70 20 74 69 6d 65 73 2c 20 69 74 20 69 73 20 69 6e times, it is in
3cf80 76 6f 6b 65 64 20 6f 6e 63 65 20 77 69 74 68 20 voked once with
3cf90 74 68 65 20 73 65 74 20 6f 66 20 76 6f 69 64 2a the set of void*
3cfa0 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 context pointer
3cfb0 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62 s.** specified b
3cfc0 79 20 74 68 65 20 62 6c 6f 63 6b 65 64 20 63 6f y the blocked co
3cfd0 6e 6e 65 63 74 69 6f 6e 73 20 62 75 6e 64 6c 65 nnections bundle
3cfe0 64 20 74 6f 67 65 74 68 65 72 20 69 6e 74 6f 20 d together into
3cff0 61 6e 20 61 72 72 61 79 2e 0a 2a 2a 20 54 68 69 an array..** Thi
3d000 73 20 67 69 76 65 73 20 74 68 65 20 61 70 70 6c s gives the appl
3d010 69 63 61 74 69 6f 6e 20 61 6e 20 6f 70 70 6f 72 ication an oppor
3d020 74 75 6e 69 74 79 20 74 6f 20 70 72 69 6f 72 69 tunity to priori
3d030 74 69 7a 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 tize any actions
3d040 20 0a 2a 2a 20 72 65 6c 61 74 65 64 20 74 6f 20 .** related to
3d050 74 68 65 20 73 65 74 20 6f 66 20 75 6e 62 6c 6f the set of unblo
3d060 63 6b 65 64 20 64 61 74 61 62 61 73 65 20 63 6f cked database co
3d070 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a nnections..**.**
3d080 20 3c 62 3e 44 65 61 64 6c 6f 63 6b 20 44 65 74 <b>Deadlock Det
3d090 65 63 74 69 6f 6e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a ection</b>.**.**
3d0a0 20 41 73 73 75 6d 69 6e 67 20 74 68 61 74 20 61 Assuming that a
3d0b0 66 74 65 72 20 72 65 67 69 73 74 65 72 69 6e 67 fter registering
3d0c0 20 66 6f 72 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e for an unlock-n
3d0d0 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 61 otify callback a
3d0e0 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 77 61 .** database wa
3d0f0 69 74 73 20 66 6f 72 20 74 68 65 20 63 61 6c 6c its for the call
3d100 62 61 63 6b 20 74 6f 20 62 65 20 69 73 73 75 65 back to be issue
3d110 64 20 62 65 66 6f 72 65 20 74 61 6b 69 6e 67 20 d before taking
3d120 61 6e 79 20 66 75 72 74 68 65 72 0a 2a 2a 20 61 any further.** a
3d130 63 74 69 6f 6e 20 28 61 20 72 65 61 73 6f 6e 61 ction (a reasona
3d140 62 6c 65 20 61 73 73 75 6d 70 74 69 6f 6e 29 2c ble assumption),
3d150 20 74 68 65 6e 20 75 73 69 6e 67 20 74 68 69 73 then using this
3d160 20 41 50 49 20 6d 61 79 20 63 61 75 73 65 20 74 API may cause t
3d170 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f he.** applicatio
3d180 6e 20 74 6f 20 64 65 61 64 6c 6f 63 6b 2e 20 46 n to deadlock. F
3d190 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 63 or example, if c
3d1a0 6f 6e 6e 65 63 74 69 6f 6e 20 58 20 69 73 20 77 onnection X is w
3d1b0 61 69 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 63 6f aiting for.** co
3d1c0 6e 6e 65 63 74 69 6f 6e 20 59 27 73 20 74 72 61 nnection Y's tra
3d1d0 6e 73 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 nsaction to be c
3d1e0 6f 6e 63 6c 75 64 65 64 2c 20 61 6e 64 20 73 69 oncluded, and si
3d1f0 6d 69 6c 61 72 6c 79 20 63 6f 6e 6e 65 63 74 69 milarly connecti
3d200 6f 6e 0a 2a 2a 20 59 20 69 73 20 77 61 69 74 69 on.** Y is waiti
3d210 6e 67 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e ng on connection
3d220 20 58 27 73 20 74 72 61 6e 73 61 63 74 69 6f 6e X's transaction
3d230 2c 20 74 68 65 6e 20 6e 65 69 74 68 65 72 20 63 , then neither c
3d240 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c onnection.** wil
3d250 6c 20 70 72 6f 63 65 65 64 20 61 6e 64 20 74 68 l proceed and th
3d260 65 20 73 79 73 74 65 6d 20 6d 61 79 20 72 65 6d e system may rem
3d270 61 69 6e 20 64 65 61 64 6c 6f 63 6b 65 64 20 69 ain deadlocked i
3d280 6e 64 65 66 69 6e 69 74 65 6c 79 2e 0a 2a 2a 0a ndefinitely..**.
3d290 2a 2a 20 54 6f 20 61 76 6f 69 64 20 74 68 69 73 ** To avoid this
3d2a0 20 73 63 65 6e 61 72 69 6f 2c 20 74 68 65 20 73 scenario, the s
3d2b0 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f qlite3_unlock_no
3d2c0 74 69 66 79 28 29 20 70 65 72 66 6f 72 6d 73 20 tify() performs
3d2d0 64 65 61 64 6c 6f 63 6b 0a 2a 2a 20 64 65 74 65 deadlock.** dete
3d2e0 63 74 69 6f 6e 2e 20 49 66 20 61 20 67 69 76 65 ction. If a give
3d2f0 6e 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 n call to sqlite
3d300 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 3_unlock_notify(
3d310 29 20 77 6f 75 6c 64 20 70 75 74 20 74 68 65 0a ) would put the.
3d320 2a 2a 20 73 79 73 74 65 6d 20 69 6e 20 61 20 64 ** system in a d
3d330 65 61 64 6c 6f 63 6b 65 64 20 73 74 61 74 65 2c eadlocked state,
3d340 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4c 4f 43 then SQLITE_LOC
3d350 4b 45 44 20 69 73 20 72 65 74 75 72 6e 65 64 20 KED is returned
3d360 61 6e 64 20 6e 6f 0a 2a 2a 20 75 6e 6c 6f 63 6b and no.** unlock
3d370 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b -notify callback
3d380 20 69 73 20 72 65 67 69 73 74 65 72 65 64 2e 20 is registered.
3d390 54 68 65 20 73 79 73 74 65 6d 20 69 73 20 73 61 The system is sa
3d3a0 69 64 20 74 6f 20 62 65 20 69 6e 0a 2a 2a 20 61 id to be in.** a
3d3b0 20 64 65 61 64 6c 6f 63 6b 65 64 20 73 74 61 74 deadlocked stat
3d3c0 65 20 69 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 e if connection
3d3d0 41 20 68 61 73 20 72 65 67 69 73 74 65 72 65 64 A has registered
3d3e0 20 66 6f 72 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e for an unlock-n
3d3f0 6f 74 69 66 79 0a 2a 2a 20 63 61 6c 6c 62 61 63 otify.** callbac
3d400 6b 20 6f 6e 20 74 68 65 20 63 6f 6e 63 6c 75 73 k on the conclus
3d410 69 6f 6e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f ion of connectio
3d420 6e 20 42 27 73 20 74 72 61 6e 73 61 63 74 69 6f n B's transactio
3d430 6e 2c 20 61 6e 64 20 63 6f 6e 6e 65 63 74 69 6f n, and connectio
3d440 6e 0a 2a 2a 20 42 20 68 61 73 20 69 74 73 65 6c n.** B has itsel
3d450 66 20 72 65 67 69 73 74 65 72 65 64 20 66 6f 72 f registered for
3d460 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 an unlock-notif
3d470 79 20 63 61 6c 6c 62 61 63 6b 20 77 68 65 6e 20 y callback when
3d480 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 41 27 connection.** A'
3d490 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 s transaction is
3d4a0 20 63 6f 6e 63 6c 75 64 65 64 2e 20 49 6e 64 69 concluded. Indi
3d4b0 72 65 63 74 20 64 65 61 64 6c 6f 63 6b 20 69 73 rect deadlock is
3d4c0 20 61 6c 73 6f 20 64 65 74 65 63 74 65 64 2c 20 also detected,
3d4d0 73 6f 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d so.** the system
3d4e0 20 69 73 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 is also conside
3d4f0 72 65 64 20 74 6f 20 62 65 20 64 65 61 64 6c 6f red to be deadlo
3d500 63 6b 65 64 20 69 66 20 63 6f 6e 6e 65 63 74 69 cked if connecti
3d510 6f 6e 20 42 20 68 61 73 0a 2a 2a 20 72 65 67 69 on B has.** regi
3d520 73 74 65 72 65 64 20 66 6f 72 20 61 6e 20 75 6e stered for an un
3d530 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c lock-notify call
3d540 62 61 63 6b 20 6f 6e 20 74 68 65 20 63 6f 6e 63 back on the conc
3d550 6c 75 73 69 6f 6e 20 6f 66 20 63 6f 6e 6e 65 63 lusion of connec
3d560 74 69 6f 6e 0a 2a 2a 20 43 27 73 20 74 72 61 6e tion.** C's tran
3d570 73 61 63 74 69 6f 6e 2c 20 77 68 65 72 65 20 63 saction, where c
3d580 6f 6e 6e 65 63 74 69 6f 6e 20 43 20 69 73 20 77 onnection C is w
3d590 61 69 74 69 6e 67 20 6f 6e 20 63 6f 6e 6e 65 63 aiting on connec
3d5a0 74 69 6f 6e 20 41 2e 20 41 6e 79 0a 2a 2a 20 6e tion A. Any.** n
3d5b0 75 6d 62 65 72 20 6f 66 20 6c 65 76 65 6c 73 20 umber of levels
3d5c0 6f 66 20 69 6e 64 69 72 65 63 74 69 6f 6e 20 61 of indirection a
3d5d0 72 65 20 61 6c 6c 6f 77 65 64 2e 0a 2a 2a 0a 2a re allowed..**.*
3d5e0 2a 20 3c 62 3e 54 68 65 20 22 44 52 4f 50 20 54 * <b>The "DROP T
3d5f0 41 42 4c 45 22 20 45 78 63 65 70 74 69 6f 6e 3c ABLE" Exception<
3d600 2f 62 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 /b>.**.** When a
3d610 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
3d620 33 5f 73 74 65 70 28 29 5d 20 72 65 74 75 72 6e 3_step()] return
3d630 73 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 2c s SQLITE_LOCKED,
3d640 20 69 74 20 69 73 20 61 6c 6d 6f 73 74 20 0a 2a it is almost .*
3d650 2a 20 61 6c 77 61 79 73 20 61 70 70 72 6f 70 72 * always appropr
3d660 69 61 74 65 20 74 6f 20 63 61 6c 6c 20 73 71 6c iate to call sql
3d670 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 ite3_unlock_noti
3d680 66 79 28 29 2e 20 54 68 65 72 65 20 69 73 20 68 fy(). There is h
3d690 6f 77 65 76 65 72 2c 0a 2a 2a 20 6f 6e 65 20 65 owever,.** one e
3d6a0 78 63 65 70 74 69 6f 6e 2e 20 57 68 65 6e 20 65 xception. When e
3d6b0 78 65 63 75 74 69 6e 67 20 61 20 22 44 52 4f 50 xecuting a "DROP
3d6c0 20 54 41 42 4c 45 22 20 6f 72 20 22 44 52 4f 50 TABLE" or "DROP
3d6d0 20 49 4e 44 45 58 22 20 73 74 61 74 65 6d 65 6e INDEX" statemen
3d6e0 74 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 63 68 65 t,.** SQLite che
3d6f0 63 6b 73 20 69 66 20 74 68 65 72 65 20 61 72 65 cks if there are
3d700 20 61 6e 79 20 63 75 72 72 65 6e 74 6c 79 20 65 any currently e
3d710 78 65 63 75 74 69 6e 67 20 53 45 4c 45 43 54 20 xecuting SELECT
3d720 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 statements.** th
3d730 61 74 20 62 65 6c 6f 6e 67 20 74 6f 20 74 68 65 at belong to the
3d740 20 73 61 6d 65 20 63 6f 6e 6e 65 63 74 69 6f 6e same connection
3d750 2e 20 49 66 20 74 68 65 72 65 20 61 72 65 2c 20 . If there are,
3d760 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 69 73 SQLITE_LOCKED is
3d770 0a 2a 2a 20 72 65 74 75 72 6e 65 64 2e 20 49 6e .** returned. In
3d780 20 74 68 69 73 20 63 61 73 65 20 74 68 65 72 65 this case there
3d790 20 69 73 20 6e 6f 20 22 62 6c 6f 63 6b 69 6e 67 is no "blocking
3d7a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 22 2c 20 73 6f connection", so
3d7b0 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c invoking.** sql
3d7c0 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 ite3_unlock_noti
3d7d0 66 79 28 29 20 72 65 73 75 6c 74 73 20 69 6e 20 fy() results in
3d7e0 74 68 65 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 the unlock-notif
3d7f0 79 20 63 61 6c 6c 62 61 63 6b 20 62 65 69 6e 67 y callback being
3d800 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 69 6d 6d 65 .** invoked imme
3d810 64 69 61 74 65 6c 79 2e 20 49 66 20 74 68 65 20 diately. If the
3d820 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 65 6e application then
3d830 20 72 65 2d 61 74 74 65 6d 70 74 73 20 74 68 65 re-attempts the
3d840 20 22 44 52 4f 50 20 54 41 42 4c 45 22 0a 2a 2a "DROP TABLE".**
3d850 20 6f 72 20 22 44 52 4f 50 20 49 4e 44 45 58 22 or "DROP INDEX"
3d860 20 71 75 65 72 79 2c 20 61 6e 20 69 6e 66 69 6e query, an infin
3d870 69 74 65 20 6c 6f 6f 70 20 6d 69 67 68 74 20 62 ite loop might b
3d880 65 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a e the result..**
3d890 0a 2a 2a 20 4f 6e 65 20 77 61 79 20 61 72 6f 75 .** One way arou
3d8a0 6e 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 nd this problem
3d8b0 69 73 20 74 6f 20 63 68 65 63 6b 20 74 68 65 20 is to check the
3d8c0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
3d8d0 6f 64 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 ode returned.**
3d8e0 62 79 20 61 6e 20 73 71 6c 69 74 65 33 5f 73 74 by an sqlite3_st
3d8f0 65 70 28 29 20 63 61 6c 6c 2e 20 49 66 20 74 68 ep() call. If th
3d900 65 72 65 20 69 73 20 61 20 62 6c 6f 63 6b 69 6e ere is a blockin
3d910 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 g connection, th
3d920 65 6e 20 74 68 65 0a 2a 2a 20 65 78 74 65 6e 64 en the.** extend
3d930 65 64 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 ed error code is
3d940 20 73 65 74 20 74 6f 20 53 51 4c 49 54 45 5f 4c set to SQLITE_L
3d950 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 OCKED_SHAREDCACH
3d960 45 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 69 6e E. Otherwise, in
3d970 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 .** the special
3d980 22 44 52 4f 50 20 54 41 42 4c 45 2f 49 4e 44 45 "DROP TABLE/INDE
3d990 58 22 20 63 61 73 65 2c 20 74 68 65 20 65 78 74 X" case, the ext
3d9a0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
3d9b0 20 69 73 20 6a 75 73 74 20 0a 2a 2a 20 53 51 4c is just .** SQL
3d9c0 49 54 45 5f 4c 4f 43 4b 45 44 2e 0a 2a 2f 0a 69 ITE_LOCKED..*/.i
3d9d0 6e 74 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 nt sqlite3_unloc
3d9e0 6b 5f 6e 6f 74 69 66 79 28 0a 20 20 73 71 6c 69 k_notify(. sqli
3d9f0 74 65 33 20 2a 70 42 6c 6f 63 6b 65 64 2c 20 20 te3 *pBlocked,
3da00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3da10 20 20 20 20 20 20 20 20 2f 2a 20 57 61 69 74 69 /* Waiti
3da20 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f ng connection */
3da30 0a 20 20 76 6f 69 64 20 28 2a 78 4e 6f 74 69 66 . void (*xNotif
3da40 79 29 28 76 6f 69 64 20 2a 2a 61 70 41 72 67 2c y)(void **apArg,
3da50 20 69 6e 74 20 6e 41 72 67 29 2c 20 20 20 20 2f int nArg), /
3da60 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 * Callback funct
3da70 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 2a 2f ion to invoke */
3da80 0a 20 20 76 6f 69 64 20 2a 70 4e 6f 74 69 66 79 . void *pNotify
3da90 41 72 67 20 20 20 20 20 20 20 20 20 20 20 20 20 Arg
3daa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
3dab0 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 70 61 * Argument to pa
3dac0 73 73 20 74 6f 20 78 4e 6f 74 69 66 79 20 2a 2f ss to xNotify */
3dad0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 55 6e 64 6f 20 .);../*.** Undo
3dae0 74 68 65 20 68 61 63 6b 20 74 68 61 74 20 63 6f the hack that co
3daf0 6e 76 65 72 74 73 20 66 6c 6f 61 74 69 6e 67 20 nverts floating
3db00 70 6f 69 6e 74 20 74 79 70 65 73 20 74 6f 20 69 point types to i
3db10 6e 74 65 67 65 72 20 66 6f 72 0a 2a 2a 20 62 75 nteger for.** bu
3db20 69 6c 64 73 20 6f 6e 20 70 72 6f 63 65 73 73 6f ilds on processo
3db30 72 73 20 77 69 74 68 6f 75 74 20 66 6c 6f 61 74 rs without float
3db40 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 ing point suppor
3db50 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c t..*/.#ifdef SQL
3db60 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e ITE_OMIT_FLOATIN
3db70 47 5f 50 4f 49 4e 54 0a 23 20 75 6e 64 65 66 20 G_POINT.# undef
3db80 64 6f 75 62 6c 65 0a 23 65 6e 64 69 66 0a 0a 23 double.#endif..#
3db90 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 ifdef __cplusplu
3dba0 73 0a 7d 20 20 2f 2a 20 45 6e 64 20 6f 66 20 74 s.} /* End of t
3dbb0 68 65 20 27 65 78 74 65 72 6e 20 22 43 22 27 20 he 'extern "C"'
3dbc0 62 6c 6f 63 6b 20 2a 2f 0a 23 65 6e 64 69 66 0a block */.#endif.
3dbd0 23 65 6e 64 69 66 0a #endif.