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 36 32 20 32 30 30 39 2f 30 n,v 1.462 2009/0
05f0: 38 2f 30 36 20 31 37 3a 34 30 3a 34 36 20 64 72 8/06 17:40:46 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 23 69 xtern.#endif..#i
0740: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 fndef SQLITE_API
0750: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
0760: 5f 41 50 49 0a 23 65 6e 64 69 66 0a 0a 0a 23 69 _API.#endif...#i
0770: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 fndef SQLITE_API
0780: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
0790: 5f 41 50 49 0a 23 65 6e 64 69 66 0a 0a 0a 23 69 _API.#endif...#i
07a0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 fndef SQLITE_API
07b0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
07c0: 5f 41 50 49 0a 23 65 6e 64 69 66 0a 0a 0a 23 69 _API.#endif...#i
07d0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 fndef SQLITE_API
07e0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
07f0: 5f 41 50 49 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a _API.#endif.../*
0800: 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 .** These no-op
0810: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20 macros are used
0820: 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 in front of inte
0830: 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 rfaces to mark t
0840: 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 hose.** interfac
0850: 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70 es as either dep
0860: 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72 recated or exper
0870: 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 imental. New ap
0880: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 plications.** sh
0890: 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70 ould not use dep
08a0: 72 65 63 61 74 65 64 20 69 6e 74 72 66 61 63 65 recated intrface
08b0: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 s - they are sup
08c0: 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72 port for backwar
08d0: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c ds.** compatibil
08e0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 ity only. Appli
08f0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73 cation writers s
0900: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74 hould be aware t
0910: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e hat.** experimen
0920: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 tal interfaces a
0930: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 re subject to ch
0940: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 ange in point re
0950: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 leases..**.** Th
0960: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20 ese macros used
0970: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 to resolve to va
0980: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 rious kinds of c
0990: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68 ompiler magic th
09a0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 at.** would gene
09b0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 rate warning mes
09c0: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20 sages when they
09d0: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20 were used. But
09e0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 that.** compiler
09f0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20 magic ended up
0a00: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20 generating such
0a10: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20 a flurry of bug
0a20: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 reports.** that
0a30: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74 we have taken it
0a40: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e all out and gon
0a50: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 e back to using
0a60: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d simple.** noop m
0a70: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e acros..*/.#defin
0a80: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 e SQLITE_DEPRECA
0a90: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 TED.#define SQLI
0aa0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a TE_EXPERIMENTAL.
0ab0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 ./*.** Ensure th
0ac0: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 ese symbols were
0ad0: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 not defined by
0ae0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 some previous he
0af0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 ader file..*/.#i
0b00: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 fdef SQLITE_VERS
0b10: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 ION.# undef SQLI
0b20: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 TE_VERSION.#endi
0b30: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
0b40: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 VERSION_NUMBER.#
0b50: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 undef SQLITE_VE
0b60: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e RSION_NUMBER.#en
0b70: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
0b80: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d REF: Compile-Tim
0b90: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f e Library Versio
0ba0: 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 31 n Numbers {H1001
0bb0: 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 0} <S60100>.**.*
0bc0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 * The SQLITE_VER
0bd0: 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f SION and SQLITE_
0be0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 VERSION_NUMBER #
0bf0: 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68 defines in.** th
0c00: 65 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c 65 e sqlite3.h file
0c10: 20 73 70 65 63 69 66 79 20 74 68 65 20 76 65 72 specify the ver
0c20: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 77 sion of SQLite w
0c30: 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68 61 ith which.** tha
0c40: 74 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73 t header file is
0c50: 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a associated..**.
0c60: 2a 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e 22 ** The "version"
0c70: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61 20 of SQLite is a
0c80: 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6f string of the fo
0c90: 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54 rm "X.Y.Z"..** T
0ca0: 68 65 20 70 68 72 61 73 65 20 22 61 6c 70 68 61 he phrase "alpha
0cb0: 22 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67 68 " or "beta" migh
0cc0: 74 20 62 65 20 61 70 70 65 6e 64 65 64 20 61 66 t be appended af
0cd0: 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68 ter the Z..** Th
0ce0: 65 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61 6a e X value is maj
0cf0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 or version numbe
0d00: 72 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51 r always 3 in SQ
0d10: 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20 Lite3..** The X
0d20: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 value only chang
0d30: 65 73 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64 es when backward
0d40: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 s compatibility
0d50: 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 is.** broken and
0d60: 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 we intend to ne
0d70: 76 65 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61 ver break backwa
0d80: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
0d90: 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61 6c 75 y..** The Y valu
0da0: 65 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 e is the minor v
0db0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e ersion number an
0dc0: 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 d only changes w
0dd0: 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 hen.** there are
0de0: 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65 major feature e
0df0: 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 nhancements that
0e00: 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f are forwards co
0e10: 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 mpatible.** but
0e20: 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f not backwards co
0e30: 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 mpatible..** The
0e40: 20 5a 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 Z value is the
0e50: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61 release number a
0e60: 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 nd is incremente
0e70: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 d with.** each r
0e80: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74 elease but reset
0e90: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e s back to 0 when
0ea0: 65 76 65 72 20 59 20 69 73 20 69 6e 63 72 65 6d ever Y is increm
0eb0: 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 ented..**.** See
0ec0: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
0ed0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e libversion()] an
0ee0: 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 d [sqlite3_libve
0ef0: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e rsion_number()].
0f00: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
0f10: 6e 74 73 3a 20 5b 48 31 30 30 31 31 5d 20 5b 48 nts: [H10011] [H
0f20: 31 30 30 31 34 5d 0a 2a 2f 0a 23 64 65 66 69 6e 10014].*/.#defin
0f30: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e e SQLITE_VERSION
0f40: 20 20 20 20 20 20 20 20 20 22 33 2e 36 2e 31 37 "3.6.17
0f50: 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ".#define SQLITE
0f60: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 _VERSION_NUMBER
0f70: 20 33 30 30 36 30 31 37 0a 0a 2f 2a 0a 2a 2a 20 3006017../*.**
0f80: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 CAPI3REF: Run-Ti
0f90: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 me Library Versi
0fa0: 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 on Numbers {H100
0fb0: 32 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 20 20} <S60100>.**
0fc0: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 KEYWORDS: sqlite
0fd0: 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3_version.**.**
0fe0: 54 68 65 73 65 20 66 65 61 74 75 72 65 73 20 70 These features p
0ff0: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 rovide the same
1000: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 information as t
1010: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 he [SQLITE_VERSI
1020: 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 ON].** and [SQLI
1030: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
1040: 52 5d 20 23 64 65 66 69 6e 65 73 20 69 6e 20 74 R] #defines in t
1050: 68 65 20 68 65 61 64 65 72 2c 20 62 75 74 20 61 he header, but a
1060: 72 65 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a re associated.**
1070: 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 with the librar
1080: 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 y instead of the
1090: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 43 header file. C
10a0: 61 75 74 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d autious programm
10b0: 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63 ers might.** inc
10c0: 6c 75 64 65 20 61 20 63 68 65 63 6b 20 69 6e 20 lude a check in
10d0: 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f their applicatio
10e0: 6e 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 n to verify that
10f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 .** sqlite3_libv
1100: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 ersion_number()
1110: 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 always returns t
1120: 68 65 20 76 61 6c 75 65 0a 2a 2a 20 5b 53 51 4c he value.** [SQL
1130: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
1140: 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ER]..**.** The s
1150: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1160: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 n() function ret
1170: 75 72 6e 73 20 74 68 65 20 73 61 6d 65 20 69 6e urns the same in
1180: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a formation as is.
1190: 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 ** in the sqlite
11a0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 3_version[] stri
11b0: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 ng constant. Th
11c0: 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 e function is pr
11d0: 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73 ovided.** for us
11e0: 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 e in DLLs since
11f0: 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c DLL users usuall
1200: 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 64 69 y do not have di
1210: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 rect access to s
1220: 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e tring.** constan
1230: 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c ts within the DL
1240: 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 L..**.** Require
1250: 6d 65 6e 74 73 3a 20 5b 48 31 30 30 32 31 5d 20 ments: [H10021]
1260: 5b 48 31 30 30 32 32 5d 20 5b 48 31 30 30 32 33 [H10022] [H10023
1270: 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
1280: 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
1290: 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
12a0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 SQLITE_EXTERN c
12b0: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 onst char sqlite
12c0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53 51 4c 3_version[];.SQL
12d0: 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
12e0: 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
12f0: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
1300: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 har *sqlite3_lib
1310: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 version(void);.S
1320: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
1330: 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
1340: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
1350: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1360: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a n_number(void);.
1370: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1380: 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 Test To See If
1390: 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 The Library Is T
13a0: 68 72 65 61 64 73 61 66 65 20 7b 48 31 30 31 30 hreadsafe {H1010
13b0: 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 0} <S60100>.**.*
13c0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 * SQLite can be
13d0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 compiled with or
13e0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 without mutexes
13f0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b . When.** the [
1400: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
1410: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f E] C preprocesso
1420: 72 20 6d 61 63 72 6f 20 31 20 6f 72 20 32 2c 20 r macro 1 or 2,
1430: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 mutexes.** are e
1440: 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 nabled and SQLit
1450: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e e is threadsafe.
1460: 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 When the.** [S
1470: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
1480: 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a ] macro is 0, .*
1490: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 * the mutexes ar
14a0: 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 e omitted. With
14b0: 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c out the mutexes,
14c0: 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a it is not safe.
14d0: 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 ** to use SQLite
14e0: 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 concurrently fr
14f0: 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 om more than one
1500: 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 thread..**.** E
1510: 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 nabling mutexes
1520: 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 incurs a measura
1530: 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 ble performance
1540: 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 penalty..** So i
1550: 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 f speed is of ut
1560: 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c most importance,
1570: 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 it makes sense
1580: 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 to disable.** th
1590: 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 e mutexes. But
15a0: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 for maximum safe
15b0: 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 ty, mutexes shou
15c0: 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a ld be enabled..*
15d0: 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 * The default be
15e0: 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 havior is for mu
15f0: 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 texes to be enab
1600: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 led..**.** This
1610: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 interface can be
1620: 20 75 73 65 64 20 62 79 20 61 20 70 72 6f 67 72 used by a progr
1630: 61 6d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 am to make sure
1640: 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 that the.** vers
1650: 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 ion of SQLite th
1660: 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 at it is linking
1670: 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d against was com
1680: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
1690: 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69 6e e desired settin
16a0: 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 g of the [SQLITE
16b0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 _THREADSAFE] mac
16c0: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 ro..**.** This i
16d0: 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 nterface only re
16e0: 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d ports on the com
16f0: 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 pile-time mutex
1700: 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 setting.** of th
1710: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
1720: 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 SAFE] flag. If
1730: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
1740: 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 ed with.** SQLIT
1750: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 74 E_THREADSAFE=1 t
1760: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 hen mutexes are
1770: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 enabled by defau
1780: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 lt but.** can be
1790: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 fully or partia
17a0: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 lly disabled usi
17b0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 ng a call to [sq
17c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a lite3_config()].
17d0: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 ** with the verb
17e0: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 s [SQLITE_CONFIG
17f0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 _SINGLETHREAD],
1800: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
1810: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 ULTITHREAD],.**
1820: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 or [SQLITE_CONFI
1830: 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20 72 G_MUTEX]. The r
1840: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
1850: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f his function sho
1860: 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20 64 ws.** only the d
1870: 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 efault compile-t
1880: 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f 74 ime setting, not
1890: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 any run-time ch
18a0: 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61 74 anges.** to that
18b0: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 setting..**.**
18c0: 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 See the [threadi
18d0: 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e ng mode] documen
18e0: 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 tation for addit
18f0: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
1900: 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 n..**.** Require
1910: 6d 65 6e 74 73 3a 20 5b 48 31 30 31 30 31 5d 20 ments: [H10101]
1920: 5b 48 31 30 31 30 32 5d 0a 2a 2f 0a 53 51 4c 49 [H10102].*/.SQLI
1930: 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
1940: 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
1950: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
1960: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 te3_threadsafe(v
1970: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 oid);../*.** CAP
1980: 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 I3REF: Database
1990: 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c Connection Handl
19a0: 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 30 32 e {H12000} <S402
19b0: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 00>.** KEYWORDS:
19c0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 {database conne
19d0: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 ction} {database
19e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a connections}.**
19f0: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 .** Each open SQ
1a00: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 Lite database is
1a10: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
1a20: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
1a30: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 instance of.** t
1a40: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 he opaque struct
1a50: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 ure named "sqlit
1a60: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 e3". It is usef
1a70: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 ul to think of a
1a80: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 n sqlite3.** poi
1a90: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 nter as an objec
1aa0: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 t. The [sqlite3
1ab0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
1ac0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e e3_open16()], an
1ad0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 d.** [sqlite3_op
1ae0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 en_v2()] interfa
1af0: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 ces are its cons
1b00: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 tructors, and [s
1b10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a qlite3_close()].
1b20: 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 72 75 ** is its destru
1b30: 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65 ctor. There are
1b40: 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 many other inte
1b50: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a rfaces (such as.
1b60: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
1b70: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
1b80: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
1b90: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b ion()], and.** [
1ba0: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
1bb0: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 eout()] to name
1bc0: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 but three) that
1bd0: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 are methods on a
1be0: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a n.** sqlite3 obj
1bf0: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ect..*/.typedef
1c00: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 struct sqlite3 s
1c10: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 qlite3;../*.** C
1c20: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 API3REF: 64-Bit
1c30: 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b 48 Integer Types {H
1c40: 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 10200} <S10110>.
1c50: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
1c60: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 ite_int64 sqlite
1c70: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 _uint64.**.** Be
1c80: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e cause there is n
1c90: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d o cross-platform
1ca0: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 way to specify
1cb0: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 64-bit integer t
1cc0: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 ypes.** SQLite i
1cd0: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 ncludes typedefs
1ce0: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e for 64-bit sign
1cf0: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 ed and unsigned
1d00: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 integers..**.**
1d10: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 The sqlite3_int6
1d20: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 4 and sqlite3_ui
1d30: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65 nt64 are the pre
1d40: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69 ferred type defi
1d50: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 nitions..** The
1d60: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 sqlite_int64 and
1d70: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 sqlite_uint64 t
1d80: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 ypes are support
1d90: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ed for backwards
1da0: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 .** compatibilit
1db0: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 y only..**.** Re
1dc0: 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 quirements: [H10
1dd0: 32 30 31 5d 20 5b 48 31 30 32 30 32 5d 0a 2a 2f 201] [H10202].*/
1de0: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 .#ifdef SQLITE_I
1df0: 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 NT64_TYPE. type
1e00: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 def SQLITE_INT64
1e10: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 _TYPE sqlite_int
1e20: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 64;. typedef un
1e30: 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e signed SQLITE_IN
1e40: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f T64_TYPE sqlite_
1e50: 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 uint64;.#elif de
1e60: 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 fined(_MSC_VER)
1e70: 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 || defined(__BOR
1e80: 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 LANDC__). typed
1e90: 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 ef __int64 sqlit
1ea0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 e_int64;. typed
1eb0: 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e ef unsigned __in
1ec0: 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 t64 sqlite_uint6
1ed0: 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 4;.#else. typed
1ee0: 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 ef long long int
1ef0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 sqlite_int64;.
1f00: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 typedef unsigne
1f10: 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 d long long int
1f20: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 sqlite_uint64;.#
1f30: 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 endif.typedef sq
1f40: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 lite_int64 sqlit
1f50: 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 e3_int64;.typede
1f60: 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 f sqlite_uint64
1f70: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a sqlite3_uint64;.
1f80: 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c ./*.** If compil
1f90: 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 ing for a proces
1fa0: 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 sor that lacks f
1fb0: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 loating point su
1fc0: 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 pport,.** substi
1fd0: 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 tute integer for
1fe0: 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e floating-point.
1ff0: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 .*/.#ifdef SQLIT
2000: 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f E_OMIT_FLOATING_
2010: 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 POINT.# define d
2020: 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e ouble sqlite3_in
2030: 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a t64.#endif../*.*
2040: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 * CAPI3REF: Clos
2050: 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 ing A Database C
2060: 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 onnection {H1201
2070: 30 7d 20 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 0} <S30100><S402
2080: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 00>.**.** This r
2090: 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64 65 outine is the de
20a0: 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 structor for the
20b0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
20c0: 74 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 t..**.** Applica
20d0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 tions should [sq
20e0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c lite3_finalize |
20f0: 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b finalize] all [
2100: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2110: 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c nts].** and [sql
2120: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 ite3_blob_close
2130: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c | close] all [BL
2140: 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f OB handles] asso
2150: 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 ciated with.** t
2160: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a he [sqlite3] obj
2170: 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 ect prior to att
2180: 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 empting to close
2190: 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 the object..**
21a0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 The [sqlite3_nex
21b0: 74 5f 73 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 t_stmt()] interf
21c0: 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ace can be used
21d0: 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a to locate all.**
21e0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
21f0: 6d 65 6e 74 73 5d 20 61 73 73 6f 63 69 61 74 65 ments] associate
2200: 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 d with a [databa
2210: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
2220: 66 20 64 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 f desired..** Ty
2230: 70 69 63 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 pical code might
2240: 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a look like this:
2250: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
2260: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 te><pre>.** sqli
2270: 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b te3_stmt *pStmt;
2280: 0a 2a 2a 20 77 68 69 6c 65 28 20 28 70 53 74 6d .** while( (pStm
2290: 74 20 3d 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 t = sqlite3_next
22a0: 5f 73 74 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 _stmt(db, 0))!=0
22b0: 20 29 7b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 ){.**
22c0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
22d0: 28 70 53 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a (pStmt);.** }.**
22e0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
22f0: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 ote>.**.** If [s
2300: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 qlite3_close()]
2310: 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 is invoked while
2320: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
2330: 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 s open,.** the t
2340: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 ransaction is au
2350: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c tomatically roll
2360: 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 ed back..**.** T
2370: 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 he C parameter t
2380: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 o [sqlite3_close
2390: 28 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 (C)] must be eit
23a0: 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f her a NULL.** po
23b0: 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c inter or an [sql
23c0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 ite3] object poi
23d0: 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a nter obtained.**
23e0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f from [sqlite3_o
23f0: 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
2400: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a _open16()], or.*
2410: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f * [sqlite3_open_
2420: 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 v2()], and not p
2430: 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 reviously closed
2440: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
2450: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 30 31 31 ents:.** [H12011
2460: 5d 20 5b 48 31 32 30 31 32 5d 20 5b 48 31 32 30 ] [H12012] [H120
2470: 31 33 5d 20 5b 48 31 32 30 31 34 5d 20 5b 48 31 13] [H12014] [H1
2480: 32 30 31 35 5d 20 5b 48 31 32 30 31 39 5d 0a 2a 2015] [H12019].*
2490: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c /.SQLITE_API SQL
24a0: 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
24b0: 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e PI SQLITE_API in
24c0: 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 t sqlite3_close(
24d0: 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a sqlite3 *);../*.
24e0: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 ** The type for
24f0: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
2500: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 ion..** This is
2510: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 legacy and depre
2520: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e cated. It is in
2530: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f cluded for histo
2540: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 rical.** compati
2550: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f bility and is no
2560: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f t documented..*/
2570: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 .typedef int (*s
2580: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 qlite3_callback)
2590: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a (void*,int,char*
25a0: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a *, char**);../*.
25b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 ** CAPI3REF: One
25c0: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 -Step Query Exec
25d0: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 20 ution Interface
25e0: 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30 30 30 {H12100} <S10000
25f0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
2600: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 te3_exec() inter
2610: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e face is a conven
2620: 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75 6e 6e ient way of runn
2630: 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a ing one or more.
2640: 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
2650: 73 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 s without having
2660: 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f 74 20 to write a lot
2670: 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68 65 20 of C code. The
2680: 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a 2a 2a UTF-8 encoded.**
2690: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
26a0: 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61 73 are passed in as
26b0: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
26c0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
26d0: 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68 65 20 _exec()..** The
26e0: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 statements are e
26f0: 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79 20 valuated one by
2700: 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68 65 72 one until either
2710: 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a 2a 20 an error or.**
2720: 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73 20 an interrupt is
2730: 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f 72 20 encountered, or
2740: 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 20 61 until they are a
2750: 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 33 72 ll done. The 3r
2760: 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 d parameter.** i
2770: 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63 61 s an optional ca
2780: 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 20 69 llback that is i
2790: 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 nvoked once for
27a0: 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e 79 20 each row of any
27b0: 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c 74 73 query.** results
27c0: 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 68 65 produced by the
27d0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e SQL statements.
27e0: 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 The 5th parame
27f0: 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 65 0a ter tells where.
2800: 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e 79 20 ** to write any
2810: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 2e 0a error messages..
2820: 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f 72 20 **.** The error
2830: 6d 65 73 73 61 67 65 20 70 61 73 73 65 64 20 62 message passed b
2840: 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 ack through the
2850: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 5th parameter is
2860: 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d 6f held.** in memo
2870: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ry obtained from
2880: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
2890: 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64 20 61 ()]. To avoid a
28a0: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a 2a memory leak,.**
28b0: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61 70 70 the calling app
28c0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
28d0: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 call [sqlite3_fr
28e0: 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65 72 72 ee()] on any err
28f0: 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 72 65 or.** message re
2900: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 turned through t
2910: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
2920: 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e when it has fin
2930: 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 ished using.** t
2940: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
2950: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 ..**.** If the S
2960: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 QL statement in
2970: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
2980: 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 r is NULL or an
2990: 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a 2a 20 empty string.**
29a0: 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 or a string cont
29b0: 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 69 74 aining only whit
29c0: 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d 6d 65 espace and comme
29d0: 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c nts, then no SQL
29e0: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 61 .** statements a
29f0: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 re evaluated and
2a00: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
2a10: 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a not changed..**
2a20: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
2a30: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 exec() interface
2a40: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 is implemented
2a50: 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b in terms of.** [
2a60: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2a70: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f v2()], [sqlite3_
2a80: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 step()], and [sq
2a90: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
2aa0: 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 ]..** The sqlite
2ab0: 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69 6e 65 3_exec() routine
2ac0: 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74 6f does nothing to
2ad0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68 the database th
2ae0: 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e at cannot be don
2af0: 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 e.** by [sqlite3
2b00: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 _prepare_v2()],
2b10: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2b20: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 , and [sqlite3_f
2b30: 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a inalize()]..**.*
2b40: 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 * The first para
2b50: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
2b60: 33 5f 65 78 65 63 28 29 5d 20 6d 75 73 74 20 62 3_exec()] must b
2b70: 65 20 61 6e 20 76 61 6c 69 64 20 61 6e 64 20 6f e an valid and o
2b80: 70 65 6e 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 pen.** [database
2b90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
2ba0: 0a 2a 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 .** The database
2bb0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 connection must
2bc0: 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20 77 not be closed w
2bd0: 68 69 6c 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 hile.** [sqlite3
2be0: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e _exec()] is runn
2bf0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ing..**.** The c
2c00: 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 alling function
2c10: 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 should use [sqli
2c20: 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 te3_free()] to f
2c30: 72 65 65 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 ree.** the memor
2c40: 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67 20 69 y that *errmsg i
2c50: 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 s left pointing
2c60: 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72 72 6f at once the erro
2c70: 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 69 73 20 r.** message is
2c80: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 no longer needed
2c90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 20 ..**.** The SQL
2ca0: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 statement text i
2cb0: 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 n the 2nd parame
2cc0: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
2cd0: 65 78 65 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 exec()].** must
2ce0: 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 remain unchanged
2cf0: 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f while [sqlite3_
2d00: 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 exec()] is runni
2d10: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ng..**.** Requir
2d20: 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 31 ements:.** [H121
2d30: 30 31 5d 20 5b 48 31 32 31 30 32 5d 20 5b 48 31 01] [H12102] [H1
2d40: 32 31 30 34 5d 20 5b 48 31 32 31 30 35 5d 20 5b 2104] [H12105] [
2d50: 48 31 32 31 30 37 5d 20 5b 48 31 32 31 31 30 5d H12107] [H12110]
2d60: 20 5b 48 31 32 31 31 33 5d 20 5b 48 31 32 31 31 [H12113] [H1211
2d70: 36 5d 0a 2a 2a 20 5b 48 31 32 31 31 39 5d 20 5b 6].** [H12119] [
2d80: 48 31 32 31 32 32 5d 20 5b 48 31 32 31 32 35 5d H12122] [H12125]
2d90: 20 5b 48 31 32 31 33 31 5d 20 5b 48 31 32 31 33 [H12131] [H1213
2da0: 34 5d 20 5b 48 31 32 31 33 37 5d 20 5b 48 31 32 4] [H12137] [H12
2db0: 31 33 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 138].*/.SQLITE_A
2dc0: 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
2dd0: 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
2de0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2df0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a exec(. sqlite3*
2e00: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
2e10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2e20: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 /* An open da
2e30: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 tabase */. cons
2e40: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 t char *sql,
2e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2e60: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f /* SQL to
2e70: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
2e80: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 . int (*callbac
2e90: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
2ea0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a r**,char**), /*
2eb0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 Callback functi
2ec0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 on */. void *,
2ed0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2ee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2ef0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 /* 1st argume
2f00: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a nt to callback *
2f10: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 /. char **errms
2f20: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 g
2f30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
2f40: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
2f50: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a ten here */.);..
2f60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2f70: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 Result Codes {H1
2f80: 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 0210} <S10700>.*
2f90: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 * KEYWORDS: SQLI
2fa0: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 TE_OK {error cod
2fb0: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d e} {error codes}
2fc0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 .** KEYWORDS: {r
2fd0: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 esult code} {res
2fe0: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a ult codes}.**.**
2ff0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e Many SQLite fun
3000: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e ctions return an
3010: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 integer result
3020: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 code from the se
3030: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 t shown.** here
3040: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 in order to indi
3050: 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f 72 cates success or
3060: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 failure..**.**
3070: 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 New error codes
3080: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
3090: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 future versions
30a0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
30b0: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 See also: [SQLI
30c0: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 TE_IOERR_READ |
30d0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
30e0: 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e codes].*/.#defin
30f0: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 e SQLITE_OK
3100: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 0 /* Suc
3110: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a cessful result *
3120: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f /./* beginning-o
3130: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f f-error-codes */
3140: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3150: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 ERROR 1
3160: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 /* SQL error or
3170: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 missing databas
3180: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
3190: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 ITE_INTERNAL
31a0: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 2 /* Internal
31b0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 logic error in
31c0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e SQLite */.#defin
31d0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 e SQLITE_PERM
31e0: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 3 /* Acc
31f0: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 ess permission d
3200: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 enied */.#define
3210: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 SQLITE_ABORT
3220: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 4 /* Call
3230: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 back routine req
3240: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 uested an abort
3250: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
3260: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 E_BUSY 5
3270: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 /* The databa
3280: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 se file is locke
3290: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
32a0: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 ITE_LOCKED
32b0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 6 /* A table
32c0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 in the database
32d0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 is locked */.#de
32e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 fine SQLITE_NOME
32f0: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 M 7 /*
3300: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 A malloc() faile
3310: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
3320: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 ITE_READONLY
3330: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 8 /* Attempt
3340: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f to write a reado
3350: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a nly database */.
3360: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3370: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 NTERRUPT 9
3380: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 /* Operation ter
3390: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 minated by sqlit
33a0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f e3_interrupt()*/
33b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
33c0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 IOERR 10
33d0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 /* Some kind of
33e0: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 disk I/O error
33f0: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 occurred */.#def
3400: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 ine SQLITE_CORRU
3410: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 PT 11 /* T
3420: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b he database disk
3430: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 image is malfor
3440: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 med */.#define S
3450: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 QLITE_NOTFOUND
3460: 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 12 /* NOT US
3470: 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 ED. Table or rec
3480: 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f ord not found */
3490: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
34a0: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 FULL 13
34b0: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 /* Insertion fa
34c0: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 iled because dat
34d0: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f abase is full */
34e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
34f0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 CANTOPEN 14
3500: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 /* Unable to op
3510: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
3520: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 file */.#define
3530: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 SQLITE_PROTOCOL
3540: 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 15 /* NOT U
3550: 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f SED. Database lo
3560: 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f ck protocol erro
3570: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
3580: 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 ITE_EMPTY
3590: 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 16 /* Database
35a0: 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 is empty */.#de
35b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 fine SQLITE_SCHE
35c0: 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 MA 17 /*
35d0: 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 The database sch
35e0: 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 ema changed */.#
35f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f define SQLITE_TO
3600: 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f OBIG 18 /
3610: 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 * String or BLOB
3620: 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 exceeds size li
3630: 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 mit */.#define S
3640: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
3650: 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 19 /* Abort
3660: 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e due to constrain
3670: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 t violation */.#
3680: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 define SQLITE_MI
3690: 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f SMATCH 20 /
36a0: 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d * Data type mism
36b0: 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 atch */.#define
36c0: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 SQLITE_MISUSE
36d0: 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 21 /* Libra
36e0: 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 ry used incorrec
36f0: 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 tly */.#define S
3700: 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 QLITE_NOLFS
3710: 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 22 /* Uses O
3720: 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 S features not s
3730: 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 upported on host
3740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
3750: 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 TE_AUTH 2
3760: 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 3 /* Authoriza
3770: 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 tion denied */.#
3780: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f define SQLITE_FO
3790: 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f RMAT 24 /
37a0: 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 * Auxiliary data
37b0: 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f base format erro
37c0: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
37d0: 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 ITE_RANGE
37e0: 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 25 /* 2nd para
37f0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
3800: 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e _bind out of ran
3810: 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ge */.#define SQ
3820: 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 LITE_NOTADB
3830: 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 26 /* File op
3840: 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 ened that is not
3850: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
3860: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
3870: 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 TE_ROW 1
3880: 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 00 /* sqlite3_s
3890: 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 tep() has anothe
38a0: 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 r row ready */.#
38b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f define SQLITE_DO
38c0: 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f NE 101 /
38d0: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
38e0: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 has finished ex
38f0: 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e ecuting */./* en
3900: 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 d-of-error-codes
3910: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
3920: 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 REF: Extended Re
3930: 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 30 32 sult Codes {H102
3940: 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 20} <S10700>.**
3950: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e KEYWORDS: {exten
3960: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 ded error code}
3970: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 {extended error
3980: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 codes}.** KEYWOR
3990: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 DS: {extended re
39a0: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 sult code} {exte
39b0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
39c0: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 s}.**.** In its
39d0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 default configur
39e0: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 ation, SQLite AP
39f0: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 I routines retur
3a00: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 n one of 26 inte
3a10: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f ger.** [SQLITE_O
3a20: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 K | result codes
3a30: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 ]. However, exp
3a40: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 erience has show
3a50: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a n that many of.*
3a60: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 * these result c
3a70: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 odes are too coa
3a80: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 rse-grained. Th
3a90: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 ey do not provid
3aa0: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 e as.** much inf
3ab0: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 ormation about p
3ac0: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 roblems as progr
3ad0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b ammers might lik
3ae0: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 e. In an effort
3af0: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 to.** address t
3b00: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 his, newer versi
3b10: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 ons of SQLite (v
3b20: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 ersion 3.3.8 and
3b30: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a later) include.
3b40: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 ** support for a
3b50: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 dditional result
3b60: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 codes that prov
3b70: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 ide more detaile
3b80: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a d information.**
3b90: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 about errors. T
3ba0: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 he extended resu
3bb0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 lt codes are ena
3bc0: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 bled or disabled
3bd0: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 .** on a per dat
3be0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3bf0: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 basis using the
3c00: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 .** [sqlite3_ext
3c10: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
3c20: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a es()] API..**.**
3c30: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 Some of the ava
3c40: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 ilable extended
3c50: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
3c60: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a listed here..**
3c70: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20 One may expect
3c80: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 the number of ex
3c90: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
3ca0: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61 des will be expa
3cb0: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e nd.** over time.
3cc0: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 Software that
3cd0: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65 uses extended re
3ce0: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c sult codes shoul
3cf0: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 d expect.** to s
3d00: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f ee new result co
3d10: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 des in future re
3d20: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
3d30: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ..**.** The SQLI
3d40: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 TE_OK result cod
3d50: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 e will never be
3d60: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 extended. It wi
3d70: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 ll always.** be
3d80: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f exactly zero..*/
3d90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3da0: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 IOERR_READ
3db0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
3dc0: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a IOERR | (1<<8)).
3dd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3de0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 OERR_SHORT_READ
3df0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3e00: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 OERR | (2<<8)).#
3e10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
3e20: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 ERR_WRITE
3e30: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
3e40: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 ERR | (3<<8)).#d
3e50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
3e60: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 RR_FSYNC
3e70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
3e80: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 RR | (4<<8)).#de
3e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
3ea0: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 R_DIR_FSYNC
3eb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
3ec0: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 R | (5<<8)).#def
3ed0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
3ee0: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 _TRUNCATE
3ef0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
3f00: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 | (6<<8)).#defi
3f10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
3f20: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20 FSTAT
3f30: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
3f40: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (7<<8)).#defin
3f50: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 e SQLITE_IOERR_U
3f60: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 NLOCK
3f70: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
3f80: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (8<<8)).#define
3f90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 SQLITE_IOERR_RD
3fa0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 LOCK
3fb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
3fc0: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (9<<8)).#define
3fd0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c SQLITE_IOERR_DEL
3fe0: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28 ETE (
3ff0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
4000: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 10<<8)).#define
4010: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
4020: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28 CKED (
4030: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
4040: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 11<<8)).#define
4050: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d SQLITE_IOERR_NOM
4060: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28 EM (
4070: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
4080: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 12<<8)).#define
4090: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 SQLITE_IOERR_ACC
40a0: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28 ESS (
40b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
40c0: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 13<<8)).#define
40d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 SQLITE_IOERR_CHE
40e0: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 CKRESERVEDLOCK (
40f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
4100: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 14<<8)).#define
4110: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 SQLITE_IOERR_LOC
4120: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 K (
4130: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
4140: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 15<<8)).#define
4150: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f SQLITE_IOERR_CLO
4160: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 SE (
4170: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
4180: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 16<<8)).#define
4190: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 SQLITE_IOERR_DIR
41a0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 _CLOSE (
41b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
41c0: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 17<<8)).#define
41d0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 SQLITE_LOCKED_SH
41e0: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28 AREDCACHE (
41f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 SQLITE_LOCKED |
4200: 28 31 3c 3c 38 29 20 29 0a 0a 2f 2a 0a 2a 2a 20 (1<<8) )../*.**
4210: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 CAPI3REF: Flags
4220: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 For File Open Op
4230: 65 72 61 74 69 6f 6e 73 20 7b 48 31 30 32 33 30 erations {H10230
4240: 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48 31 32 37 } <H11120> <H127
4250: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 00>.**.** These
4260: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 bit values are i
4270: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 ntended for use
4280: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 in the.** 3rd pa
4290: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b rameter to the [
42a0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
42b0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 )] interface and
42c0: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 .** in the 4th p
42d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
42e0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 xOpen method of
42f0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
4300: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a vfs] object..*/.
4310: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
4320: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 PEN_READONLY
4330: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 0x00000001
4340: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
4350: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
4360: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
4370: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 PEN_READWRITE
4380: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 0x00000002
4390: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
43a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
43b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
43c0: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 PEN_CREATE
43d0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 0x00000004
43e0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
43f0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
4400: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
4410: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
4420: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 E 0x00000008
4430: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
4440: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
4450: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 PEN_EXCLUSIVE
4460: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 0x00000010
4470: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
4480: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
4490: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 PEN_MAIN_DB
44a0: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 0x00000100
44b0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
44c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
44d0: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 PEN_TEMP_DB
44e0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 0x00000200
44f0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
4510: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 PEN_TRANSIENT_DB
4520: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 0x00000400
4530: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
4540: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
4550: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c PEN_MAIN_JOURNAL
4560: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 0x00000800
4570: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
4580: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
4590: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c PEN_TEMP_JOURNAL
45a0: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 0x00001000
45b0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
45c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
45d0: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 PEN_SUBJOURNAL
45e0: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 0x00002000
45f0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
4610: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e PEN_MASTER_JOURN
4620: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 AL 0x00004000
4630: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
4640: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
4650: 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 PEN_NOMUTEX
4660: 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 0x00008000
4670: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
4680: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
4690: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
46a0: 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 PEN_FULLMUTEX
46b0: 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 0x00010000
46c0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
46d0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
46e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
46f0: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65 Device Characte
4700: 72 69 73 74 69 63 73 20 7b 48 31 30 32 34 30 7d ristics {H10240}
4710: 20 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 <H11120>.**.**
4720: 54 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62 The xDeviceCapab
4730: 69 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f ilities method o
4740: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 f the [sqlite3_i
4750: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 o_methods].** ob
4760: 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 ject returns an
4770: 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 integer which is
4780: 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 a vector of the
4790: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 these.** bit va
47a0: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 lues expressing
47b0: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 I/O characterist
47c0: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 ics of the mass
47d0: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 storage.** devic
47e0: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 e that holds the
47f0: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b file that the [
4800: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
4810: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f ds].** refers to
4820: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ..**.** The SQLI
4830: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 TE_IOCAP_ATOMIC
4840: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
4850: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f hat all writes o
4860: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 f.** any size ar
4870: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
4880: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
4890: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 ICnnn values.**
48a0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 mean that writes
48b0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 of blocks that
48c0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e are nnn bytes in
48d0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 size and.** are
48e0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 aligned to an a
48f0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 ddress which is
4900: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 an integer multi
4910: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 ple of.** nnn ar
4920: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
4930: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
4940: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 _APPEND value me
4950: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e ans.** that when
4960: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
4970: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 d to a file, the
4980: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
4990: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 d.** first then
49a0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
49b0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 file is extended
49c0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 , never the othe
49d0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e r.** way around.
49e0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
49f0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 AP_SEQUENTIAL pr
4a00: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 operty means tha
4a10: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e t.** information
4a20: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 is written to d
4a30: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 isk in the same
4a40: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a order as calls.*
4a50: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a * to xWrite()..*
4a60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4a70: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 _IOCAP_ATOMIC
4a80: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
4a90: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
4aa0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 _IOCAP_ATOMIC512
4ab0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
4ac0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
4ad0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 _IOCAP_ATOMIC1K
4ae0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
4af0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
4b00: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 _IOCAP_ATOMIC2K
4b10: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
4b20: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
4b30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 _IOCAP_ATOMIC4K
4b40: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 0x0000001
4b50: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
4b60: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 _IOCAP_ATOMIC8K
4b70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 0x0000002
4b80: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
4b90: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b _IOCAP_ATOMIC16K
4ba0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 0x0000004
4bb0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
4bc0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b _IOCAP_ATOMIC32K
4bd0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 0x0000008
4be0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
4bf0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b _IOCAP_ATOMIC64K
4c00: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 0x0000010
4c10: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
4c20: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
4c30: 4e 44 20 20 20 20 20 30 78 30 30 30 30 30 32 30 ND 0x0000020
4c40: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
4c50: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
4c60: 4c 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 L 0x0000040
4c70: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 0../*.** CAPI3RE
4c80: 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 F: File Locking
4c90: 4c 65 76 65 6c 73 20 7b 48 31 30 32 35 30 7d 20 Levels {H10250}
4ca0: 3c 48 31 31 31 32 30 3e 20 3c 48 31 31 33 31 30 <H11120> <H11310
4cb0: 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 >.**.** SQLite u
4cc0: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 ses one of these
4cd0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 integer values
4ce0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a as the second.**
4cf0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c argument to cal
4d00: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 ls it makes to t
4d10: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 he xLock() and x
4d20: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 Unlock() methods
4d30: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 .** of an [sqlit
4d40: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
4d50: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e bject..*/.#defin
4d60: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f e SQLITE_LOCK_NO
4d70: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 NE 0.#d
4d80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
4d90: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 K_SHARED
4da0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
4db0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 _LOCK_RESERVED
4dc0: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
4dd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e LITE_LOCK_PENDIN
4de0: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e G 3.#defin
4df0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 e SQLITE_LOCK_EX
4e00: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f CLUSIVE 4../
4e10: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
4e20: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 ynchronization T
4e30: 79 70 65 20 46 6c 61 67 73 20 7b 48 31 30 32 36 ype Flags {H1026
4e40: 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 0} <H11120>.**.*
4e50: 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e * When SQLite in
4e60: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 vokes the xSync(
4e70: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a ) method of an.*
4e80: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 * [sqlite3_io_me
4e90: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 thods] object it
4ea0: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 uses a combinat
4eb0: 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 ion of.** these
4ec0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 integer values a
4ed0: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
4ee0: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 ument..**.** Whe
4ef0: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e n the SQLITE_SYN
4f00: 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 C_DATAONLY flag
4f10: 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e is used, it mean
4f20: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 s that the.** sy
4f30: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c nc operation onl
4f40: 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 y needs to flush
4f50: 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 data to mass st
4f60: 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a orage. Inode.**
4f70: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 information nee
4f80: 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 d not be flushed
4f90: 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 . If the lower f
4fa0: 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 our bits of the
4fb0: 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 flag.** equal SQ
4fc0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
4fd0: 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 , that means to
4fe0: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 use normal fsync
4ff0: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a () semantics..**
5000: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f If the lower fo
5010: 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 ur bits equal SQ
5020: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 LITE_SYNC_FULL,
5030: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f that means.** to
5040: 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 use Mac OS X st
5050: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 yle fullsync ins
5060: 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e tead of fsync().
5070: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
5080: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 TE_SYNC_NORMAL
5090: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 0x00002.#d
50a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e efine SQLITE_SYN
50b0: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 C_FULL
50c0: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 0x00003.#define
50d0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 SQLITE_SYNC_DATA
50e0: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 ONLY 0x0001
50f0: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 0../*.** CAPI3RE
5100: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 F: OS Interface
5110: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 Open File Handle
5120: 20 7b 48 31 31 31 31 30 7d 20 3c 53 32 30 31 31 {H11110} <S2011
5130: 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 0>.**.** An [sql
5140: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
5150: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 t represents an
5160: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 open file in the
5170: 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 OS.** interface
5180: 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 69 64 layer. Individ
5190: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 ual OS interface
51a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
51b0: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f will.** want to
51c0: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f subclass this o
51d0: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 bject by appendi
51e0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 ng additional fi
51f0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 elds.** for thei
5200: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 r own use. The
5210: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 pMethods entry i
5220: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
5230: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f n.** [sqlite3_io
5240: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
5250: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 that defines me
5260: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 thods for perfor
5270: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 ming.** I/O oper
5280: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 ations on the op
5290: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 en file..*/.type
52a0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
52b0: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f e3_file sqlite3_
52c0: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c file;.struct sql
52d0: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f ite3_file {. co
52e0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 nst struct sqlit
52f0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 e3_io_methods *p
5300: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 Methods; /* Met
5310: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e hods for an open
5320: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a file */.};../*.
5330: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 ** CAPI3REF: OS
5340: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 Interface File V
5350: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f irtual Methods O
5360: 62 6a 65 63 74 20 7b 48 31 31 31 32 30 7d 20 3c bject {H11120} <
5370: 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 45 76 S20110>.**.** Ev
5380: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 ery file opened
5390: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
53a0: 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f vfs] xOpen metho
53b0: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a d populates an.*
53c0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d * [sqlite3_file]
53d0: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 object (or, mor
53e0: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 e commonly, a su
53f0: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a bclass of the.**
5400: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
5410: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 object) with a p
5420: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
5430: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
5440: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 ject..** This ob
5450: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 ject defines the
5460: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f methods used to
5470: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 perform various
5480: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 operations.** a
5490: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 gainst the open
54a0: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 file represented
54b0: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 by the [sqlite3
54c0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a _file] object..*
54d0: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f 70 65 *.** If the xOpe
54e0: 6e 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 n method sets th
54f0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 e sqlite3_file.p
5500: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 Methods element
5510: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c .** to a non-NUL
5520: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 L pointer, then
5530: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d the sqlite3_io_m
5540: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 ethods.xClose me
5550: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 thod.** may be i
5560: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 nvoked even if t
5570: 68 65 20 78 4f 70 65 6e 20 72 65 70 6f 72 74 65 he xOpen reporte
5580: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 d that it failed
5590: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 . The.** only w
55a0: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 ay to prevent a
55b0: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 call to xClose f
55c0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 ollowing a faile
55d0: 64 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 66 6f d xOpen.** is fo
55e0: 72 20 74 68 65 20 78 4f 70 65 6e 20 74 6f 20 73 r the xOpen to s
55f0: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 et the sqlite3_f
5600: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 ile.pMethods ele
5610: 6d 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a ment to NULL..**
5620: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 .** The flags ar
5630: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 gument to xSync
5640: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 may be one of [S
5650: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 QLITE_SYNC_NORMA
5660: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 L] or.** [SQLITE
5670: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 _SYNC_FULL]. Th
5680: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 e first choice i
5690: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 s the normal fsy
56a0: 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 nc()..** The sec
56b0: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 ond choice is a
56c0: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 Mac OS X style f
56d0: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 ullsync. The [S
56e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f QLITE_SYNC_DATAO
56f0: 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 NLY].** flag may
5700: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 be ORed in to i
5710: 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c ndicate that onl
5720: 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 y the data of th
5730: 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f e file.** and no
5740: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 t its inode need
5750: 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a s to be synced..
5760: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 **.** The intege
5770: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 r values to xLoc
5780: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 k() and xUnlock(
5790: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 ) are one of.**
57a0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
57b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c LITE_LOCK_NONE],
57c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
57d0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a _LOCK_SHARED],.*
57e0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c * <li> [SQLITE_L
57f0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a OCK_RESERVED],.*
5800: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c * <li> [SQLITE_L
5810: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 OCK_PENDING], or
5820: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
5830: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d _LOCK_EXCLUSIVE]
5840: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c ..** </ul>.** xL
5850: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 ock() increases
5860: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 the lock. xUnloc
5870: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 k() decreases th
5880: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 e lock..** The x
5890: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 CheckReservedLoc
58a0: 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b k() method check
58b0: 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 s whether any da
58c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
58d0: 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 n,.** either in
58e0: 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 this process or
58f0: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 in some other pr
5900: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e ocess, is holdin
5910: 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a g a RESERVED,.**
5920: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 PENDING, or EXC
5930: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 LUSIVE lock on t
5940: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 he file. It ret
5950: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 urns true.** if
5960: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 such a lock exis
5970: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 ts and false oth
5980: 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 erwise..**.** Th
5990: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 e xFileControl()
59a0: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e method is a gen
59b0: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 eric interface t
59c0: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f hat allows custo
59d0: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 m.** VFS impleme
59e0: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 ntations to dire
59f0: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 ctly control an
5a00: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 open file using
5a10: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
5a20: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
5a30: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 interface. The
5a40: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 second "op" argu
5a50: 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e ment is an.** in
5a60: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 teger opcode. T
5a70: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
5a80: 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 t is a generic p
5a90: 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 ointer intended
5aa0: 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 to.** point to a
5ab0: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 structure that
5ac0: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 may contain argu
5ad0: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 ments or space i
5ae0: 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 n which to.** wr
5af0: 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 ite return value
5b00: 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 s. Potential us
5b10: 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 es for xFileCont
5b20: 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a rol() might be.*
5b30: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 * functions to e
5b40: 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c nable blocking l
5b50: 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 ocks with timeou
5b60: 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 ts, to change th
5b70: 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 e.** locking str
5b80: 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 ategy (for examp
5b90: 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 le to use dot-fi
5ba0: 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e le locks), to in
5bb0: 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 quire.** about t
5bc0: 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c he status of a l
5bd0: 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b ock, or to break
5be0: 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 stale locks. T
5bf0: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 he SQLite.** cor
5c00: 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f e reserves all o
5c10: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e pcodes less than
5c20: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 100 for its own
5c30: 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 use..** A [SQLI
5c40: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
5c50: 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 TE | list of opc
5c60: 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 odes] less than
5c70: 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 100 is available
5c80: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e ..** Application
5c90: 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 s that define a
5ca0: 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 custom xFileCont
5cb0: 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c rol method shoul
5cc0: 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a d use opcodes.**
5cd0: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 greater than 10
5ce0: 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 0 to avoid confl
5cf0: 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 icts..**.** The
5d00: 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 xSectorSize() me
5d10: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 thod returns the
5d20: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 sector size of
5d30: 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 the.** device th
5d40: 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 at underlies the
5d50: 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 file. The sect
5d60: 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a or size is the.*
5d70: 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 * minimum write
5d80: 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 that can be perf
5d90: 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 ormed without di
5da0: 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 sturbing.** othe
5db0: 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 r bytes in the f
5dc0: 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 ile. The xDevic
5dd0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 eCharacteristics
5de0: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 ().** method ret
5df0: 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f urns a bit vecto
5e00: 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 r describing beh
5e10: 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a aviors of the.**
5e20: 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 underlying devi
5e30: 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a ce:.**.** <ul>.*
5e40: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
5e50: 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 OCAP_ATOMIC].**
5e60: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
5e70: 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a AP_ATOMIC512].**
5e80: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
5e90: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a CAP_ATOMIC1K].**
5ea0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
5eb0: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a CAP_ATOMIC2K].**
5ec0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
5ed0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a CAP_ATOMIC4K].**
5ee0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
5ef0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a CAP_ATOMIC8K].**
5f00: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
5f10: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a CAP_ATOMIC16K].*
5f20: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
5f30: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a OCAP_ATOMIC32K].
5f40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
5f50: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d IOCAP_ATOMIC64K]
5f60: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
5f70: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
5f80: 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ND].** <li> [SQL
5f90: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e ITE_IOCAP_SEQUEN
5fa0: 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a TIAL].** </ul>.*
5fb0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f *.** The SQLITE_
5fc0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f IOCAP_ATOMIC pro
5fd0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
5fe0: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a all writes of.*
5ff0: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 * any size are a
6000: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 tomic. The SQLI
6010: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e TE_IOCAP_ATOMICn
6020: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 nn values.** mea
6030: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 n that writes of
6040: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 blocks that are
6050: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 nnn bytes in si
6060: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c ze and.** are al
6070: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 igned to an addr
6080: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 ess which is an
6090: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 integer multiple
60a0: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 of.** nnn are a
60b0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 tomic. The SQLI
60c0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
60d0: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 PEND value means
60e0: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 .** that when da
60f0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 ta is appended t
6100: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 o a file, the da
6110: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a ta is appended.*
6120: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 * first then the
6130: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c size of the fil
6140: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e e is extended, n
6150: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a ever the other.*
6160: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 * way around. T
6170: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
6180: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 SEQUENTIAL prope
6190: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a rty means that.*
61a0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 * information is
61b0: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b written to disk
61c0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 in the same ord
61d0: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 er as calls.** t
61e0: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a o xWrite()..**.*
61f0: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 * If xRead() ret
6200: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 urns SQLITE_IOER
6210: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 R_SHORT_READ it
6220: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a must also fill.*
6230: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 * in the unread
6240: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 portions of the
6250: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f buffer with zero
6260: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a s. A VFS that.*
6270: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d * fails to zero-
6280: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 fill short reads
6290: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 might seem to w
62a0: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a ork. However,.*
62b0: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 * failure to zer
62c0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 o-fill short rea
62d0: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c ds will eventual
62e0: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 ly lead to.** da
62f0: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f tabase corruptio
6300: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 n..*/.typedef st
6310: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
6320: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f methods sqlite3_
6330: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 io_methods;.stru
6340: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ct sqlite3_io_me
6350: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 thods {. int iV
6360: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a ersion;. int (*
6370: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f xClose)(sqlite3_
6380: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
6390: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 xRead)(sqlite3_f
63a0: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 ile*, void*, int
63b0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 iAmt, sqlite3_i
63c0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 nt64 iOfst);. i
63d0: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c nt (*xWrite)(sql
63e0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 ite3_file*, cons
63f0: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d t void*, int iAm
6400: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 t, sqlite3_int64
6410: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 iOfst);. int (
6420: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 *xTruncate)(sqli
6430: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 te3_file*, sqlit
6440: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a e3_int64 size);.
6450: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 int (*xSync)(s
6460: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
6470: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 t flags);. int
6480: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c (*xFileSize)(sql
6490: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 ite3_file*, sqli
64a0: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 te3_int64 *pSize
64b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b );. int (*xLock
64c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
64d0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 int);. int (*x
64e0: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f Unlock)(sqlite3_
64f0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 file*, int);. i
6500: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 nt (*xCheckReser
6510: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 vedLock)(sqlite3
6520: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 _file*, int *pRe
6530: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sOut);. int (*x
6540: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c FileControl)(sql
6550: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
6560: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b op, void *pArg);
6570: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 . int (*xSector
6580: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 Size)(sqlite3_fi
6590: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 le*);. int (*xD
65a0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 eviceCharacteris
65b0: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 tics)(sqlite3_fi
65c0: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 le*);. /* Addit
65d0: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 ional methods ma
65e0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
65f0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f ture releases */
6600: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
6610: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 REF: Standard Fi
6620: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 le Control Opcod
6630: 65 73 20 7b 48 31 31 33 31 30 7d 20 3c 53 33 30 es {H11310} <S30
6640: 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 800>.**.** These
6650: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
6660: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 ts are opcodes f
6670: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 or the xFileCont
6680: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 rol method.** of
6690: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f the [sqlite3_io
66a0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
66b0: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 and for the [sq
66c0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
66d0: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 ol()].** interfa
66e0: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 ce..**.** The [S
66f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b QLITE_FCNTL_LOCK
6700: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 STATE] opcode is
6710: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 used for debugg
6720: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 ing. This.** op
6730: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 code causes the
6740: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
6750: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 hod to write the
6760: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f current state o
6770: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f f.** the lock (o
6780: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f ne of [SQLITE_LO
6790: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 CK_NONE], [SQLIT
67a0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a E_LOCK_SHARED],.
67b0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ** [SQLITE_LOCK_
67c0: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 RESERVED], [SQLI
67d0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d TE_LOCK_PENDING]
67e0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 , or [SQLITE_LOC
67f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a K_EXCLUSIVE]).**
6800: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 into an integer
6810: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 that the pArg a
6820: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 rgument points t
6830: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 o. This capabili
6840: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 ty.** is used du
6850: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 ring testing and
6860: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 only needs to b
6870: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e e supported when
6880: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 SQLITE_TEST.**
6890: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 is defined..*/.#
68a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
68b0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 NTL_LOCKSTATE
68c0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
68d0: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 QLITE_GET_LOCKPR
68e0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23 OXYFILE 2.#
68f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 define SQLITE_SE
6900: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 T_LOCKPROXYFILE
6910: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
6920: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f QLITE_LAST_ERRNO
6930: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 0a 4..
6940: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
6950: 4d 75 74 65 78 20 48 61 6e 64 6c 65 20 7b 48 31 Mutex Handle {H1
6960: 37 31 31 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 7110} <S20130>.*
6970: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d *.** The mutex m
6980: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c odule within SQL
6990: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c ite defines [sql
69a0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 ite3_mutex] to b
69b0: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 e an.** abstract
69c0: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 type for a mute
69d0: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 x object. The S
69e0: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 QLite core never
69f0: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 looks.** at the
6a00: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 internal repres
6a10: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b entation of an [
6a20: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 sqlite3_mutex].
6a30: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c It only.** deal
6a40: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 s with pointers
6a50: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
6a60: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a mutex] object..*
6a70: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 *.** Mutexes are
6a80: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b created using [
6a90: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
6aa0: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 loc()]..*/.typed
6ab0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
6ac0: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 3_mutex sqlite3_
6ad0: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 mutex;../*.** CA
6ae0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 PI3REF: OS Inter
6af0: 66 61 63 65 20 4f 62 6a 65 63 74 20 7b 48 31 31 face Object {H11
6b00: 31 34 30 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 140} <S20100>.**
6b10: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
6b20: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 of the sqlite3_v
6b30: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 fs object define
6b40: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 s the interface
6b50: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 between.** the S
6b60: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 QLite core and t
6b70: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 he underlying op
6b80: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 erating system.
6b90: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e The "vfs".** in
6ba0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
6bb0: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 object stands f
6bc0: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 or "virtual file
6bd0: 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 system"..**.**
6be0: 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 The value of the
6bf0: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 iVersion field
6c00: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 is initially 1 b
6c10: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 ut may be larger
6c20: 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 in.** future ve
6c30: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
6c40: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 . Additional fi
6c50: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 elds may be appe
6c60: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 nded to this.**
6c70: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 object when the
6c80: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 iVersion value i
6c90: 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f s increased. No
6ca0: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 te that the stru
6cb0: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 cture.** of the
6cc0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 sqlite3_vfs obje
6cd0: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 ct changes in th
6ce0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 e transaction be
6cf0: 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 tween.** SQLite
6d00: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e version 3.5.9 an
6d10: 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 d 3.6.0 and yet
6d20: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 the iVersion fie
6d30: 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f ld was not.** mo
6d40: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 dified..**.** Th
6d50: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 e szOsFile field
6d60: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 is the size of
6d70: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b the subclassed [
6d80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a sqlite3_file].**
6d90: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 structure used
6da0: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 by this VFS. mx
6db0: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 Pathname is the
6dc0: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f maximum length o
6dd0: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 f.** a pathname
6de0: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a in this VFS..**.
6df0: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71 ** Registered sq
6e00: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 lite3_vfs object
6e10: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 s are kept on a
6e20: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d linked list form
6e30: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 ed by.** the pNe
6e40: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 xt pointer. The
6e50: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 [sqlite3_vfs_re
6e60: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 gister()].** and
6e70: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e [sqlite3_vfs_un
6e80: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 register()] inte
6e90: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 rfaces manage th
6ea0: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 is list.** in a
6eb0: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e thread-safe way.
6ec0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 The [sqlite3_v
6ed0: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 fs_find()] inter
6ee0: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 face.** searches
6ef0: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 the list. Neit
6f00: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 her the applicat
6f10: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 ion code nor the
6f20: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e VFS.** implemen
6f30: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 tation should us
6f40: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e e the pNext poin
6f50: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 ter..**.** The p
6f60: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 Next field is th
6f70: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 e only field in
6f80: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a the sqlite3_vfs.
6f90: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 ** structure tha
6fa0: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 t SQLite will ev
6fb0: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 er modify. SQLi
6fc0: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 te will only acc
6fd0: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 ess.** or modify
6fe0: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c this field whil
6ff0: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 e holding a part
7000: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 icular static mu
7010: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c tex..** The appl
7020: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e ication should n
7030: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 ever modify anyt
7040: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 hing within the
7050: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f sqlite3_vfs.** o
7060: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f bject once the o
7070: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 bject has been r
7080: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a egistered..**.**
7090: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 The zName field
70a0: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 holds the name
70b0: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c of the VFS modul
70c0: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 e. The name mus
70d0: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 t.** be unique a
70e0: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f cross all VFS mo
70f0: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c dules..**.** SQL
7100: 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 ite will guarant
7110: 65 65 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c ee that the zFil
7120: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 ename parameter
7130: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 to xOpen.** is e
7140: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 ither a NULL poi
7150: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f nter or string o
7160: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 btained.** from
7170: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e xFullPathname().
7180: 20 20 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 SQLite further
7190: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
71a0: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 .** the string w
71b0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 ill be valid and
71c0: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c unchanged until
71d0: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 xClose() is.**
71e0: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 called. Because
71f0: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 of the previous
7200: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 sentence,.** the
7210: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
7220: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 can safely store
7230: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
7240: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 e.** filename if
7250: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d it needs to rem
7260: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 ember the filena
7270: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 me for some reas
7280: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 on..** If the zF
7290: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
72a0: 72 20 69 73 20 78 4f 70 65 6e 20 69 73 20 61 20 r is xOpen is a
72b0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
72c0: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 n xOpen.** must
72d0: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 invent its own t
72e0: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f emporary name fo
72f0: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 57 68 65 r the file. Whe
7300: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 never the .** xF
7310: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
7320: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c r is NULL it wil
7330: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 l also be the ca
7340: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 se that the.** f
7350: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 lags parameter w
7360: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c ill include [SQL
7370: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
7380: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 NCLOSE]..**.** T
7390: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
73a0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 t to xOpen() inc
73b0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 ludes all bits s
73c0: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 et in.** the fla
73d0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b gs argument to [
73e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
73f0: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 )]. Or if [sqli
7400: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f te3_open()].** o
7410: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 r [sqlite3_open1
7420: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 6()] is used, th
7430: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 en flags include
7440: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 s at least.** [S
7450: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
7460: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f RITE] | [SQLITE_
7470: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a OPEN_CREATE]. .*
7480: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 * If xOpen() ope
7490: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f ns a file read-o
74a0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 nly then it sets
74b0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a *pOutFlags to.*
74c0: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 * include [SQLIT
74d0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d E_OPEN_READONLY]
74e0: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e . Other bits in
74f0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 *pOutFlags may
7500: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 be set..**.** SQ
7510: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 Lite will also a
7520: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f dd one of the fo
7530: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f llowing flags to
7540: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 the xOpen().**
7550: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 call, depending
7560: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 on the object be
7570: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a ing opened:.**.*
7580: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 * <ul>.** <li>
7590: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 [SQLITE_OPEN_MAI
75a0: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b N_DB].** <li> [
75b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e SQLITE_OPEN_MAIN
75c0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 _JOURNAL].** <li
75d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
75e0: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e TEMP_DB].** <li>
75f0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 [SQLITE_OPEN_T
7600: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 EMP_JOURNAL].**
7610: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
7620: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d EN_TRANSIENT_DB]
7630: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
7640: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 E_OPEN_SUBJOURNA
7650: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
7660: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f ITE_OPEN_MASTER_
7670: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c JOURNAL].** </ul
7680: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 >.**.** The file
7690: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 I/O implementat
76a0: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 ion can use the
76b0: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 object type flag
76c0: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 s to.** change t
76d0: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 he way it deals
76e0: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 with files. For
76f0: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 example, an app
7700: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 lication.** that
7710: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 does not care a
7720: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 bout crash recov
7730: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 ery or rollback
7740: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 might make.** th
7750: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 e open of a jour
7760: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 nal file a no-op
7770: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 . Writes to thi
7780: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a s journal would.
7790: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 ** also be no-op
77a0: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d s, and any attem
77b0: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a pt to read the j
77c0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 ournal would ret
77d0: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f urn.** SQLITE_IO
77e0: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 ERR. Or the imp
77f0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 lementation migh
7800: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 t recognize that
7810: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 a database.** f
7820: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e ile will be doin
7830: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 g page-aligned s
7840: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 ector reads and
7850: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 writes in a rand
7860: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 om.** order and
7870: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 set up its I/O s
7880: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 ubsystem accordi
7890: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 ngly..**.** SQLi
78a0: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 te might also ad
78b0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c d one of the fol
78c0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 lowing flags to
78d0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 the xOpen method
78e0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
78f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 <li> [SQLITE_OPE
7900: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
7910: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
7920: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d _OPEN_EXCLUSIVE]
7930: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
7940: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e The [SQLITE_OPEN
7950: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 _DELETEONCLOSE]
7960: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 flag means the f
7970: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a ile should be.**
7980: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 deleted when it
7990: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 54 68 65 is closed. The
79a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
79b0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 LETEONCLOSE].**
79c0: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 will be set for
79d0: 54 45 4d 50 20 20 64 61 74 61 62 61 73 65 73 2c TEMP databases,
79e0: 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66 6f journals and fo
79f0: 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a r subjournals..*
7a00: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 *.** The [SQLITE
7a10: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d _OPEN_EXCLUSIVE]
7a20: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 flag is always
7a30: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 used in conjunct
7a40: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ion.** with the
7a50: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 [SQLITE_OPEN_CRE
7a60: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 ATE] flag, which
7a70: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 are both direct
7a80: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 ly.** analogous
7a90: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e to the O_EXCL an
7aa0: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 d O_CREAT flags
7ab0: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 of the POSIX ope
7ac0: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 n().** API. The
7ad0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 SQLITE_OPEN_EXC
7ae0: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 LUSIVE flag, whe
7af0: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 n paired with th
7b00: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 e .** SQLITE_OPE
7b10: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 N_CREATE, is use
7b20: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 d to indicate th
7b30: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 at file should a
7b40: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 lways.** be crea
7b50: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 ted, and that it
7b60: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 is an error if
7b70: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 it already exist
7b80: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e s..** It is <i>n
7b90: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 ot</i> used to i
7ba0: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 ndicate the file
7bb0: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 should be opene
7bc0: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 d .** for exclus
7bd0: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a ive access..**.*
7be0: 2a 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 * At least szOsF
7bf0: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d ile bytes of mem
7c00: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 ory are allocate
7c10: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 d by SQLite.** t
7c20: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c o hold the [sql
7c30: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 ite3_file] struc
7c40: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 ture passed as t
7c50: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 he third.** argu
7c60: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 ment to xOpen.
7c70: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 The xOpen method
7c80: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 does not have t
7c90: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 o.** allocate th
7ca0: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 e structure; it
7cb0: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c should just fill
7cc0: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 it in. Note th
7cd0: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 at.** the xOpen
7ce0: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 method must set
7cf0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 the sqlite3_file
7d00: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 .pMethods to eit
7d10: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b her.** a valid [
7d20: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
7d30: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f ds] object or to
7d40: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 NULL. xOpen mu
7d50: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 st do.** this ev
7d60: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 en if the open f
7d70: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 ails. SQLite ex
7d80: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 pects that the s
7d90: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 qlite3_file.pMet
7da0: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 hods.** element
7db0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 will be valid af
7dc0: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e ter xOpen return
7dd0: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 s regardless of
7de0: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f the success.** o
7df0: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 r failure of the
7e00: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a xOpen call..**.
7e10: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 ** The flags arg
7e20: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 ument to xAccess
7e30: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 () may be [SQLIT
7e40: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d E_ACCESS_EXISTS]
7e50: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 .** to test for
7e60: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 the existence of
7e70: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c a file, or [SQL
7e80: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
7e90: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 RITE] to.** test
7ea0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 whether a file
7eb0: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 is readable and
7ec0: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 writable, or [SQ
7ed0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
7ee0: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 ].** to test whe
7ef0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 ther a file is a
7f00: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 t least readable
7f10: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e . The file can
7f20: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f be a.** directo
7f30: 72 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ry..**.** SQLite
7f40: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c will always all
7f50: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d ocate at least m
7f60: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 xPathname+1 byte
7f70: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 s for the.** out
7f80: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c put buffer xFull
7f90: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 Pathname. The e
7fa0: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 xact size of the
7fb0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a output buffer.*
7fc0: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 * is also passed
7fd0: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 as a parameter
7fe0: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 to both methods
7ff0: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 . If the output
8000: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 buffer.** is not
8010: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b large enough, [
8020: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d SQLITE_CANTOPEN]
8030: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 should be retur
8040: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 ned. Since this
8050: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 is.** handled as
8060: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 a fatal error b
8070: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d y SQLite, vfs im
8080: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 plementations sh
8090: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a ould endeavor.**
80a0: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 to prevent this
80b0: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 by setting mxPa
80c0: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 thname to a suff
80d0: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 iciently large v
80e0: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 alue..**.** The
80f0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 xRandomness(), x
8100: 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75 Sleep(), and xCu
8110: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 rrentTime() inte
8120: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f rfaces.** are no
8130: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 t strictly a par
8140: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 t of the filesys
8150: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 tem, but they ar
8160: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e e.** included in
8170: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 the VFS structu
8180: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e re for completen
8190: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e ess..** The xRan
81a0: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 domness() functi
81b0: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 on attempts to r
81c0: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 eturn nBytes byt
81d0: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 es.** of good-qu
81e0: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 ality randomness
81f0: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 into zOut. The
8200: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 return value is
8210: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e .** the actual n
8220: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f umber of bytes o
8230: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 f randomness obt
8240: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 ained..** The xS
8250: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 leep() method ca
8260: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 uses the calling
8270: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 thread to sleep
8280: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 for at.** least
8290: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d the number of m
82a0: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 icroseconds give
82b0: 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 n. The xCurrent
82c0: 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 Time().** method
82d0: 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 returns a Julia
82e0: 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 n Day Number for
82f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 the current dat
8300: 65 20 61 6e 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a e and time..**.*
8310: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
8320: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c sqlite3_vfs sql
8330: 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 ite3_vfs;.struct
8340: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 sqlite3_vfs {.
8350: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 int iVersion;
8360: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 /* Str
8370: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e ucture version n
8380: 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 umber */. int s
8390: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 zOsFile;
83a0: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 /* Size of s
83b0: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 ubclassed sqlite
83c0: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 3_file */. int
83d0: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 mxPathname;
83e0: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
83f0: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 file pathname le
8400: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 ngth */. sqlite
8410: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 3_vfs *pNext;
8420: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 /* Next regis
8430: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 tered VFS */. c
8440: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
8450: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 ; /* Name
8460: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 of this virtual
8470: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 file system */.
8480: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b void *pAppData;
8490: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 /* Poi
84a0: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 nter to applicat
84b0: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 ion-specific dat
84c0: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 a */. int (*xOp
84d0: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a en)(sqlite3_vfs*
84e0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
84f0: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c ame, sqlite3_fil
8500: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 e*,.
8510: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e int flags, in
8520: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 t *pOutFlags);.
8530: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 int (*xDelete)(
8540: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
8550: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
8560: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 int syncDir);.
8570: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 int (*xAccess)(
8580: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
8590: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
85a0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 int flags, int
85b0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 *pResOut);. int
85c0: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 (*xFullPathname
85d0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
85e0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
85f0: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 e, int nOut, cha
8600: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 r *zOut);. void
8610: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c *(*xDlOpen)(sql
8620: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
8630: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 char *zFilename
8640: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 );. void (*xDlE
8650: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 rror)(sqlite3_vf
8660: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 s*, int nByte, c
8670: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 har *zErrMsg);.
8680: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d void (*(*xDlSym
8690: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 )(sqlite3_vfs*,v
86a0: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 oid*, const char
86b0: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 *zSymbol))(void
86c0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 );. void (*xDlC
86d0: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 lose)(sqlite3_vf
86e0: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e s*, void*);. in
86f0: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 t (*xRandomness)
8700: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
8710: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a nt nByte, char *
8720: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 zOut);. int (*x
8730: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 Sleep)(sqlite3_v
8740: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 fs*, int microse
8750: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a conds);. int (*
8760: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 xCurrentTime)(sq
8770: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 lite3_vfs*, doub
8780: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 le*);. int (*xG
8790: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c etLastError)(sql
87a0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 ite3_vfs*, int,
87b0: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 char *);. /* Ne
87c0: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 w fields may be
87d0: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 appended in figu
87e0: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 re versions. Th
87f0: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 e iVersion. **
8800: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 value will incre
8810: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 ment whenever th
8820: 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d is happens. */.}
8830: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
8840: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 F: Flags for the
8850: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 xAccess VFS met
8860: 68 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c 48 31 hod {H11190} <H1
8870: 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 1140>.**.** Thes
8880: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
8890: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 nts can be used
88a0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 as the third par
88b0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 ameter to.** the
88c0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 xAccess method
88d0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 of an [sqlite3_v
88e0: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 fs] object. {END
88f0: 7d 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e } They determin
8900: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f e.** what kind o
8910: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 f permissions th
8920: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
8930: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e is looking for.
8940: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f .** With SQLITE_
8950: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 ACCESS_EXISTS, t
8960: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
8970: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 d.** simply chec
8980: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 ks whether the f
8990: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 ile exists..** W
89a0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ith SQLITE_ACCES
89b0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 S_READWRITE, the
89c0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a xAccess method.
89d0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 ** checks whethe
89e0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f r the file is bo
89f0: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 th readable and
8a00: 77 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 69 74 writable..** Wit
8a10: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
8a20: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 READ, the xAcces
8a30: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 s method.** chec
8a40: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 ks whether the f
8a50: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e ile is readable.
8a60: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
8a70: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 TE_ACCESS_EXISTS
8a80: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
8a90: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
8aa0: 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20 WRITE 1.#define
8ab0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
8ac0: 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a AD 2../*.**
8ad0: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 CAPI3REF: Initi
8ae0: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 alize The SQLite
8af0: 20 4c 69 62 72 61 72 79 20 7b 48 31 30 31 33 30 Library {H10130
8b00: 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 31 30 } <S20000><S3010
8b10: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0>.**.** The sql
8b20: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
8b30: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 ) routine initia
8b40: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c lizes the.** SQL
8b50: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 ite library. Th
8b60: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f e sqlite3_shutdo
8b70: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 wn() routine.**
8b80: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 deallocates any
8b90: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 resources that w
8ba0: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 ere allocated by
8bb0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
8bc0: 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 ize()..**.** A c
8bd0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 all to sqlite3_i
8be0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 nitialize() is a
8bf0: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 n "effective" ca
8c00: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 ll if it is.** t
8c10: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 he first time sq
8c20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
8c30: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 () is invoked du
8c40: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d ring the lifetim
8c50: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 e of.** the proc
8c60: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 ess, or if it is
8c70: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 the first time
8c80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
8c90: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a ze() is invoked.
8ca0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 ** following a c
8cb0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
8cc0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 hutdown(). Only
8cd0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 an effective ca
8ce0: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 ll.** of sqlite3
8cf0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f _initialize() do
8d00: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a es any initializ
8d10: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 ation. All othe
8d20: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 r calls.** are h
8d30: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a armless no-ops..
8d40: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 **.** A call to
8d50: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
8d60: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 () is an "effect
8d70: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 ive" call if it
8d80: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 is the first.**
8d90: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
8da0: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 shutdown() since
8db0: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 the last sqlite
8dc0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 3_initialize().
8dd0: 20 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 Only.** an effe
8de0: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 ctive call to sq
8df0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
8e00: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 does any deinit
8e10: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 ialization..** A
8e20: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 20 74 ll other calls t
8e30: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
8e40: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 wn() are harmles
8e50: 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 s no-ops..**.**
8e60: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e Among other thin
8e70: 67 73 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 gs, sqlite3_init
8e80: 69 61 6c 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 ialize() shall i
8e90: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 nvoke.** sqlite3
8ea0: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d _os_init(). Sim
8eb0: 69 6c 61 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f ilarly, sqlite3_
8ec0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 shutdown().** sh
8ed0: 61 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 all invoke sqlit
8ee0: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a e3_os_end()..**.
8ef0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 ** The sqlite3_i
8f00: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
8f10: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ine returns [SQL
8f20: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
8f30: 73 73 2e 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f ss..** If for so
8f40: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 me reason, sqlit
8f50: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
8f60: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 is unable to ini
8f70: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c tialize.** the l
8f80: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 ibrary (perhaps
8f90: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 it is unable to
8fa0: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 allocate a neede
8fb0: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a d resource such.
8fc0: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 ** as a mutex) i
8fd0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 t returns an [er
8fe0: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 ror code] other
8ff0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d than [SQLITE_OK]
9000: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
9010: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
9020: 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c routine is call
9030: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 ed internally by
9040: 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 many other.** S
9050: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
9060: 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c so that an appl
9070: 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 ication usually
9080: 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
9090: 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 .** invoke sqlit
90a0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
90b0: 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 directly. For e
90c0: 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 xample, [sqlite3
90d0: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c _open()].** call
90e0: 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 s sqlite3_initia
90f0: 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 lize() so the SQ
9100: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c Lite library wil
9110: 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c l be automatical
9120: 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 ly.** initialize
9130: 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f d when [sqlite3_
9140: 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 open()] is calle
9150: 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 d if it has not
9160: 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a be initialized.*
9170: 2a 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77 65 * already. Howe
9180: 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 ver, if SQLite i
9190: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
91a0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 the [SQLITE_OMIT
91b0: 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f _AUTOINIT].** co
91c0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
91d0: 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f n, then the auto
91e0: 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 matic calls to s
91f0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9200: 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 e().** are omitt
9210: 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 ed and the appli
9220: 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c cation must call
9230: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
9240: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a ize() directly.*
9250: 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 * prior to using
9260: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 any other SQLit
9270: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f e interface. Fo
9280: 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 r maximum portab
9290: 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 ility,.** it is
92a0: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 recommended that
92b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c applications al
92c0: 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 ways invoke sqli
92d0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
92e0: 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 .** directly pri
92f0: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 or to using any
9300: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
9310: 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 erface. Future
9320: 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 releases.** of S
9330: 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 QLite may requir
9340: 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 e this. In othe
9350: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 r words, the beh
9360: 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a avior exhibited.
9370: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 ** when SQLite i
9380: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
9390: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 [SQLITE_OMIT_AUT
93a0: 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 OINIT] might bec
93b0: 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 ome the.** defau
93c0: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 lt behavior in s
93d0: 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 ome future relea
93e0: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a se of SQLite..**
93f0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
9400: 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e os_init() routin
9410: 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 e does operating
9420: 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 -system specific
9430: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 .** initializati
9440: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 on of the SQLite
9450: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 library. The s
9460: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a qlite3_os_end().
9470: 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 ** routine undoe
9480: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 s the effect of
9490: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
94a0: 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b ). Typical task
94b0: 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 s.** performed b
94c0: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 y these routines
94d0: 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 include allocat
94e0: 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 ion or deallocat
94f0: 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 ion.** of static
9500: 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 resources, init
9510: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c ialization of gl
9520: 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a obal variables,.
9530: 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 ** setting up a
9540: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
9550: 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 _vfs] module, or
9560: 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 setting up.** a
9570: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 default configu
9580: 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 ration using [sq
9590: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e lite3_config()].
95a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 .**.** The appli
95b0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 cation should ne
95c0: 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 ver invoke eithe
95d0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 r sqlite3_os_ini
95e0: 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 t().** or sqlite
95f0: 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 3_os_end() direc
9600: 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 tly. The applic
9610: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c ation should onl
9620: 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 y invoke.** sqli
9630: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
9640: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 and sqlite3_shu
9650: 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 tdown(). The sq
9660: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a lite3_os_init().
9670: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
9680: 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 called automatic
9690: 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f ally by sqlite3_
96a0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 initialize() and
96b0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 .** sqlite3_os_e
96c0: 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 nd() is called b
96d0: 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f y sqlite3_shutdo
96e0: 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 wn(). Appropria
96f0: 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 te.** implementa
9700: 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 tions for sqlite
9710: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 3_os_init() and
9720: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
9730: 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e .** are built in
9740: 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 to SQLite when i
9750: 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f t is compiled fo
9760: 72 20 75 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c r unix, windows,
9770: 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 or os/2..** Whe
9780: 6e 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 n built for othe
9790: 72 20 70 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 r platforms (usi
97a0: 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f ng the [SQLITE_O
97b0: 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 S_OTHER=1] compi
97c0: 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f le-time.** optio
97d0: 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 n) the applicati
97e0: 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 on must supply a
97f0: 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d suitable implem
9800: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 entation for.**
9810: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
9820: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 ) and sqlite3_os
9830: 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c _end(). An appl
9840: 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 ication-supplied
9850: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
9860: 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 on of sqlite3_os
9870: 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 _init() or sqlit
9880: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d e3_os_end().** m
9890: 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ust return [SQLI
98a0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
98b0: 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 s and some other
98c0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 [error code] up
98d0: 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a on.** failure..*
98e0: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c /.SQLITE_API SQL
98f0: 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
9900: 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e PI SQLITE_API in
9910: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 t sqlite3_initia
9920: 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 lize(void);.SQLI
9930: 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
9940: 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
9950: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
9960: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 te3_shutdown(voi
9970: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 d);.SQLITE_API S
9980: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
9990: 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
99a0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 int sqlite3_os_i
99b0: 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 nit(void);.SQLIT
99c0: 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
99d0: 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
99e0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
99f0: 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b e3_os_end(void);
9a00: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
9a10: 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 : Configuring Th
9a20: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 e SQLite Library
9a30: 20 7b 48 31 34 31 30 30 7d 20 3c 53 32 30 30 30 {H14100} <S2000
9a40: 30 3e 3c 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 0><S30200>.** EX
9a50: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
9a60: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e The sqlite3_con
9a70: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
9a80: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 is used to make
9a90: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 global configura
9aa0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 tion.** changes
9ab0: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 to SQLite in ord
9ac0: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 er to tune SQLit
9ad0: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 e to the specifi
9ae0: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 c needs of.** th
9af0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 e application.
9b00: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 The default conf
9b10: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 iguration is rec
9b20: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 ommended for mos
9b30: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e t.** application
9b40: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f s and so this ro
9b50: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 utine is usually
9b60: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 not necessary.
9b70: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 It is.** provid
9b80: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 ed to support ra
9b90: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 re applications
9ba0: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 with unusual nee
9bb0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ds..**.** The sq
9bc0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
9bd0: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 nterface is not
9be0: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 threadsafe. The
9bf0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 application.**
9c00: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 must insure that
9c10: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 no other SQLite
9c20: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
9c30: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 invoked by other
9c40: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c .** threads whil
9c50: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
9c60: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 () is running.
9c70: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c Furthermore, sql
9c80: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a ite3_config().**
9c90: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 may only be inv
9ca0: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 oked prior to li
9cb0: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 brary initializa
9cc0: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 tion using.** [s
9cd0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9ce0: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 e()] or after sh
9cf0: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 utdown by [sqlit
9d00: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a e3_shutdown()]..
9d10: 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 ** Note, however
9d20: 2c 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63 , that sqlite3_c
9d30: 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 onfig() can be c
9d40: 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 alled as part of
9d50: 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e the.** implemen
9d60: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 tation of an app
9d70: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
9d80: 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 [sqlite3_os_ini
9d90: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 t()]..**.** The
9da0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
9db0: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 o sqlite3_config
9dc0: 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 () is an integer
9dd0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
9de0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 IG_SINGLETHREAD
9df0: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 | configuration
9e00: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 option] that det
9e10: 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 ermines.** what
9e20: 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 property of SQLi
9e30: 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 te is to be conf
9e40: 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 igured. Subsequ
9e50: 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a ent arguments.**
9e60: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 vary depending
9e70: 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 on the [SQLITE_C
9e80: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
9e90: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 AD | configurati
9ea0: 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e on option].** in
9eb0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
9ec0: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 ent..**.** When
9ed0: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 a configuration
9ee0: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 option is set, s
9ef0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
9f00: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
9f10: 4f 4b 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f OK]..** If the o
9f20: 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e ption is unknown
9f30: 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e or SQLite is un
9f40: 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 able to set the
9f50: 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 option.** then t
9f60: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
9f70: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b rns a non-zero [
9f80: 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a error code]..**.
9f90: 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
9fa0: 0a 2a 2a 20 5b 48 31 34 31 30 33 5d 20 5b 48 31 .** [H14103] [H1
9fb0: 34 31 30 36 5d 20 5b 48 31 34 31 32 30 5d 20 5b 4106] [H14120] [
9fc0: 48 31 34 31 32 33 5d 20 5b 48 31 34 31 32 36 5d H14123] [H14126]
9fd0: 20 5b 48 31 34 31 32 39 5d 20 5b 48 31 34 31 33 [H14129] [H1413
9fe0: 32 5d 20 5b 48 31 34 31 33 35 5d 0a 2a 2a 20 5b 2] [H14135].** [
9ff0: 48 31 34 31 33 38 5d 20 5b 48 31 34 31 34 31 5d H14138] [H14141]
a000: 20 5b 48 31 34 31 34 34 5d 20 5b 48 31 34 31 34 [H14144] [H1414
a010: 37 5d 20 5b 48 31 34 31 35 30 5d 20 5b 48 31 34 7] [H14150] [H14
a020: 31 35 33 5d 20 5b 48 31 34 31 35 36 5d 20 5b 48 153] [H14156] [H
a030: 31 34 31 35 39 5d 0a 2a 2a 20 5b 48 31 34 31 36 14159].** [H1416
a040: 32 5d 20 5b 48 31 34 31 36 35 5d 20 5b 48 31 34 2] [H14165] [H14
a050: 31 36 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 168].*/.SQLITE_A
a060: 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
a070: 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
a080: 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 API SQLITE_EXPER
a090: 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 IMENTAL int sqli
a0a0: 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 te3_config(int,
a0b0: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ...);../*.** CAP
a0c0: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 I3REF: Configure
a0d0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
a0e0: 74 69 6f 6e 73 20 20 7b 48 31 34 32 30 30 7d 20 tions {H14200}
a0f0: 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 <S20000>.** EXPE
a100: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
a110: 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f he sqlite3_db_co
a120: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 nfig() interface
a130: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 is used to make
a140: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a configuration.*
a150: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b * changes to a [
a160: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
a170: 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 ion]. The inter
a180: 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 face is similar
a190: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
a1a0: 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 onfig()] except
a1b0: 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 that the changes
a1c0: 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 apply to a sing
a1d0: 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 le.** [database
a1e0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 connection] (spe
a1f0: 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 cified in the fi
a200: 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20 rst argument).
a210: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 The.** sqlite3_d
a220: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 b_config() inter
a230: 66 61 63 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 face can only be
a240: 20 75 73 65 64 20 69 6d 6d 65 64 69 61 74 65 6c used immediatel
a250: 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 y after.** the d
a260: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
a270: 6f 6e 20 69 73 20 63 72 65 61 74 65 64 20 75 73 on is created us
a280: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 ing [sqlite3_ope
a290: 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 n()],.** [sqlite
a2a0: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 3_open16()], or
a2b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
a2c0: 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 ()]. .**.** The
a2d0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
a2e0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 to sqlite3_db_c
a2f0: 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 onfig(D,V,...)
a300: 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 is the.** config
a310: 75 72 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 uration verb - a
a320: 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 n integer code t
a330: 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 hat indicates wh
a340: 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 at.** aspect of
a350: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
a360: 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 nnection] is bei
a370: 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a ng configured..*
a380: 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 * The only choic
a390: 65 20 66 6f 72 20 74 68 69 73 20 76 61 6c 75 65 e for this value
a3a0: 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f is [SQLITE_DBCO
a3b0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e NFIG_LOOKASIDE].
a3c0: 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 61 72 .** New verbs ar
a3d0: 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 e likely to be a
a3e0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
a3f0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
a400: 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c e..** Additional
a410: 20 61 72 67 75 6d 65 6e 74 73 20 64 65 70 65 6e arguments depen
a420: 64 20 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a d on the verb..*
a430: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
a440: 73 3a 0a 2a 2a 20 5b 48 31 34 32 30 33 5d 20 5b s:.** [H14203] [
a450: 48 31 34 32 30 36 5d 20 5b 48 31 34 32 30 39 5d H14206] [H14209]
a460: 20 5b 48 31 34 32 31 32 5d 20 5b 48 31 34 32 31 [H14212] [H1421
a470: 35 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 5].*/.SQLITE_API
a480: 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
a490: 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
a4a0: 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d I SQLITE_EXPERIM
a4b0: 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 ENTAL int sqlite
a4c0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 3_db_config(sqli
a4d0: 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e te3*, int op, ..
a4e0: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
a4f0: 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f REF: Memory Allo
a500: 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 cation Routines
a510: 7b 48 31 30 31 35 35 7d 20 3c 53 32 30 31 32 30 {H10155} <S20120
a520: 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
a530: 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 L.**.** An insta
a540: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
a550: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 ct defines the i
a560: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e nterface between
a570: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c SQLite.** and l
a580: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 ow-level memory
a590: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 allocation routi
a5a0: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 nes..**.** This
a5b0: 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 object is used i
a5c0: 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 n only one place
a5d0: 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 in the SQLite i
a5e0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 nterface..** A p
a5f0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
a600: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
a610: 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 ject is the argu
a620: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 ment to.** [sqli
a630: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 te3_config()] wh
a640: 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 en the configura
a650: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a tion option is.*
a660: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
a670: 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 _MALLOC]. By cr
a680: 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e eating an instan
a690: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
a6a0: 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 t.** and passing
a6b0: 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f it to [sqlite3_
a6c0: 63 6f 6e 66 69 67 28 29 5d 20 64 75 72 69 6e 67 config()] during
a6d0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 configuration,
a6e0: 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f an.** applicatio
a6f0: 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e n can specify an
a700: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d alternative mem
a710: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 ory allocation s
a720: 75 62 73 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 ubsystem.** for
a730: 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f SQLite to use fo
a740: 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e r all of its dyn
a750: 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 amic memory need
a760: 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 s..**.** Note th
a770: 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 at SQLite comes
a780: 77 69 74 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 with a built-in
a790: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
a7a0: 20 74 68 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 that is.** perf
a7b0: 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 ectly adequate f
a7c0: 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d or the overwhelm
a7d0: 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 ing majority of
a7e0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 applications.**
a7f0: 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 and that this ob
a800: 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 ject is only use
a810: 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 ful to a tiny mi
a820: 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 nority of applic
a830: 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 ations.** with s
a840: 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 pecialized memor
a850: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 y allocation req
a860: 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 uirements. This
a870: 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c object is.** al
a880: 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 so used during t
a890: 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 esting of SQLite
a8a0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 in order to spe
a8b0: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 cify an alternat
a8c0: 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c ive.** memory al
a8d0: 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d locator that sim
a8e0: 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 ulates memory ou
a8f0: 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 t-of-memory cond
a900: 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 itions in.** ord
a910: 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 er to verify tha
a920: 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 t SQLite recover
a930: 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f s gracefully fro
a940: 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 m such.** condit
a950: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ions..**.** The
a960: 78 4d 61 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 xMalloc, xFree,
a970: 61 6e 64 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 and xRealloc met
a980: 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c hods must work l
a990: 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f ike the.** mallo
a9a0: 63 28 29 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 c(), free(), and
a9b0: 20 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 realloc() funct
a9c0: 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 ions from the st
a9d0: 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 2e 0a andard library..
a9e0: 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 **.** xSize shou
a9f0: 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c ld return the al
aa00: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 located size of
aa10: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
aa20: 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c ion.** previousl
aa30: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
aa40: 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c xMalloc or xReal
aa50: 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 loc. The alloca
aa60: 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 ted size.** is a
aa70: 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 lways at least a
aa80: 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 s big as the req
aa90: 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 uested size but
aaa0: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a may be larger..*
aab0: 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 *.** The xRoundu
aac0: 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 p method returns
aad0: 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 what would be t
aae0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a he allocated siz
aaf0: 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 e of.** a memory
ab00: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 allocation give
ab10: 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 n a particular r
ab20: 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 equested size.
ab30: 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 Most memory.** a
ab40: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 llocators round
ab50: 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 up memory alloca
ab60: 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 tions at least t
ab70: 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 o the next multi
ab80: 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f ple.** of 8. So
ab90: 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f me allocators ro
aba0: 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 und up to a larg
abb0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 er multiple or t
abc0: 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a o a power of 2..
abd0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 **.** The xInit
abe0: 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a method initializ
abf0: 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c es the memory al
ac00: 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 locator. (For e
ac10: 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 xample,.** it mi
ac20: 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 ght allocate any
ac30: 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 require mutexes
ac40: 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 or initialize i
ac50: 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 nternal data.**
ac60: 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 structures. The
ac70: 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f xShutdown metho
ac80: 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e d is invoked (in
ac90: 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 directly) by.**
aca0: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
acb0: 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 n()] and should
acc0: 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 deallocate any r
acd0: 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 esources acquire
ace0: 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 d.** by xInit.
acf0: 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 The pAppData poi
ad00: 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 nter is used as
ad10: 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 the only paramet
ad20: 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 er to.** xInit a
ad30: 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f nd xShutdown..*/
ad40: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
ad50: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
ad60: 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f ods sqlite3_mem_
ad70: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 methods;.struct
ad80: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
ad90: 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a ods {. void *(*
ada0: 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 xMalloc)(int);
adb0: 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 /* Memory
adc0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 allocation func
add0: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 tion */. void (
ade0: 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 *xFree)(void*);
adf0: 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 /* Free
ae00: 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 a prior allocat
ae10: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 ion */. void *(
ae20: 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a *xRealloc)(void*
ae30: 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a ,int); /* Resiz
ae40: 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 e an allocation
ae50: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 */. int (*xSize
ae60: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 )(void*);
ae70: 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 /* Return th
ae80: 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c e size of an all
ae90: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 ocation */. int
aea0: 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 (*xRoundup)(int
aeb0: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 ); /* R
aec0: 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 ound up request
aed0: 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 size to allocati
aee0: 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 on size */. int
aef0: 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 (*xInit)(void*)
af00: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 ; /* I
af10: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 nitialize the me
af20: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a mory allocator *
af30: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 /. void (*xShut
af40: 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 down)(void*);
af50: 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 /* Deinitiali
af60: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c ze the memory al
af70: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 locator */. voi
af80: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 d *pAppData;
af90: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 /* A
afa0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 rgument to xInit
afb0: 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e () and xShutdown
afc0: 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 () */.};../*.**
afd0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
afe0: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 uration Options
aff0: 7b 48 31 30 31 36 30 7d 20 3c 53 32 30 30 30 30 {H10160} <S20000
b000: 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
b010: 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f L.**.** These co
b020: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 nstants are the
b030: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 available intege
b040: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 r configuration
b050: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 options that.**
b060: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 can be passed as
b070: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
b080: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ent to the [sqli
b090: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e te3_config()] in
b0a0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e terface..**.** N
b0b0: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ew configuration
b0c0: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 options may be
b0d0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
b0e0: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
b0f0: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 te..** Existing
b100: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
b110: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 tions might be d
b120: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 iscontinued. Ap
b130: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 plications.** sh
b140: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 ould check the r
b150: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 eturn code from
b160: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
b170: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 )] to make sure
b180: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c that.** the call
b190: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 worked. The [s
b1a0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
b1b0: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 interface will
b1c0: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d return a.** non-
b1d0: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
b1e0: 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e ] if a discontin
b1f0: 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 ued or unsupport
b200: 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ed configuration
b210: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e option.** is in
b220: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c voked..**.** <dl
b230: 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f >.** <dt>SQLITE_
b240: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
b250: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e EAD</dt>.** <dd>
b260: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 There are no arg
b270: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
b280: 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 ption. This opt
b290: 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 ion disables.**
b2a0: 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 all mutexing and
b2b0: 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 puts SQLite int
b2c0: 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 o a mode where i
b2d0: 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 t can only be us
b2e0: 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c ed.** by a singl
b2f0: 65 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a e thread.</dd>.*
b300: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
b310: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
b320: 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 AD</dt>.** <dd>T
b330: 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 here are no argu
b340: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 ments to this op
b350: 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 tion. This opti
b360: 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d on disables.** m
b370: 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 utexing on [data
b380: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
b390: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
b3a0: 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 tatement] object
b3b0: 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 s..** The applic
b3c0: 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 ation is respons
b3d0: 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 ible for seriali
b3e0: 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a zing access to.*
b3f0: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
b400: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 ections] and [pr
b410: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
b420: 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d s]. But other m
b430: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e utexes.** are en
b440: 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 abled so that SQ
b450: 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 Lite will be saf
b460: 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 e to use in a mu
b470: 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 lti-threaded.**
b480: 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c environment as l
b490: 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 ong as no two th
b4a0: 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f reads attempt to
b4b0: 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a use the same.**
b4c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
b4d0: 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 ction] at the sa
b4e0: 6d 65 20 74 69 6d 65 2e 20 20 53 65 65 20 74 68 me time. See th
b4f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 e [threading mod
b500: 65 5d 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74 61 74 e].** documentat
b510: 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ion for addition
b520: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c al information.<
b530: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
b540: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 QLITE_CONFIG_SER
b550: 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 IALIZED</dt>.**
b560: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f <dd>There are no
b570: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
b580: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 is option. This
b590: 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a option enables.
b5a0: 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 ** all mutexes i
b5b0: 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 ncluding the rec
b5c0: 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 ursive.** mutexe
b5d0: 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 s on [database c
b5e0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b onnection] and [
b5f0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
b600: 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 nt] objects..**
b610: 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 In this mode (wh
b620: 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 ich is the defau
b630: 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 lt when SQLite i
b640: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
b650: 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 ** [SQLITE_THREA
b660: 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 DSAFE=1]) the SQ
b670: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c Lite library wil
b680: 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 l itself seriali
b690: 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 ze access.** to
b6a0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
b6b0: 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 tions] and [prep
b6c0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
b6d0: 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 so that the.**
b6e0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 application is f
b6f0: 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 ree to use the s
b700: 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f ame [database co
b710: 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 nnection] or the
b720: 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 .** same [prepar
b730: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e ed statement] in
b740: 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
b750: 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 ds at the same t
b760: 69 6d 65 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 ime..** See the
b770: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
b780: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 documentation f
b790: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e or additional in
b7a0: 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a formation.</dd>.
b7b0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
b7c0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f _CONFIG_MALLOC</
b7d0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
b7e0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
b7f0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
b800: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 hich is a pointe
b810: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 r to an.** insta
b820: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
b830: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
b840: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 structure. The
b850: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 argument specif
b860: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 ies.** alternati
b870: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d ve low-level mem
b880: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
b890: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 outines to be us
b8a0: 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a ed in place of.*
b8b0: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c * the memory all
b8c0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
b8d0: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 built into SQLi
b8e0: 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c te.</dd>.**.** <
b8f0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
b900: 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a _GETMALLOC</dt>.
b910: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 ** <dd>This opti
b920: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
b930: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
b940: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
b950: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
b960: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
b970: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 mem_methods] str
b980: 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 ucture. The [sq
b990: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
b9a0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 s].** structure
b9b0: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 is filled with t
b9c0: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 he currently def
b9d0: 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ined memory allo
b9e0: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e cation routines.
b9f0: 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 .** This option
ba00: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
ba10: 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 verload the defa
ba20: 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ult memory alloc
ba30: 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 ation.** routine
ba40: 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 s with a wrapper
ba50: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e that simulation
ba60: 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 s memory allocat
ba70: 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a ion failure or.*
ba80: 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 * tracks memory
ba90: 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 usage, for examp
baa0: 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c le.</dd>.**.** <
bab0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
bac0: 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a _MEMSTATUS</dt>.
bad0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 ** <dd>This opti
bae0: 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 on takes single
baf0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 argument of type
bb00: 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 int, interprete
bb10: 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 d as a .** boole
bb20: 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 an, which enable
bb30: 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 s or disables th
bb40: 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 e collection of
bb50: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
bb60: 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 n .** statistics
bb70: 2e 20 57 68 65 6e 20 64 69 73 61 62 6c 65 64 2c . When disabled,
bb80: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 the following S
bb90: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
bba0: 20 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d become .** non-
bbb0: 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 operational:.**
bbc0: 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e <ul>.** <li>
bbd0: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
bbe0: 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c _used()].** <l
bbf0: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f i> [sqlite3_memo
bc00: 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a ry_highwater()].
bc10: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
bc20: 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d e3_soft_heap_lim
bc30: 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 it()].** <li>
bc40: 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 [sqlite3_status(
bc50: 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a )].** </ul>.**
bc60: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 </dd>.**.** <dt
bc70: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
bc80: 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c CRATCH</dt>.** <
bc90: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 dd>This option s
bca0: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 pecifies a stati
bcb0: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 c memory buffer
bcc0: 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 that SQLite can
bcd0: 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 use for.** scrat
bce0: 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 ch memory. Ther
bcf0: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 e are three argu
bd00: 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 ments: A pointe
bd10: 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 r an 8-byte.** a
bd20: 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 ligned memory bu
bd30: 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 ffer from which
bd40: 74 68 65 20 73 63 72 61 63 68 20 61 6c 6c 6f 63 the scrach alloc
bd50: 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a ations will be.*
bd60: 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a * drawn, the siz
bd70: 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 e of each scratc
bd80: 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a h allocation (sz
bd90: 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 ),.** and the ma
bda0: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
bdb0: 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 scratch allocati
bdc0: 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a ons (N). The sz
bdd0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 .** argument mus
bde0: 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 t be a multiple
bdf0: 6f 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70 61 of 16. The sz pa
be00: 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 rameter should b
be10: 65 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a 2a e a few bytes.**
be20: 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 larger than the
be30: 20 61 63 74 75 61 6c 20 73 63 72 61 74 63 68 20 actual scratch
be40: 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20 64 space required d
be50: 75 65 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20 6f ue to internal o
be60: 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65 20 verhead..** The
be70: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 first argument s
be80: 68 6f 75 6c 64 20 70 6f 69 6e 74 65 72 20 74 6f hould pointer to
be90: 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e an 8-byte align
bea0: 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 ed buffer.** of
beb0: 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 at least sz*N by
bec0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a tes of memory..*
bed0: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 * SQLite will us
bee0: 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f e no more than o
bef0: 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65 ne scratch buffe
bf00: 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68 r at once per th
bf10: 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 read, so.** N sh
bf20: 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 ould be set to t
bf30: 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 he expected maxi
bf40: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 mum number of th
bf50: 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a reads. The sz.*
bf60: 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 * parameter shou
bf70: 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20 74 68 ld be 6 times th
bf80: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 e size of the la
bf90: 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 rgest database p
bfa0: 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 age size..** Scr
bfb0: 61 74 63 68 20 62 75 66 66 65 72 73 20 61 72 65 atch buffers are
bfc0: 20 75 73 65 64 20 61 73 20 70 61 72 74 20 6f 66 used as part of
bfd0: 20 74 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e the btree balan
bfe0: 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 ce operation. I
bff0: 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62 f.** The btree b
c000: 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64 alancer needs ad
c010: 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 ditional memory
c020: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 beyond what is p
c030: 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 rovided by.** sc
c040: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 6f 72 ratch buffers or
c050: 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62 if no scratch b
c060: 75 66 66 65 72 20 73 70 61 63 65 20 69 73 20 73 uffer space is s
c070: 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53 pecified, then S
c080: 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f QLite.** goes to
c090: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
c0a0: 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 ()] to obtain th
c0b0: 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 e memory it need
c0c0: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 s.</dd>.**.** <d
c0d0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
c0e0: 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a PAGECACHE</dt>.*
c0f0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f * <dd>This optio
c100: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 n specifies a st
c110: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 atic memory buff
c120: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 er that SQLite c
c130: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 an use for.** th
c140: 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 e database page
c150: 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 cache with the d
c160: 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 efault page cach
c170: 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e e implemenation.
c180: 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 .** This confi
c190: 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 guration should
c1a0: 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 not be used if a
c1b0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
c1c0: 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 fine page.** cac
c1d0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
c1e0: 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e n is loaded usin
c1f0: 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e g the SQLITE_CON
c200: 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f FIG_PCACHE optio
c210: 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 n..** There are
c220: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 three arguments
c230: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 to this option:
c240: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 A pointer to 8-b
c250: 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d yte aligned.** m
c260: 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 emory, the size
c270: 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 of each page buf
c280: 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 fer (sz), and th
c290: 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 e number of page
c2a0: 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a s (N)..** The sz
c2b0: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 argument should
c2c0: 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 be the size of
c2d0: 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 the largest data
c2e0: 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 base page.** (a
c2f0: 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 power of two bet
c300: 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 ween 512 and 327
c310: 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 68) plus a littl
c320: 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 e extra for each
c330: 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e .** page header.
c340: 20 20 54 68 65 20 70 61 67 65 20 68 65 61 64 65 The page heade
c350: 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 r size is 20 to
c360: 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 40 bytes dependi
c370: 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 ng on.** the hos
c380: 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 t architecture.
c390: 20 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c It is harmless,
c3a0: 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 apart from the
c3b0: 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a wasted memory,.*
c3c0: 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c * to make sz a l
c3d0: 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e ittle too large.
c3e0: 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 The first.** a
c3f0: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 rgument should p
c400: 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 oint to an alloc
c410: 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 ation of at leas
c420: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 t sz*N bytes of
c430: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 memory..** SQLit
c440: 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d e will use the m
c450: 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 emory provided b
c460: 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 y the first argu
c470: 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 ment to satisfy
c480: 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 its.** memory ne
c490: 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 eds for the firs
c4a0: 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 t N pages that i
c4b0: 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e t adds to cache.
c4c0: 20 20 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a If additional.
c4d0: 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 ** page cache me
c4e0: 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 mory is needed b
c4f0: 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 eyond what is pr
c500: 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f ovided by this o
c510: 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 ption, then.** S
c520: 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 QLite goes to [s
c530: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
c540: 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f for the additio
c550: 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 nal storage spac
c560: 65 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d e..** The implem
c570: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 entation might u
c580: 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f se one or more o
c590: 66 20 74 68 65 20 4e 20 62 75 66 66 65 72 73 20 f the N buffers
c5a0: 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f to hold .** memo
c5b0: 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e ry accounting in
c5c0: 66 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 65 20 70 formation. The p
c5d0: 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 ointer in the fi
c5e0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 rst argument mus
c5f0: 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 t.** be aligned
c600: 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 to an 8-byte bou
c610: 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 ndary or subsequ
c620: 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 ent behavior of
c630: 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 SQLite.** will b
c640: 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 e undefined.</dd
c650: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
c660: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f TE_CONFIG_HEAP</
c670: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
c680: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 option specifies
c690: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 a static memory
c6a0: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c buffer that SQL
c6b0: 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 ite will use.**
c6c0: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 for all of its d
c6d0: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c ynamic memory al
c6e0: 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 location needs b
c6f0: 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 eyond those prov
c700: 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b ided.** for by [
c710: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
c720: 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 RATCH] and [SQLI
c730: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
c740: 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 CHE]..** There a
c750: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e re three argumen
c760: 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c ts: An 8-byte al
c770: 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f igned pointer to
c780: 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 the memory,.**
c790: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
c7a0: 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 tes in the memor
c7b0: 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 y buffer, and th
c7c0: 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 e minimum alloca
c7d0: 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 49 66 tion size..** If
c7e0: 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 the first point
c7f0: 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 er (the memory p
c800: 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c ointer) is NULL,
c810: 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 then SQLite rev
c820: 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 erts.** to using
c830: 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d its default mem
c840: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 ory allocator (t
c850: 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 he system malloc
c860: 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f () implementatio
c870: 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 n),.** undoing a
c880: 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 ny prior invocat
c890: 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 ion of [SQLITE_C
c8a0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 ONFIG_MALLOC].
c8b0: 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 If the.** memory
c8c0: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 pointer is not
c8d0: 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 NULL and either
c8e0: 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d [SQLITE_ENABLE_M
c8f0: 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 EMSYS3] or.** [S
c900: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d QLITE_ENABLE_MEM
c910: 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 SYS5] are define
c920: 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 d, then the alte
c930: 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a rnative memory.*
c940: 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 * allocator is e
c950: 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 ngaged to handle
c960: 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 all of SQLites
c970: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
c980: 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 n needs..** The
c990: 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 first pointer (t
c9a0: 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 he memory pointe
c9b0: 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e r) must be align
c9c0: 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a ed to an 8-byte.
c9d0: 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 ** boundary or s
c9e0: 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 ubsequent behavi
c9f0: 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c or of SQLite wil
ca00: 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c l be undefined.<
ca10: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
ca20: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
ca30: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 EX</dt>.** <dd>T
ca40: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
ca50: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
ca60: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f nt which is a po
ca70: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 inter to an.** i
ca80: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
ca90: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
caa0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
cab0: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 . The argument
cac0: 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 specifies.** alt
cad0: 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 ernative low-lev
cae0: 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 el mutex routine
caf0: 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 s to be used in
cb00: 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 place.** the mut
cb10: 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c ex routines buil
cb20: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f t into SQLite.</
cb30: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
cb40: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
cb50: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 UTEX</dt>.** <dd
cb60: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b >This option tak
cb70: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
cb80: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
cb90: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
cba0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
cbb0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
cbc0: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
cbd0: 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c re. The.** [sql
cbe0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
cbf0: 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 ds].** structure
cc00: 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 is filled with
cc10: 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 the currently de
cc20: 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 fined mutex rout
cc30: 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 ines..** This op
cc40: 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 tion can be used
cc50: 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 to overload the
cc60: 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 default mutex a
cc70: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 llocation.** rou
cc80: 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 tines with a wra
cc90: 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 pper used to tra
cca0: 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 ck mutex usage f
ccb0: 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a or performance.*
ccc0: 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 * profiling or t
ccd0: 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d esting, for exam
cce0: 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ple.</dd>.**.**
ccf0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
cd00: 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e G_LOOKASIDE</dt>
cd10: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
cd20: 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 ion takes two ar
cd30: 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 guments that det
cd40: 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 ermine the defau
cd50: 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c lt.** memory all
cd60: 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 cation lookaside
cd70: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 optimization.
cd80: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
cd90: 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a nt is the.** siz
cda0: 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 e of each lookas
cdb0: 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 ide buffer slot
cdc0: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 and the second i
cdd0: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a s the number of.
cde0: 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 ** slots allocat
cdf0: 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 ed to each datab
ce00: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c ase connection.<
ce10: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
ce20: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
ce30: 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e CHE</dt>.** <dd>
ce40: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
ce50: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
ce60: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
ce70: 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 ointer to.** an
ce80: 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
ce90: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e methods] object.
cea0: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 This object sp
ceb0: 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 ecifies the inte
cec0: 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 rface.** to a cu
ced0: 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 stom page cache
cee0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 implementation.
cef0: 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 SQLite makes a
cf00: 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f copy of the.** o
cf10: 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 bject and uses i
cf20: 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 t for page cache
cf30: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
cf40: 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ons.</dd>.**.**
cf50: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
cf60: 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74 3e G_GETPCACHE</dt>
cf70: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
cf80: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
cf90: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
cfa0: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 h is a pointer t
cfb0: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 o an.** [sqlite3
cfc0: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d _pcache_methods]
cfd0: 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 object. SQLite
cfe0: 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 copies of the c
cff0: 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 urrent.** page c
d000: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
d010: 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 ion into that ob
d020: 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ject.</dd>.**.**
d030: 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </dl>.*/.#defin
d040: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
d050: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 SINGLETHREAD 1
d060: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
d070: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
d080: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 _MULTITHREAD 2
d090: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
d0a0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
d0b0: 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 G_SERIALIZED
d0c0: 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 3 /* nil */.#de
d0d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
d0e0: 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 IG_MALLOC
d0f0: 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 4 /* sqlite3_m
d100: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 em_methods* */.#
d110: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
d120: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 NFIG_GETMALLOC
d130: 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5 /* sqlite3
d140: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f _mem_methods* */
d150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d160: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 CONFIG_SCRATCH
d170: 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 6 /* void*
d180: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 , int sz, int N
d190: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
d1a0: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
d1b0: 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 HE 7 /* voi
d1c0: 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 d*, int sz, int
d1d0: 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c N */.#define SQL
d1e0: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 ITE_CONFIG_HEAP
d1f0: 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 8 /* v
d200: 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c oid*, int nByte,
d210: 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 int min */.#def
d220: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
d230: 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 G_MEMSTATUS
d240: 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 9 /* boolean */
d250: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d260: 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 CONFIG_MUTEX
d270: 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 10 /* sqlit
d280: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
d290: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
d2a0: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
d2b0: 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 TEX 11 /* s
d2c0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
d2d0: 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 hods* */./* prev
d2e0: 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f iously SQLITE_CO
d2f0: 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 NFIG_CHUNKALLOC
d300: 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 12 which is now
d310: 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 unused. */ .#def
d320: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
d330: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 G_LOOKASIDE 1
d340: 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 3 /* int int */
d350: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d360: 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 CONFIG_PCACHE
d370: 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 14 /* sqlit
d380: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
d390: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
d3a0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
d3b0: 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 CACHE 15 /*
d3c0: 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d sqlite3_pcache_m
d3d0: 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a ethods* */../*.*
d3e0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
d3f0: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e iguration Option
d400: 73 20 7b 48 31 30 31 37 30 7d 20 3c 53 32 30 30 s {H10170} <S200
d410: 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 00>.** EXPERIMEN
d420: 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TAL.**.** These
d430: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 constants are th
d440: 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 e available inte
d450: 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ger configuratio
d460: 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a n options that.*
d470: 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 * can be passed
d480: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 as the second ar
d490: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 gument to the [s
d4a0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
d4b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
d4c0: 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 *.** New configu
d4d0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
d4e0: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
d4f0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
d500: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 f SQLite..** Exi
d510: 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 sting configurat
d520: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 ion options migh
d530: 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 t be discontinue
d540: 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 d. Applications
d550: 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b .** should check
d560: 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 the return code
d570: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 from [sqlite3_d
d580: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d b_config()] to m
d590: 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a ake sure that.**
d5a0: 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 the call worked
d5b0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
d5c0: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 db_config()] int
d5d0: 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 erface will retu
d5e0: 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f rn a.** non-zero
d5f0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
d600: 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 a discontinued
d610: 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 or unsupported c
d620: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
d630: 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 ion.** is invoke
d640: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a d..**.** <dl>.**
d650: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
d660: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f NFIG_LOOKASIDE</
d670: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
d680: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 option takes thr
d690: 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 ee additional ar
d6a0: 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 guments that det
d6b0: 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b ermine the .** [
d6c0: 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
d6d0: 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 allocator] conf
d6e0: 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 iguration for th
d6f0: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
d700: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 ection]..** The
d710: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 first argument (
d720: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
d730: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
d740: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 db_config()] is
d750: 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 a.** pointer to
d760: 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 an 8-byte aligne
d770: 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 d memory buffer
d780: 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 to use for looka
d790: 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 side memory..**
d7a0: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
d7b0: 6e 74 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 nt may be NULL i
d7c0: 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c n which case SQL
d7d0: 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 ite will allocat
d7e0: 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 e the.** lookasi
d7f0: 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 de buffer itself
d800: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
d810: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 malloc()]. The
d820: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
d830: 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f is the.** size o
d840: 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 f each lookaside
d850: 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 buffer slot and
d860: 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d the third argum
d870: 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ent is the numbe
d880: 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 r of.** slots.
d890: 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 The size of the
d8a0: 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 buffer in the fi
d8b0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 rst argument mus
d8c0: 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 t be greater tha
d8d0: 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f n.** or equal to
d8e0: 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 the product of
d8f0: 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 the second and t
d900: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 3c hird arguments.<
d910: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e /dd>.**.** </dl>
d920: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
d930: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
d940: 41 53 49 44 45 20 20 20 20 31 30 30 31 20 20 2f ASIDE 1001 /
d950: 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 * void* int int
d960: 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */.../*.** CAPI3
d970: 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 REF: Enable Or D
d980: 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 isable Extended
d990: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 Result Codes {H1
d9a0: 32 32 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2200} <S10700>.*
d9b0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
d9c0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
d9d0: 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 _codes() routine
d9e0: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 enables or disa
d9f0: 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 bles the.** [ext
da00: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
da10: 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 es] feature of S
da20: 51 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e QLite. The exten
da30: 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f ded result.** co
da40: 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 des are disabled
da50: 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 by default for
da60: 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 historical compa
da70: 74 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 tibility conside
da80: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 rations..**.** R
da90: 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
daa0: 5b 48 31 32 32 30 31 5d 20 5b 48 31 32 32 30 32 [H12201] [H12202
dab0: 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
dac0: 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
dad0: 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
dae0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 int sqlite3_ext
daf0: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
db00: 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 es(sqlite3*, int
db10: 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 onoff);../*.**
db20: 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 CAPI3REF: Last I
db30: 6e 73 65 72 74 20 52 6f 77 69 64 20 7b 48 31 32 nsert Rowid {H12
db40: 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 220} <S10700>.**
db50: 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 .** Each entry i
db60: 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c n an SQLite tabl
db70: 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 e has a unique 6
db80: 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 4-bit signed.**
db90: 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c integer key call
dba0: 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 ed the [ROWID |
dbb0: 22 72 6f 77 69 64 22 5d 2e 20 54 68 65 20 72 6f "rowid"]. The ro
dbc0: 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 wid is always av
dbd0: 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e ailable.** as an
dbe0: 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 undeclared colu
dbf0: 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 mn named ROWID,
dc00: 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 OID, or _ROWID_
dc10: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 as long as those
dc20: 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f .** names are no
dc30: 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 t also used by e
dc40: 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 xplicitly declar
dc50: 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a ed columns. If.*
dc60: 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 * the table has
dc70: 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 a column of type
dc80: 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 [INTEGER PRIMAR
dc90: 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 Y KEY] then that
dca0: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e column.** is an
dcb0: 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 other alias for
dcc0: 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a the rowid..**.**
dcd0: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 This routine re
dce0: 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 turns the [rowid
dcf0: 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ] of the most re
dd00: 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 cent.** successf
dd10: 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f ul [INSERT] into
dd20: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 the database fr
dd30: 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 om the [database
dd40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 connection].**
dd50: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
dd60: 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75 ument. If no su
dd70: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
dd80: 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 ]s.** have ever
dd90: 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 occurred on that
dda0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
ddb0: 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 tion, zero is re
ddc0: 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 turned..**.** If
ddd0: 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 an [INSERT] occ
dde0: 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 urs within a tri
ddf0: 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 5b gger, then the [
de00: 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e rowid] of the in
de10: 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 serted.** row is
de20: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
de30: 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e s routine as lon
de40: 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 g as the trigger
de50: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 is running..**
de60: 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 But once the tri
de70: 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c gger terminates,
de80: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
de90: 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 ned by this rout
dea0: 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 ine.** reverts t
deb0: 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 o the last value
dec0: 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 inserted before
ded0: 20 74 68 65 20 74 72 69 67 67 65 72 20 66 69 72 the trigger fir
dee0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 49 4e ed..**.** An [IN
def0: 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 SERT] that fails
df00: 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 due to a constr
df10: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 aint violation i
df20: 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 s not a.** succe
df30: 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 ssful [INSERT] a
df40: 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e nd does not chan
df50: 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ge the value ret
df60: 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a urned by this.**
df70: 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20 routine. Thus
df80: 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 INSERT OR FAIL,
df90: 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 INSERT OR IGNORE
dfa0: 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c , INSERT OR ROLL
dfb0: 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 BACK,.** and INS
dfc0: 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b ERT OR ABORT mak
dfd0: 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 e no changes to
dfe0: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
dff0: 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 of this.** rout
e000: 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 ine when their i
e010: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 nsertion fails.
e020: 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 When INSERT OR
e030: 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 REPLACE.** encou
e040: 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 nters a constrai
e050: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 nt violation, it
e060: 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 does not fail.
e070: 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 The.** INSERT c
e080: 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 ontinues to comp
e090: 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c letion after del
e0a0: 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 eting rows that
e0b0: 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f caused.** the co
e0c0: 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d nstraint problem
e0d0: 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 so INSERT OR RE
e0e0: 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 PLACE will alway
e0f0: 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 s change.** the
e100: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
e110: 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a this interface..
e120: 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 **.** For the pu
e130: 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 rposes of this r
e140: 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 outine, an [INSE
e150: 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 RT] is considere
e160: 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 d to.** be succe
e170: 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 ssful even if it
e180: 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 is subsequently
e190: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a rolled back..**
e1a0: 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
e1b0: 3a 0a 2a 2a 20 5b 48 31 32 32 32 31 5d 20 5b 48 :.** [H12221] [H
e1c0: 31 32 32 32 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 12223].**.** If
e1d0: 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
e1e0: 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 d performs a new
e1f0: 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 [INSERT] on the
e200: 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 same.** databas
e210: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 e connection whi
e220: 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f le the [sqlite3_
e230: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
e240: 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e d()].** function
e250: 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 is running and
e260: 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 thus changes the
e270: 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f last insert [ro
e280: 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 wid],.** then th
e290: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
e2a0: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 by [sqlite3_las
e2b0: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 t_insert_rowid()
e2c0: 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 ] is.** unpredic
e2d0: 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 table and might
e2e0: 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 not equal either
e2f0: 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 the old or the
e300: 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 new.** last inse
e310: 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 rt [rowid]..*/.S
e320: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
e330: 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
e340: 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
e350: 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e3_int64 sqlite3
e360: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
e370: 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f id(sqlite3*);../
e380: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
e390: 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 ount The Number
e3a0: 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 Of Rows Modified
e3b0: 20 7b 48 31 32 32 34 30 7d 20 3c 53 31 30 36 30 {H12240} <S1060
e3c0: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 0>.**.** This fu
e3d0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 nction returns t
e3e0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 he number of dat
e3f0: 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 abase rows that
e400: 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 were changed.**
e410: 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 or inserted or d
e420: 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f eleted by the mo
e430: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 st recently comp
e440: 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d leted SQL statem
e450: 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 ent.** on the [d
e460: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
e470: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 on] specified by
e480: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
e490: 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68 eter..** Only ch
e4a0: 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 anges that are d
e4b0: 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 irectly specifie
e4c0: 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 d by the [INSERT
e4d0: 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 ], [UPDATE],.**
e4e0: 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 or [DELETE] stat
e4f0: 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 ement are counte
e500: 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 d. Auxiliary ch
e510: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a anges caused by.
e520: 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20 ** triggers are
e530: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65 not counted. Use
e540: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f the [sqlite3_to
e550: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 tal_changes()] f
e560: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 unction.** to fi
e570: 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d nd the total num
e580: 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 ber of changes i
e590: 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 ncluding changes
e5a0: 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 caused by trigg
e5b0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e 67 ers..**.** Chang
e5c0: 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 es to a view tha
e5d0: 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 t are simulated
e5e0: 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f by an [INSTEAD O
e5f0: 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 F trigger].** ar
e600: 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 e not counted.
e610: 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 Only real table
e620: 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e changes are coun
e630: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f ted..**.** A "ro
e640: 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 w change" is a c
e650: 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c hange to a singl
e660: 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c e row of a singl
e670: 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 e table.** cause
e680: 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 d by an INSERT,
e690: 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 DELETE, or UPDAT
e6a0: 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f E statement. Ro
e6b0: 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 ws that.** are c
e6c0: 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 hanged as side e
e6d0: 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 ffects of [REPLA
e6e0: 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 CE] constraint r
e6f0: 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f esolution,.** ro
e700: 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 llback, ABORT pr
e710: 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 ocessing, [DROP
e720: 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e TABLE], or by an
e730: 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 y other.** mecha
e740: 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 nisms do not cou
e750: 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 nt as direct row
e760: 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 changes..**.**
e770: 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 A "trigger conte
e780: 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f xt" is a scope o
e790: 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 f execution that
e7a0: 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 begins and.** e
e7b0: 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 nds with the scr
e7c0: 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 ipt of a [CREATE
e7d0: 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 TRIGGER | trigg
e7e0: 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 er]. .** Most SQ
e7f0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 L statements are
e800: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 .** evaluated ou
e810: 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 tside of any tri
e820: 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 gger. This is t
e830: 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a he "top level".*
e840: 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 * trigger contex
e850: 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 t. If a trigger
e860: 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 fires from the
e870: 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 top level, a.**
e880: 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 new trigger cont
e890: 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 ext is entered f
e8a0: 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 or the duration
e8b0: 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 of that one.** t
e8c0: 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 rigger. Subtrig
e8d0: 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 gers create subc
e8e0: 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 ontexts for thei
e8f0: 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a r duration..**.*
e900: 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 * Calling [sqlit
e910: 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 e3_exec()] or [s
e920: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 qlite3_step()] r
e930: 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a ecursively does.
e940: 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 ** not create a
e950: 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 new trigger cont
e960: 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ext..**.** This
e970: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
e980: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 the number of d
e990: 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 irect row change
e9a0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 s in the.** most
e9b0: 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 recent INSERT,
e9c0: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 UPDATE, or DELET
e9d0: 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 E statement with
e9e0: 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 in the same.** t
e9f0: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a rigger context..
ea00: 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e **.** Thus, when
ea10: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
ea20: 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 top level, this
ea30: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
ea40: 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
ea50: 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 of changes in th
ea60: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e e most recent IN
ea70: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 SERT, UPDATE, or
ea80: 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 DELETE.** that
ea90: 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 also occurred at
eaa0: 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 the top level.
eab0: 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 Within the body
eac0: 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a of a trigger,.*
ead0: 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 * the sqlite3_ch
eae0: 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 anges() interfac
eaf0: 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 e can be called
eb00: 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 to find the numb
eb10: 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 er of.** changes
eb20: 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 in the most rec
eb30: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 ently completed
eb40: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
eb50: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 or DELETE.** sta
eb60: 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 tement within th
eb70: 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 e body of the sa
eb80: 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 me trigger..** H
eb90: 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 owever, the numb
eba0: 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 er returned does
ebb0: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 not include cha
ebc0: 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 nges.** caused b
ebd0: 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 y subtriggers si
ebe0: 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 nce those have t
ebf0: 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 heir own context
ec00: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
ec10: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f the [sqlite3_to
ec20: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 tal_changes()] i
ec30: 6e 74 65 72 66 61 63 65 20 61 6e 64 20 74 68 65 nterface and the
ec40: 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 .** [count_chang
ec50: 65 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2a 0a 2a es pragma]..**.*
ec60: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
ec70: 2a 2a 20 5b 48 31 32 32 34 31 5d 20 5b 48 31 32 ** [H12241] [H12
ec80: 32 34 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 243].**.** If a
ec90: 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 separate thread
eca0: 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e makes changes on
ecb0: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
ecc0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
ecd0: 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f while [sqlite3_
ece0: 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 changes()] is ru
ecf0: 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 nning then the v
ed00: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a alue returned.**
ed10: 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c is unpredictabl
ed20: 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e e and not meanin
ed30: 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f gful..*/.SQLITE_
ed40: 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
ed50: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
ed60: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
ed70: 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 _changes(sqlite3
ed80: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
ed90: 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 REF: Total Numbe
eda0: 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 r Of Rows Modifi
edb0: 65 64 20 7b 48 31 32 32 36 30 7d 20 3c 53 31 30 ed {H12260} <S10
edc0: 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 600>.**.** This
edd0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
ede0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 the number of r
edf0: 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 ow changes cause
ee00: 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a d by [INSERT],.*
ee10: 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 * [UPDATE] or [D
ee20: 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 ELETE] statement
ee30: 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 s since the [dat
ee40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
ee50: 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a ] was opened..**
ee60: 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 The count inclu
ee70: 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 des all changes
ee80: 66 72 6f 6d 20 61 6c 6c 20 0a 2a 2a 20 5b 43 52 from all .** [CR
ee90: 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 EATE TRIGGER | t
eea0: 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 rigger] contexts
eeb0: 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 . However,.** t
eec0: 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f he count does no
eed0: 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 t include change
eee0: 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d s used to implem
eef0: 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f ent [REPLACE] co
ef00: 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f nstraints,.** do
ef10: 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 rollbacks or AB
ef20: 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 ORT processing,
ef30: 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 or [DROP TABLE]
ef40: 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 processing. The
ef50: 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e .** count does n
ef60: 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 ot include rows
ef70: 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69 of views that fi
ef80: 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f re an [INSTEAD O
ef90: 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 F trigger],.** t
efa0: 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 hough if the INS
efb0: 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 TEAD OF trigger
efc0: 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 makes changes of
efd0: 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 its own, those
efe0: 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 changes .** are
eff0: 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 54 68 65 20 counted..** The
f000: 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e changes are coun
f010: 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 ted as soon as t
f020: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 he statement tha
f030: 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 0a t makes them is.
f040: 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 ** completed (wh
f050: 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 en the statement
f060: 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73 73 65 handle is passe
f070: 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 d to [sqlite3_re
f080: 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 set()] or.** [sq
f090: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
f0a0: 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ])..**.** See al
f0b0: 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f so the [sqlite3_
f0c0: 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 changes()] inter
f0d0: 66 61 63 65 20 61 6e 64 20 74 68 65 0a 2a 2a 20 face and the.**
f0e0: 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 [count_changes p
f0f0: 72 61 67 6d 61 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 ragma]..**.** Re
f100: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
f110: 48 31 32 32 36 31 5d 20 5b 48 31 32 32 36 33 5d H12261] [H12263]
f120: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 .**.** If a sepa
f130: 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 rate thread make
f140: 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 s changes on the
f150: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
f160: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 onnection.** whi
f170: 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 le [sqlite3_tota
f180: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 l_changes()] is
f190: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 running then the
f1a0: 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e value.** return
f1b0: 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 ed is unpredicta
f1c0: 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e ble and not mean
f1d0: 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 ingful..*/.SQLIT
f1e0: 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
f1f0: 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
f200: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
f210: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
f220: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
f230: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 ** CAPI3REF: Int
f240: 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 errupt A Long-Ru
f250: 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31 32 nning Query {H12
f260: 32 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 270} <S30500>.**
f270: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f .** This functio
f280: 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e n causes any pen
f290: 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 ding database op
f2a0: 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 eration to abort
f2b0: 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 and.** return a
f2c0: 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f t its earliest o
f2d0: 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 pportunity. This
f2e0: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 routine is typi
f2f0: 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 cally.** called
f300: 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 in response to a
f310: 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 user action suc
f320: 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 h as pressing "C
f330: 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 ancel".** or Ctr
f340: 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 l-C where the us
f350: 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 er wants a long
f360: 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 query operation
f370: 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 to halt.** immed
f380: 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 iately..**.** It
f390: 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c is safe to call
f3a0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 this routine fr
f3b0: 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 om a thread diff
f3c0: 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a erent from the.*
f3d0: 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 * thread that is
f3e0: 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 currently runni
f3f0: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ng the database
f400: 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 operation. But
f410: 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 it.** is not saf
f420: 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 e to call this r
f430: 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 outine with a [d
f440: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
f450: 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 on] that.** is c
f460: 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 losed or might c
f470: 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 lose before sqli
f480: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
f490: 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 returns..**.** I
f4a0: 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 f an SQL operati
f4b0: 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c on is very nearl
f4c0: 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 y finished at th
f4d0: 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 e time when.** s
f4e0: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
f4f0: 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 () is called, th
f500: 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 en it might not
f510: 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e have an opportun
f520: 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 ity.** to be int
f530: 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 errupted and mig
f540: 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 ht continue to c
f550: 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a ompletion..**.**
f560: 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f An SQL operatio
f570: 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 n that is interr
f580: 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 upted will retur
f590: 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 n [SQLITE_INTERR
f5a0: 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 UPT]..** If the
f5b0: 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 interrupted SQL
f5c0: 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 operation is an
f5d0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
f5e0: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 or DELETE.** tha
f5f0: 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 t is inside an e
f600: 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
f610: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e ion, then the en
f620: 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e tire transaction
f630: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c .** will be roll
f640: 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 ed back automati
f650: 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 cally..**.** The
f660: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
f670: 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e pt(D) call is in
f680: 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c effect until al
f690: 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e l currently runn
f6a0: 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ing.** SQL state
f6b0: 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 ments on [databa
f6c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
f6d0: 20 63 6f 6d 70 6c 65 74 65 2e 20 20 41 6e 79 20 complete. Any
f6e0: 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e new SQL statemen
f6f0: 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 ts.** that are s
f700: 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 tarted after the
f710: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
f720: 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 pt() call and be
f730: 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e fore the .** run
f740: 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 ning statements
f750: 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 reaches zero are
f760: 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 interrupted as
f770: 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e if they had been
f780: 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f .** running prio
f790: 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
f7a0: 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c _interrupt() cal
f7b0: 6c 2e 20 20 4e 65 77 20 53 51 4c 20 73 74 61 74 l. New SQL stat
f7c0: 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 ements.** that a
f7d0: 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 re started after
f7e0: 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 the running sta
f7f0: 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 tement count rea
f800: 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a ches zero are.**
f810: 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 not effected by
f820: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 the sqlite3_int
f830: 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 41 20 63 errupt()..** A c
f840: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 all to sqlite3_i
f850: 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 nterrupt(D) that
f860: 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 occurs when the
f870: 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e re are no runnin
f880: 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 g.** SQL stateme
f890: 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 nts is a no-op a
f8a0: 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 nd has no effect
f8b0: 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e on SQL statemen
f8c0: 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 ts.** that are s
f8d0: 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 tarted after the
f8e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
f8f0: 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e pt() call return
f900: 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 s..**.** Require
f910: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 37 ments:.** [H1227
f920: 31 5d 20 5b 48 31 32 32 37 32 5d 0a 2a 2a 0a 2a 1] [H12272].**.*
f930: 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 * If the databas
f940: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f e connection clo
f950: 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 ses while [sqlit
f960: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a e3_interrupt()].
f970: 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 ** is running th
f980: 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 en bad things wi
f990: 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e ll likely happen
f9a0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
f9b0: 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
f9c0: 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
f9d0: 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e void sqlite3_in
f9e0: 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a terrupt(sqlite3*
f9f0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
fa00: 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 EF: Determine If
fa10: 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
fa20: 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b 48 t Is Complete {H
fa30: 31 30 35 31 30 7d 20 3c 53 37 30 32 30 30 3e 0a 10510} <S70200>.
fa40: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
fa50: 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 ines are useful
fa60: 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c during command-l
fa70: 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 ine input to det
fa80: 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a ermine if the.**
fa90: 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 currently enter
faa0: 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f ed text seems to
fab0: 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 form a complete
fac0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f SQL statement o
fad0: 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e r.** if addition
fae0: 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 al input is need
faf0: 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e ed before sendin
fb00: 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a g the text into.
fb10: 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 ** SQLite for pa
fb20: 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72 6f rsing. These ro
fb30: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 utines return 1
fb40: 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 if the input str
fb50: 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 ing.** appears t
fb60: 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 o be a complete
fb70: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 SQL statement.
fb80: 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a A statement is j
fb90: 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 udged to be.** c
fba0: 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e omplete if it en
fbb0: 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f ds with a semico
fbc0: 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 lon token and is
fbd0: 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 not a prefix of
fbe0: 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 a.** well-forme
fbf0: 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 d CREATE TRIGGER
fc00: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d statement. Sem
fc10: 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 icolons that are
fc20: 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e embedded within
fc30: 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 .** string liter
fc40: 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 als or quoted id
fc50: 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f entifier names o
fc60: 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e r comments are n
fc70: 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e ot.** independen
fc80: 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 t tokens (they a
fc90: 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 re part of the t
fca0: 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 oken in which th
fcb0: 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 ey are.** embedd
fcc0: 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 ed) and thus do
fcd0: 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 not count as a s
fce0: 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 tatement termina
fcf0: 74 6f 72 2e 20 20 57 68 69 74 65 73 70 61 63 65 tor. Whitespace
fd00: 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 .** and comments
fd10: 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 that follow the
fd20: 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e final semicolon
fd30: 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a are ignored..**
fd40: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
fd50: 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 es return 0 if t
fd60: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
fd70: 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 49 66 20 incomplete. If
fd80: 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f a.** memory allo
fd90: 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 cation fails, th
fda0: 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 en SQLITE_NOMEM
fdb0: 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
fdc0: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
fdd0: 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 s do not parse t
fde0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
fdf0: 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e s thus.** will n
fe00: 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 ot detect syntac
fe10: 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 tically incorrec
fe20: 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 t SQL..**.** If
fe30: 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 SQLite has not b
fe40: 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 een initialized
fe50: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 using [sqlite3_i
fe60: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 nitialize()] pri
fe70: 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 or .** to invoki
fe80: 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c ng sqlite3_compl
fe90: 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c ete16() then sql
fea0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
feb0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 ) is invoked.**
fec0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 automatically by
fed0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
fee0: 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 e16(). If that
fef0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 initialization f
ff00: 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 ails,.** then th
ff10: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
ff20: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 rom sqlite3_comp
ff30: 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 lete16() will be
ff40: 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 non-zero.** reg
ff50: 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
ff60: 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e er or not the in
ff70: 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c put SQL is compl
ff80: 65 74 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ete..**.** Requi
ff90: 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35 31 31 rements: [H10511
ffa0: 5d 20 5b 48 31 30 35 31 32 5d 0a 2a 2a 0a 2a 2a ] [H10512].**.**
ffb0: 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 The input to [s
ffc0: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 qlite3_complete(
ffd0: 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 )] must be a zer
ffe0: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
fff0: 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a UTF-8 string..**
10000 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f .** The input to
10010 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 [sqlite3_comple
10020 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 te16()] must be
10030 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
10040 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 d.** UTF-16 stri
10050 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 ng in native byt
10060 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 e order..*/.SQLI
10070 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
10080 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
10090 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
100a0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e te3_complete(con
100b0 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 st char *sql);.S
100c0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
100d0 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
100e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
100f0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
10100 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6(const void *sq
10110 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
10120 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 REF: Register A
10130 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 Callback To Hand
10140 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 le SQLITE_BUSY E
10150 72 72 6f 72 73 20 7b 48 31 32 33 31 30 7d 20 3c rrors {H12310} <
10160 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S40400>.**.** Th
10170 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 is routine sets
10180 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
10190 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 ion that might b
101a0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 e invoked whenev
101b0 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 er.** an attempt
101c0 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e is made to open
101d0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c a database tabl
101e0 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 e that another t
101f0 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 hread.** or proc
10200 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a ess has locked..
10210 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 **.** If the bus
10220 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 y callback is NU
10230 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 LL, then [SQLITE
10240 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 _BUSY] or [SQLIT
10250 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
10260 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
10270 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e immediately upon
10280 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 encountering th
10290 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20 62 e lock. If the b
102a0 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 usy callback.**
102b0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 is not NULL, the
102c0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 n the callback w
102d0 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 ill be invoked w
102e0 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 ith two argument
102f0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 s..**.** The fir
10300 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
10310 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 he handler is a
10320 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 copy of the void
10330 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a * pointer which.
10340 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 ** is the third
10350 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
10360 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
10370 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 (). The second
10380 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 argument to.** t
10390 68 65 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 he handler callb
103a0 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ack is the numbe
103b0 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 r of times that
103c0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
103d0 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 has.** been inv
103e0 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f oked for this lo
103f0 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 49 66 cking event. If
10400 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c the.** busy cal
10410 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c lback returns 0,
10420 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f then no additio
10430 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 nal attempts are
10440 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 made to.** acce
10450 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ss the database
10460 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 and [SQLITE_BUSY
10470 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 ] or [SQLITE_IOE
10480 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 RR_BLOCKED] is r
10490 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 eturned..** If t
104a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
104b0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
104c0 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d en another attem
104d0 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f pt.** is made to
104e0 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 open the databa
104f0 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 se for reading a
10500 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 nd the cycle rep
10510 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eats..**.** The
10520 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 presence of a bu
10530 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 sy handler does
10540 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 not guarantee th
10550 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e at it will be in
10560 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 voked.** when th
10570 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 ere is lock cont
10580 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74 ention. If SQLit
10590 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 e determines tha
105a0 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 t invoking the b
105b0 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 usy.** handler c
105c0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 ould result in a
105d0 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 deadlock, it wi
105e0 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 ll go ahead and
105f0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 return [SQLITE_B
10600 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 USY].** or [SQLI
10610 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
10620 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 ] instead of inv
10630 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 oking the busy h
10640 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 andler..** Consi
10650 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 der a scenario w
10660 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 here one process
10670 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 is holding a re
10680 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 ad lock that.**
10690 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 it is trying to
106a0 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 promote to a res
106b0 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a erved lock and.*
106c0 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 * a second proce
106d0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 ss is holding a
106e0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 reserved lock th
106f0 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a at it is trying.
10700 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f ** to promote to
10710 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f an exclusive lo
10720 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 ck. The first p
10730 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 rocess cannot pr
10740 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 oceed.** because
10750 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 it is blocked b
10760 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 y the second and
10770 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 the second proc
10780 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 ess cannot.** pr
10790 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 oceed because it
107a0 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 is blocked by t
107b0 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f he first. If bo
107c0 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 th processes.**
107d0 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 invoke the busy
107e0 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 handlers, neithe
107f0 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 r will make any
10800 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 progress. There
10810 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 fore,.** SQLite
10820 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
10830 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 BUSY] for the fi
10840 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 rst process, hop
10850 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a ing that this.**
10860 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 will induce the
10870 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 first process t
10880 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 o release its re
10890 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f ad lock and allo
108a0 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 w.** the second
108b0 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 process to proce
108c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 ed..**.** The de
108d0 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 fault busy callb
108e0 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a ack is NULL..**.
108f0 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 ** The [SQLITE_B
10900 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f USY] error is co
10910 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 nverted to [SQLI
10920 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
10930 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 ].** when SQLite
10940 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c is in the middl
10950 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 e of a large tra
10960 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 nsaction where a
10970 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 ll the.** change
10980 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 s will not fit i
10990 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 nto the in-memor
109a0 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 y cache. SQLite
109b0 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 will.** already
109c0 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 hold a RESERVED
109d0 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 lock on the dat
109e0 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 abase file, but
109f0 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 it needs.** to p
10a00 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b romote this lock
10a10 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f to EXCLUSIVE so
10a20 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 that it can spi
10a30 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 ll cache.** page
10a40 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 s into the datab
10a50 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 ase file without
10a60 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 harm to concurr
10a70 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 ent.** readers.
10a80 20 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 If it is unable
10a90 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 to promote the
10aa0 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 lock, then the i
10ab0 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 n-memory.** cach
10ac0 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 e will be left i
10ad0 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e n an inconsisten
10ae0 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 t state and so t
10af0 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 he error.** code
10b00 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f is promoted fro
10b10 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 m the relatively
10b20 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f benign [SQLITE_
10b30 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 BUSY] to.** the
10b40 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c more severe [SQL
10b50 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 ITE_IOERR_BLOCKE
10b60 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 D]. This error
10b70 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a code promotion.*
10b80 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f * forces an auto
10b90 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f matic rollback o
10ba0 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 f the changes.
10bb0 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 See the.** <a hr
10bc0 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b ef="/cvstrac/wik
10bd0 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f i?p=CorruptionFo
10be0 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 llowingBusyError
10bf0 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e ">.** Corruption
10c00 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 FollowingBusyErr
10c10 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 or</a> wiki page
10c20 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f for a discussio
10c30 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 n of why.** this
10c40 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a is important..*
10c50 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f *.** There can o
10c60 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 nly be a single
10c70 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 busy handler def
10c80 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a ined for each.**
10c90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
10ca0 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 ction]. Setting
10cb0 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 a new busy hand
10cc0 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a ler clears any.*
10cd0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 * previously set
10ce0 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20 handler. Note
10cf0 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 that calling [sq
10d00 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
10d10 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c ut()].** will al
10d20 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 so set or clear
10d30 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
10d40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 ..**.** The busy
10d50 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 callback should
10d60 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 not take any ac
10d70 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 tions which modi
10d80 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 fy the.** databa
10d90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
10da0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 at invoked the b
10db0 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e usy handler. An
10dc0 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a y such actions.*
10dd0 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 * result in unde
10de0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a fined behavior..
10df0 2a 2a 20 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 ** .** Requireme
10e00 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 31 31 5d nts:.** [H12311]
10e10 20 5b 48 31 32 33 31 32 5d 20 5b 48 31 32 33 31 [H12312] [H1231
10e20 34 5d 20 5b 48 31 32 33 31 36 5d 20 5b 48 31 32 4] [H12316] [H12
10e30 33 31 38 5d 0a 2a 2a 0a 2a 2a 20 41 20 62 75 73 318].**.** A bus
10e40 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e y handler must n
10e50 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 ot close the dat
10e60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
10e70 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 .** or [prepared
10e80 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
10e90 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 invoked the bus
10ea0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 y handler..*/.SQ
10eb0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
10ec0 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
10ed0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
10ee0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
10ef0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 er(sqlite3*, int
10f00 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 (*)(void*,int),
10f10 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
10f20 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 API3REF: Set A B
10f30 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 usy Timeout {H12
10f40 33 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 340} <S40410>.**
10f50 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
10f60 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 sets a [sqlite3
10f70 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 _busy_handler |
10f80 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 busy handler] th
10f90 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 at sleeps.** for
10fa0 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f a specified amo
10fb0 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e unt of time when
10fc0 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b a table is lock
10fd0 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 ed. The handler
10fe0 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d .** will sleep m
10ff0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e ultiple times un
11000 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 til at least "ms
11010 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f " milliseconds o
11020 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 f sleeping.** ha
11030 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 ve accumulated.
11040 7b 48 31 32 33 34 33 7d 20 41 66 74 65 72 20 22 {H12343} After "
11050 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 ms" milliseconds
11060 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a of sleeping,.**
11070 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 the handler ret
11080 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 urns 0 which cau
11090 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ses [sqlite3_ste
110a0 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a p()] to return.*
110b0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 * [SQLITE_BUSY]
110c0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 or [SQLITE_IOERR
110d0 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a _BLOCKED]..**.**
110e0 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f Calling this ro
110f0 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 utine with an ar
11100 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e gument less than
11110 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 or equal to zer
11120 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 o.** turns off a
11130 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 ll busy handlers
11140 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 ..**.** There ca
11150 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 n only be a sing
11160 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 le busy handler
11170 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 for a particular
11180 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
11190 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e nnection] any an
111a0 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 y given moment.
111b0 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 If another busy
111c0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 handler.** was
111d0 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 defined (using
111e0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 [sqlite3_busy_ha
111f0 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 ndler()]) prior
11200 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 to calling.** th
11210 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 is routine, that
11220 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 other busy hand
11230 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a ler is cleared..
11240 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
11250 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 34 31 5d 20 ts:.** [H12341]
11260 5b 48 31 32 33 34 33 5d 20 5b 48 31 32 33 34 34 [H12343] [H12344
11270 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
11280 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
11290 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
112a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 int sqlite3_bus
112b0 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 y_timeout(sqlite
112c0 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 3*, int ms);../*
112d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
112e0 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e nvenience Routin
112f0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 es For Running Q
11300 75 65 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20 ueries {H12370}
11310 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 <S10000>.**.** D
11320 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e efinition: A <b>
11330 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e result table</b>
11340 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 is memory data
11350 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 structure create
11360 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c d by the.** [sql
11370 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
11380 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 ] interface. A
11390 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 result table rec
113a0 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 ords the.** comp
113b0 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c lete query resul
113c0 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d ts from one or m
113d0 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a ore queries..**.
113e0 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e ** The table con
113f0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 ceptually has a
11400 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 number of rows a
11410 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 nd columns. But
11420 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 .** these number
11430 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f s are not part o
11440 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 f the result tab
11450 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 le itself. Thes
11460 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 e.** numbers are
11470 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 obtained separa
11480 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 tely. Let N be
11490 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f the number of ro
114a0 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 ws.** and M be t
114b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
114c0 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 umns..**.** A re
114d0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e sult table is an
114e0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
114f0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 rs to zero-termi
11500 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 nated UTF-8 stri
11510 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 ngs..** There ar
11520 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e e (N+1)*M elemen
11530 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e ts in the array.
11540 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f The first M po
11550 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 inters point.**
11560 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 to zero-terminat
11570 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 ed strings that
11580 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d contain the nam
11590 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e es of the column
115a0 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e s..** The remain
115b0 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 ing entries all
115c0 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 point to query r
115d0 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 esults. NULL va
115e0 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 lues result.** i
115f0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e n NULL pointers.
11600 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 All other valu
11610 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 es are in their
11620 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 UTF-8 zero-termi
11630 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 nated.** string
11640 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 representation a
11650 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 s returned by [s
11660 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
11670 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 xt()]..**.** A r
11680 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 esult table migh
11690 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 t consist of one
116a0 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 or more memory
116b0 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 allocations..**
116c0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 It is not safe t
116d0 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 o pass a result
116e0 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 table directly t
116f0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
11700 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 )]..** A result
11710 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 table should be
11720 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e deallocated usin
11730 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f g [sqlite3_free_
11740 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 table()]..**.**
11750 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 As an example of
11760 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
11770 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 e format, suppos
11780 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 e a query result
11790 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 .** is as follow
117a0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
117b0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 uote><pre>.**
117c0 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 Name
117d0 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 | Age.**
117e0 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ---------------
117f0 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 --------.**
11800 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c Alice |
11810 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 43.** Bo
11820 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a b | 28.*
11830 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 * Cindy
11840 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 | 21.** </p
11850 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
11860 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 .**.** There are
11870 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d two column (M==
11880 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 2) and three row
11890 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 s (N==3). Thus
118a0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 the.** result ta
118b0 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 ble has 8 entrie
118c0 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 s. Suppose the
118d0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 result table is
118e0 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 stored.** in an
118f0 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 array names azRe
11900 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 sult. Then azRe
11910 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 sult holds this
11920 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c content:.**.** <
11930 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
11940 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
11950 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 ult[0] = "Na
11960 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 me";.** a
11970 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d zResult[1] =
11980 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 "Age";.**
11990 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 azResult[2
119a0 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 ] = "Alice";.**
119b0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
119c0 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a #91;3] = "43";.*
119d0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
119e0 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 t[4] = "Bob"
119f0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
11a00 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 sult[5] = "2
11a10 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 8";.** az
11a20 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 Result[6] =
11a30 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 "Cindy";.**
11a40 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
11a50 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 7] = "21";.** </
11a60 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
11a70 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
11a80 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 te3_get_table()
11a90 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 function evaluat
11aa0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a es one or more.*
11ab0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 * semicolon-sepa
11ac0 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d rated SQL statem
11ad0 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f ents in the zero
11ae0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
11af0 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 8.** string of i
11b00 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 ts 2nd parameter
11b10 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20 . It returns a
11b20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 result table to
11b30 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 the.** pointer g
11b40 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 iven in its 3rd
11b50 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
11b60 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 After the calli
11b70 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 ng function has
11b80 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 finished using t
11b90 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 he result, it sh
11ba0 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 ould.** pass the
11bb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
11bc0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 result table to
11bd0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
11be0 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f le() in order to
11bf0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 .** release the
11c00 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 memory that was
11c10 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 malloced. Becau
11c20 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 se of the way th
11c30 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 e.** [sqlite3_ma
11c40 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 lloc()] happens
11c50 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 within sqlite3_g
11c60 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 et_table(), the
11c70 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 calling.** funct
11c80 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 ion must not try
11c90 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 to call [sqlite
11ca0 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 3_free()] direct
11cb0 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 ly. Only.** [sq
11cc0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
11cd0 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 ()] is able to r
11ce0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 elease the memor
11cf0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 y properly and s
11d00 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 afely..**.** The
11d10 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
11d20 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 le() interface i
11d30 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 s implemented as
11d40 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e a wrapper aroun
11d50 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 d.** [sqlite3_ex
11d60 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 ec()]. The sqli
11d70 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 te3_get_table()
11d80 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 routine does not
11d90 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 have access.**
11da0 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 to any internal
11db0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 data structures
11dc0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 of SQLite. It u
11dd0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 ses only the pub
11de0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 lic.** interface
11df0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 defined here.
11e00 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 As a consequence
11e10 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 , errors that oc
11e20 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 cur in the.** wr
11e30 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 apper layer outs
11e40 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 ide of the inter
11e50 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 nal [sqlite3_exe
11e60 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f c()] call are no
11e70 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 t.** reflected i
11e80 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c n subsequent cal
11e90 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 ls to [sqlite3_e
11ea0 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 rrcode()] or [sq
11eb0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e lite3_errmsg()].
11ec0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
11ed0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 37 31 5d nts:.** [H12371]
11ee0 20 5b 48 31 32 33 37 33 5d 20 5b 48 31 32 33 37 [H12373] [H1237
11ef0 34 5d 20 5b 48 31 32 33 37 36 5d 20 5b 48 31 32 4] [H12376] [H12
11f00 33 37 39 5d 20 5b 48 31 32 33 38 32 5d 0a 2a 2f 379] [H12382].*/
11f10 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
11f20 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
11f30 49 20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 I SQLITE_API int
11f40 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
11f50 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 le(. sqlite3 *d
11f60 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 b, /* A
11f70 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 n open database
11f80 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
11f90 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 *zSql, /* SQ
11fa0 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 L to be evaluate
11fb0 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 d */. char ***p
11fc0 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 azResult, /*
11fd0 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 Results of the q
11fe0 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 uery */. int *p
11ff0 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 nRow,
12000 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 /* Number of res
12010 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e ult rows written
12020 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a here */. int *
12030 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 pnColumn,
12040 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 /* Number of re
12050 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 sult columns wri
12060 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 tten here */. c
12070 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 har **pzErrmsg
12080 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 /* Error ms
12090 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a g written here *
120a0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 /.);.SQLITE_API
120b0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
120c0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
120d0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 void sqlite3_fr
120e0 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a ee_table(char **
120f0 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 result);../*.**
12100 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 CAPI3REF: Format
12110 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 ted String Print
12120 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 ing Functions {H
12130 31 37 34 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 17400} <S70000><
12140 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S20000>.**.** Th
12150 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
12160 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 workalikes of t
12170 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 he "printf()" fa
12180 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e mily of function
12190 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 s.** from the st
121a0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
121b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
121c0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e te3_mprintf() an
121d0 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e d sqlite3_vmprin
121e0 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 tf() routines wr
121f0 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 ite their.** res
12200 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 ults into memory
12210 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
12220 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
12230 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 ]..** The string
12240 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
12250 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 ese two routines
12260 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 should be.** re
12270 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 leased by [sqlit
12280 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 e3_free()]. Bot
12290 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 h routines retur
122a0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e n a.** NULL poin
122b0 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f ter if [sqlite3_
122c0 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 malloc()] is una
122d0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 ble to allocate
122e0 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 enough.** memory
122f0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 to hold the res
12300 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a ulting string..*
12310 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f *.** In sqlite3_
12320 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 snprintf() routi
12330 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f ne is similar to
12340 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 "snprintf()" fr
12350 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 om.** the standa
12360 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 rd C library. T
12370 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 he result is wri
12380 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a tten into the.**
12390 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 buffer supplied
123a0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 as the second p
123b0 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 arameter whose s
123c0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a ize is given by.
123d0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 ** the first par
123e0 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 ameter. Note tha
123f0 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 t the order of t
12400 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 he.** first two
12410 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 parameters is re
12420 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 versed from snpr
12430 69 6e 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 intf(). This is
12440 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 an.** historica
12450 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 l accident that
12460 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 cannot be fixed
12470 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 without breaking
12480 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f .** backwards co
12490 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f mpatibility. No
124a0 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c te also that sql
124b0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a ite3_snprintf().
124c0 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ** returns a poi
124d0 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 nter to its buff
124e0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 er instead of th
124f0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 e number of.** c
12500 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c haracters actual
12510 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 ly written into
12520 74 68 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 the buffer. We
12530 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 admit that.** th
12540 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
12550 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 acters written w
12560 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 ould be a more u
12570 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 seful return.**
12580 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e value but we can
12590 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 not change the i
125a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
125b0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
125c0 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f f().** now witho
125d0 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 ut breaking comp
125e0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a atibility..**.**
125f0 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 As long as the
12600 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 buffer size is g
12610 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f reater than zero
12620 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e , sqlite3_snprin
12630 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 tf().** guarante
12640 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 es that the buff
12650 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 er is always zer
12660 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 o-terminated. T
12670 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 he first.** para
12680 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 meter "n" is the
12690 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 total size of t
126a0 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 he buffer, inclu
126b0 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a ding space for.*
126c0 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 * the zero termi
126d0 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c nator. So the l
126e0 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 ongest string th
126f0 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 at can be comple
12700 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 tely.** written
12710 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 will be n-1 char
12720 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 acters..**.** Th
12730 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c ese routines all
12740 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 implement some
12750 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 additional forma
12760 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 tting.** options
12770 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c that are useful
12780 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e for constructin
12790 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 g SQL statements
127a0 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 ..** All of the
127b0 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 usual printf() f
127c0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e ormatting option
127d0 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 s apply. In add
127e0 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 ition, there.**
127f0 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 is are "%q", "%Q
12800 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 ", and "%z" opti
12810 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 ons..**.** The %
12820 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c q option works l
12830 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 ike %s in that i
12840 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 t substitutes a
12850 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a null-terminated.
12860 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 ** string from t
12870 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 he argument list
12880 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 . But %q also d
12890 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 oubles every '\'
128a0 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 ' character..**
128b0 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 %q is designed f
128c0 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 or use inside a
128d0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 string literal.
128e0 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 By doubling eac
128f0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 h '\''.** charac
12900 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 ter it escapes t
12910 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e hat character an
12920 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 d allows it to b
12930 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a e inserted into.
12940 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a ** the string..*
12950 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 *.** For example
12960 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 , assume the str
12970 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 ing variable zTe
12980 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 xt contains text
12990 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
129a0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
129b0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
129c0 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 Text = "It's a h
129d0 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c appy day!";.** <
129e0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
129f0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e e>.**.** One can
12a00 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 use this text i
12a10 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
12a20 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a nt as follows:.*
12a30 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
12a40 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 ><pre>.** char
12a50 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f *zSQL = sqlite3_
12a60 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 mprintf("INSERT
12a70 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 INTO table VALUE
12a80 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 S('%q')", zText)
12a90 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 ;.** sqlite3_ex
12aa0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 ec(db, zSQL, 0,
12ab0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 0, 0);.** sqlit
12ac0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a e3_free(zSQL);.*
12ad0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
12ae0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 uote>.**.** Beca
12af0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 use the %q forma
12b00 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 t string is used
12b10 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 , the '\'' chara
12b20 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a cter in zText.**
12b30 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 is escaped and
12b40 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 the SQL generate
12b50 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a d is as follows:
12b60 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
12b70 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 te><pre>.** INS
12b80 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 ERT INTO table1
12b90 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 VALUES('It''s a
12ba0 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 happy day!').**
12bb0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
12bc0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 te>.**.** This i
12bd0 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 s correct. Had
12be0 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 we used %s inste
12bf0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 ad of %q, the ge
12c00 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 nerated SQL.** w
12c10 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 ould have looked
12c20 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a like this:.**.*
12c30 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
12c40 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 re>.** INSERT I
12c50 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 NTO table1 VALUE
12c60 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 S('It's a happy
12c70 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 day!');.** </pre
12c80 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
12c90 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 *.** This second
12ca0 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 example is an S
12cb0 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e QL syntax error.
12cc0 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 As a general r
12cd0 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a ule you should.*
12ce0 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 * always use %q
12cf0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 instead of %s wh
12d00 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 en inserting tex
12d10 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 t into a string
12d20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 literal..**.** T
12d30 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 he %Q option wor
12d40 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 ks like %q excep
12d50 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 t it also adds s
12d60 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f ingle quotes aro
12d70 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 und.** the outsi
12d80 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 de of the total
12d90 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f string. Additio
12da0 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 nally, if the pa
12db0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a rameter in the.*
12dc0 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 * argument list
12dd0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
12de0 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 r, %Q substitute
12df0 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c s the text "NULL
12e00 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 " (without.** si
12e10 6e 67 6c 65 20 71 75 6f 74 65 73 29 20 69 6e 20 ngle quotes) in
12e20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 place of the %Q
12e30 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 option. So, for
12e40 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f example, one co
12e50 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c uld say:.**.** <
12e60 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
12e70 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 .** char *zSQL
12e80 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 = sqlite3_mprint
12e90 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 f("INSERT INTO t
12ea0 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 able VALUES(%Q)"
12eb0 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 , zText);.** sq
12ec0 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a lite3_exec(db, z
12ed0 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a SQL, 0, 0, 0);.*
12ee0 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 * sqlite3_free(
12ef0 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e zSQL);.** </pre>
12f00 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
12f10 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f .** The code abo
12f20 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 ve will render a
12f30 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 correct SQL sta
12f40 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 tement in the zS
12f50 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 QL.** variable e
12f60 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 ven if the zText
12f70 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e variable is a N
12f80 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
12f90 2a 2a 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d ** The "%z" form
12fa0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f atting option wo
12fb0 72 6b 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 rks exactly like
12fc0 20 22 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a "%s" with the.*
12fd0 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 * addition that
12fe0 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 after the string
12ff0 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 has been read a
13000 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a nd copied into.*
13010 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 * the result, [s
13020 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 qlite3_free()] i
13030 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 s called on the
13040 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 input string. {E
13050 4e 44 7d 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ND}.**.** Requir
13060 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 34 ements:.** [H174
13070 30 33 5d 20 5b 48 31 37 34 30 36 5d 20 5b 48 31 03] [H17406] [H1
13080 37 34 30 37 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 7407].*/.SQLITE_
13090 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
130a0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
130b0 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 _API char *sqlit
130c0 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 e3_mprintf(const
130d0 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c char*,...);.SQL
130e0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
130f0 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
13100 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 LITE_API char *s
13110 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 qlite3_vmprintf(
13120 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f const char*, va_
13130 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 list);.SQLITE_AP
13140 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
13150 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
13160 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 PI char *sqlite3
13170 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 _snprintf(int,ch
13180 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
13190 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ...);../*.** CA
131a0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 PI3REF: Memory A
131b0 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 llocation Subsys
131c0 74 65 6d 20 7b 48 31 37 33 30 30 7d 20 3c 53 32 tem {H17300} <S2
131d0 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0000>.**.** The
131e0 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65 SQLite core use
131f0 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f s these three ro
13200 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f utines for all o
13210 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 f its own.** int
13220 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c ernal memory all
13230 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 ocation needs. "
13240 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 Core" in the pre
13250 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a vious sentence.*
13260 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 * does not inclu
13270 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 de operating-sys
13280 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 tem specific VFS
13290 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
132a0 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 The.** Windows
132b0 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 VFS uses native
132c0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 malloc() and fr
132d0 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 ee() for some op
132e0 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 erations..**.**
132f0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c The sqlite3_mall
13300 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 oc() routine ret
13310 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
13320 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 o a block.** of
13330 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 memory at least
13340 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 N bytes in lengt
13350 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 h, where N is th
13360 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 e parameter..**
13370 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f If sqlite3_mallo
13380 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f c() is unable to
13390 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 obtain sufficie
133a0 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 nt free.** memor
133b0 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 y, it returns a
133c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 NULL pointer. I
133d0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
133e0 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f N to.** sqlite3_
133f0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f malloc() is zero
13400 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 or negative the
13410 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 n sqlite3_malloc
13420 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 () returns.** a
13430 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
13440 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 .** Calling sqli
13450 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 te3_free() with
13460 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f a pointer previo
13470 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a usly returned.**
13480 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c by sqlite3_mall
13490 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f oc() or sqlite3_
134a0 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 realloc() releas
134b0 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 es that memory s
134c0 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 o.** that it mig
134d0 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 54 ht be reused. T
134e0 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 he sqlite3_free(
134f0 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 ) routine is.**
13500 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 a no-op if is ca
13510 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c lled with a NULL
13520 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 pointer. Passi
13530 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ng a NULL pointe
13540 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f r.** to sqlite3_
13550 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 free() is harmle
13560 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 ss. After being
13570 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a freed, memory.*
13580 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 * should neither
13590 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 be read nor wri
135a0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 tten. Even read
135b0 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 ing previously f
135c0 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d reed.** memory m
135d0 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 ight result in a
135e0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 segmentation fa
135f0 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 ult or other sev
13600 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 ere error..** Me
13610 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c mory corruption,
13620 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 a segmentation
13630 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 fault, or other
13640 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 severe error.**
13650 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 might result if
13660 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 sqlite3_free() i
13670 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 s called with a
13680 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 non-NULL pointer
13690 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 that.** was not
136a0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 obtained from s
136b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
136c0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c or sqlite3_reall
136d0 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 oc()..**.** The
136e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
136f0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 ) interface atte
13700 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 mpts to resize a
13710 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 .** prior memory
13720 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 allocation to b
13730 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 e at least N byt
13740 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 es, where N is t
13750 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 he.** second par
13760 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d ameter. The mem
13770 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 ory allocation t
13780 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 o be resized is
13790 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 the first.** par
137a0 61 6d 65 74 65 72 2e 20 20 49 66 20 74 68 65 20 ameter. If the
137b0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
137c0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
137d0 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c oc().** is a NUL
137e0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 L pointer then i
137f0 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 ts behavior is i
13800 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c dentical to call
13810 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d ing.** sqlite3_m
13820 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e alloc(N) where N
13830 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 is the second p
13840 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
13850 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a te3_realloc()..*
13860 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 * If the second
13870 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
13880 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 ite3_realloc() i
13890 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 s zero or.** neg
138a0 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 ative then the b
138b0 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 ehavior is exact
138c0 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 ly the same as c
138d0 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 alling.** sqlite
138e0 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 3_free(P) where
138f0 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 P is the first p
13900 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
13910 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a te3_realloc()..*
13920 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f * sqlite3_reallo
13930 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f c() returns a po
13940 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 inter to a memor
13950 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 y allocation.**
13960 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 of at least N by
13970 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e tes in size or N
13980 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e ULL if sufficien
13990 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 t memory is unav
139a0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d ailable..** If M
139b0 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 is the size of
139c0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 the prior alloca
139d0 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e tion, then min(N
139e0 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 ,M) bytes.** of
139f0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 the prior alloca
13a00 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 tion are copied
13a10 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 into the beginni
13a20 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 ng of buffer ret
13a30 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 urned.** by sqli
13a40 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e te3_realloc() an
13a50 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f d the prior allo
13a60 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e cation is freed.
13a70 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 72 .** If sqlite3_r
13a80 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 ealloc() returns
13a90 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 NULL, then the
13aa0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
13ab0 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 .** is not freed
13ac0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f ..**.** The memo
13ad0 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ry returned by s
13ae0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
13af0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c and sqlite3_real
13b00 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 loc().** is alwa
13b10 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 ys aligned to at
13b20 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 least an 8 byte
13b30 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d boundary. {END}
13b40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 .**.** The defau
13b50 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f lt implementatio
13b60 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 n of the memory
13b70 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 allocation subsy
13b80 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20 74 68 65 stem uses.** the
13b90 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c malloc(), reall
13ba0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
13bb0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 provided by the
13bc0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
13bd0 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38 32 7d 20 ry..** {H17382}
13be0 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 However, if SQLi
13bf0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
13c00 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 ith the.** SQLIT
13c10 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 E_MEMORY_SIZE=<i
13c20 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 65 70 72 >NNN</i> C prepr
13c30 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 28 77 ocessor macro (w
13c40 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a here <i>NNN</i>.
13c50 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ** is an integer
13c60 29 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 ), then SQLite c
13c70 72 65 61 74 65 20 61 20 73 74 61 74 69 63 20 61 reate a static a
13c80 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73 74 rray of at least
13c90 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 .** <i>NNN</i> b
13ca0 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 ytes in size and
13cb0 20 75 73 65 73 20 74 68 61 74 20 61 72 72 61 79 uses that array
13cc0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 for all of its
13cd0 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 dynamic.** memor
13ce0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 y allocation nee
13cf0 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69 74 ds. {END} Addit
13d00 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c ional memory all
13d10 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a ocator options.*
13d20 2a 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 * may be added i
13d30 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
13d40 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 s..**.** In SQLi
13d50 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 te version 3.5.0
13d60 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 and 3.5.1, it w
13d70 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 as possible to d
13d80 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c efine.** the SQL
13d90 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f ITE_OMIT_MEMORY_
13da0 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 ALLOCATION which
13db0 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 would cause the
13dc0 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 built-in.** imp
13dd0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
13de0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f hese routines to
13df0 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 be omitted. Th
13e00 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a at capability.**
13e10 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 is no longer pr
13e20 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 ovided. Only bu
13e30 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c ilt-in memory al
13e40 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 locators can be
13e50 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 used..**.** The
13e60 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 Windows OS inter
13e70 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 face layer calls
13e80 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d .** the system m
13e90 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 alloc() and free
13ea0 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e () directly when
13eb0 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 converting.** f
13ec0 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e ilenames between
13ed0 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 the UTF-8 encod
13ee0 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 ing used by SQLi
13ef0 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 te.** and whatev
13f00 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f er filename enco
13f10 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 ding is used by
13f20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 the particular W
13f30 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c indows.** instal
13f40 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 lation. Memory
13f50 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
13f60 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 s are detected,
13f70 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 but.** they are
13f80 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 reported back as
13f90 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 [SQLITE_CANTOPE
13fa0 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 N] or.** [SQLITE
13fb0 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 _IOERR] rather t
13fc0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 han [SQLITE_NOME
13fd0 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 M]..**.** Requir
13fe0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 ements:.** [H173
13ff0 30 33 5d 20 5b 48 31 37 33 30 34 5d 20 5b 48 31 03] [H17304] [H1
14000 37 33 30 35 5d 20 5b 48 31 37 33 30 36 5d 20 5b 7305] [H17306] [
14010 48 31 37 33 31 30 5d 20 5b 48 31 37 33 31 32 5d H17310] [H17312]
14020 20 5b 48 31 37 33 31 35 5d 20 5b 48 31 37 33 31 [H17315] [H1731
14030 38 5d 0a 2a 2a 20 5b 48 31 37 33 32 31 5d 20 5b 8].** [H17321] [
14040 48 31 37 33 32 32 5d 20 5b 48 31 37 33 32 33 5d H17322] [H17323]
14050 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 .**.** The point
14060 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 er arguments to
14070 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
14080 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
14090 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 alloc()].** must
140a0 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 be either NULL
140b0 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 or else pointers
140c0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 obtained from a
140d0 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 prior.** invoca
140e0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
140f0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 _malloc()] or [s
14100 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
14110 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e ] that have.** n
14120 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 ot yet been rele
14130 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ased..**.** The
14140 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
14150 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 not read or wri
14160 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a te any part of.*
14170 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d * a block of mem
14180 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 ory after it has
14190 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 been released u
141a0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
141b0 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c _free()] or [sql
141c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e ite3_realloc()].
141d0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 .*/.SQLITE_API S
141e0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
141f0 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
14200 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 void *sqlite3_ma
14210 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 lloc(int);.SQLIT
14220 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
14230 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
14240 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c TE_API void *sql
14250 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 ite3_realloc(voi
14260 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 d*, int);.SQLITE
14270 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
14280 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
14290 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
142a0 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a e3_free(void*);.
142b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
142c0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f Memory Allocato
142d0 72 20 53 74 61 74 69 73 74 69 63 73 20 7b 48 31 r Statistics {H1
142e0 37 33 37 30 7d 20 3c 53 33 30 32 31 30 3e 0a 2a 7370} <S30210>.*
142f0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 *.** SQLite prov
14300 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 ides these two i
14310 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 nterfaces for re
14320 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 porting on the s
14330 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 tatus.** of the
14340 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
14350 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 )], [sqlite3_fre
14360 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 e()], and [sqlit
14370 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a e3_realloc()].**
14380 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 routines, which
14390 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d form the built-
143a0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
143b0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a tion subsystem..
143c0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
143d0 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 37 31 5d 20 ts:.** [H17371]
143e0 5b 48 31 37 33 37 33 5d 20 5b 48 31 37 33 37 34 [H17373] [H17374
143f0 5d 20 5b 48 31 37 33 37 35 5d 0a 2a 2f 0a 53 51 ] [H17375].*/.SQ
14400 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
14410 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
14420 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
14430 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
14440 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 memory_used(void
14450 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 );.SQLITE_API SQ
14460 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
14470 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 73 API SQLITE_API s
14480 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
14490 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
144a0 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 water(int resetF
144b0 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 lag);../*.** CAP
144c0 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 I3REF: Pseudo-Ra
144d0 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 ndom Number Gene
144e0 72 61 74 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c rator {H17390} <
144f0 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 S20000>.**.** SQ
14500 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 Lite contains a
14510 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 high-quality pse
14520 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 udo-random numbe
14530 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e r generator (PRN
14540 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 G) used to.** se
14550 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 lect random [ROW
14560 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 ID | ROWIDs] whe
14570 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 n inserting new
14580 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 records into a t
14590 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 able that.** alr
145a0 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 eady uses the la
145b0 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b rgest possible [
145c0 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e ROWID]. The PRN
145d0 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 G is also used f
145e0 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d or.** the build-
145f0 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 in random() and
14600 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c randomblob() SQL
14610 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 functions. Thi
14620 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f s interface allo
14630 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f ws.** applicatio
14640 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 ns to access the
14650 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f same PRNG for o
14660 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a ther purposes..*
14670 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74 *.** A call to t
14680 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 his routine stor
14690 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 es N bytes of ra
146a0 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 ndomness into bu
146b0 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 ffer P..**.** Th
146c0 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 e first time thi
146d0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 s routine is inv
146e0 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 oked (either int
146f0 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a ernally or by.**
14700 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
14710 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 ) the PRNG is se
14720 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f eded using rando
14730 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a mness obtained.*
14740 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 * from the xRand
14750 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 omness method of
14760 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 the default [sq
14770 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
14780 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 t..** On all sub
14790 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 sequent invocati
147a0 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d ons, the pseudo-
147b0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 randomness is ge
147c0 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 nerated.** inter
147d0 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 nally and withou
147e0 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 t recourse to th
147f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 e [sqlite3_vfs]
14800 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d xRandomness.** m
14810 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 ethod..**.** Req
14820 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
14830 31 37 33 39 32 5d 0a 2a 2f 0a 53 51 4c 49 54 45 17392].*/.SQLITE
14840 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
14850 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
14860 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
14870 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e e3_randomness(in
14880 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a t N, void *P);..
14890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
148a0 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 Compile-Time Aut
148b0 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 horization Callb
148c0 61 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c 53 acks {H12500} <S
148d0 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 70100>.**.** Thi
148e0 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 s routine regist
148f0 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 ers a authorizer
14900 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 callback with a
14910 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b particular.** [
14920 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
14930 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 ion], supplied i
14940 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
14950 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 ment..** The aut
14960 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
14970 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 is invoked as S
14980 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 QL statements ar
14990 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 e being compiled
149a0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f .** by [sqlite3_
149b0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 prepare()] or it
149c0 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 s variants [sqli
149d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
149e0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 ],.** [sqlite3_p
149f0 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 repare16()] and
14a00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
14a10 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 16_v2()]. At va
14a20 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 rious.** points
14a30 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 during the compi
14a40 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 lation process,
14a50 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e as logic is bein
14a60 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 g created.** to
14a70 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 perform various
14a80 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 actions, the aut
14a90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
14aa0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a is invoked to.*
14ab0 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 * see if those a
14ac0 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 ctions are allow
14ad0 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 ed. The authori
14ae0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f zer callback sho
14af0 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 uld.** return [S
14b00 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c QLITE_OK] to all
14b10 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b ow the action, [
14b20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 SQLITE_IGNORE] t
14b30 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a o disallow the.*
14b40 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f * specific actio
14b50 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 n but allow the
14b60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f SQL statement to
14b70 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a continue to be.
14b80 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 ** compiled, or
14b90 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f [SQLITE_DENY] to
14ba0 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 cause the entir
14bb0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
14bc0 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 to be.** rejecte
14bd0 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e d with an error.
14be0 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 If the authori
14bf0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 zer callback ret
14c00 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 urns.** any valu
14c10 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 e other than [SQ
14c20 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 LITE_IGNORE], [S
14c30 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 QLITE_OK], or [S
14c40 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 QLITE_DENY].** t
14c50 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 hen the [sqlite3
14c60 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
14c70 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c r equivalent cal
14c80 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 l that triggered
14c90 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a .** the authoriz
14ca0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 er will fail wit
14cb0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 h an error messa
14cc0 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 ge..**.** When t
14cd0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
14ce0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c rns [SQLITE_OK],
14cf0 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 that means the
14d00 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 operation.** req
14d10 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 uested is ok. W
14d20 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
14d30 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
14d40 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b _DENY], the.** [
14d50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
14d60 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c v2()] or equival
14d70 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 ent call that tr
14d80 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 iggered the.** a
14d90 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 uthorizer will f
14da0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f ail with an erro
14db0 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 r message explai
14dc0 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 ning that.** acc
14dd0 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a ess is denied. .
14de0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
14df0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
14e00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
14e10 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f back is a copy o
14e20 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 f the third.** p
14e30 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
14e40 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
14e50 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 orizer() interfa
14e60 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 ce. The second p
14e70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 arameter.** to t
14e80 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 he callback is a
14e90 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 n integer [SQLIT
14ea0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 E_COPY | action
14eb0 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 code] that speci
14ec0 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 fies.** the part
14ed0 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f icular action to
14ee0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 be authorized.
14ef0 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 The third throug
14f00 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 h sixth paramete
14f10 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c rs.** to the cal
14f20 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 lback are zero-t
14f30 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 erminated string
14f40 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 s that contain a
14f50 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 dditional.** det
14f60 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 ails about the a
14f70 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 ction to be auth
14f80 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 orized..**.** If
14f90 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 the action code
14fa0 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 is [SQLITE_READ
14fb0 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c ].** and the cal
14fc0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 lback returns [S
14fd0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 QLITE_IGNORE] th
14fe0 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 en the.** [prepa
14ff0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 red statement] s
15000 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 tatement is cons
15010 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 tructed to subst
15020 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 itute.** a NULL
15030 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f value in place o
15040 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 f the table colu
15050 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 mn that would ha
15060 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 ve.** been read
15070 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 if [SQLITE_OK] h
15080 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 ad been returned
15090 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 . The [SQLITE_I
150a0 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e GNORE].** return
150b0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
150c0 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 deny an untruste
150d0 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f d user access to
150e0 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 individual.** c
150f0 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c olumns of a tabl
15100 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 61 63 74 e..** If the act
15110 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c ion code is [SQL
15120 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 ITE_DELETE] and
15130 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
15140 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f urns.** [SQLITE_
15150 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 IGNORE] then the
15160 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 [DELETE] operat
15170 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 ion proceeds but
15180 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 the.** [truncat
15190 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 e optimization]
151a0 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 is disabled and
151b0 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c all rows are del
151c0 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c eted individuall
151d0 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 y..**.** An auth
151e0 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 orizer is used w
151f0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hen [sqlite3_pre
15200 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 pare | preparing
15210 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 ].** SQL stateme
15220 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 nts from an untr
15230 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f usted source, to
15240 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 ensure that the
15250 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
15260 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f ** do not try to
15270 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 access data the
15280 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 y are not allowe
15290 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 d to see, or tha
152a0 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a t they do not.**
152b0 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 try to execute
152c0 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d malicious statem
152d0 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 ents that damage
152e0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 the database.
152f0 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 For.** example,
15300 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d an application m
15310 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 ay allow a user
15320 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 to enter arbitra
15330 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 ry.** SQL querie
15340 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e s for evaluation
15350 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 by a database.
15360 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 But the applica
15370 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 tion does.** not
15380 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 want the user t
15390 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b o be able to mak
153a0 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e e arbitrary chan
153b0 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 ges to the.** da
153c0 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 tabase. An auth
153d0 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 orizer could the
153e0 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 n be put in plac
153f0 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 e while the.** u
15400 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 ser-entered SQL
15410 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 is being [sqlite
15420 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 3_prepare | prep
15430 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 ared] that.** di
15440 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 sallows everythi
15450 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 ng except [SELEC
15460 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a T] statements..*
15470 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e *.** Application
15480 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 s that need to p
15490 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 rocess SQL from
154a0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 untrusted source
154b0 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 s.** might also
154c0 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e consider lowerin
154d0 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 g resource limit
154e0 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 s using [sqlite3
154f0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 _limit()].** and
15500 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 limiting databa
15510 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 se size using th
15520 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e e [max_page_coun
15530 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 t] [PRAGMA].** i
15540 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 n addition to us
15550 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 ing an authorize
15560 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 r..**.** Only a
15570 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 single authorize
15580 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 r can be in plac
15590 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 e on a database
155a0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 connection.** at
155b0 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 a time. Each c
155c0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
155d0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 et_authorizer ov
155e0 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 errides the.** p
155f0 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 revious call. D
15600 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f isable the autho
15610 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c rizer by install
15620 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 ing a NULL callb
15630 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 ack..** The auth
15640 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c orizer is disabl
15650 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a ed by default..*
15660 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 *.** The authori
15670 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 zer callback mus
15680 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e t not do anythin
15690 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 g that will modi
156a0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 fy.** the databa
156b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
156c0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 at invoked the a
156d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
156e0 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 ck..** Note that
156f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
15700 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c e_v2()] and [sql
15710 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 ite3_step()] bot
15720 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a h modify their.*
15730 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
15740 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d ctions for the m
15750 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 eaning of "modif
15760 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 y" in this parag
15770 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e raph..**.** When
15780 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
15790 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 e_v2()] is used
157a0 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 to prepare a sta
157b0 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 tement, the.** s
157c0 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 tatement might b
157d0 65 20 72 65 70 72 65 70 61 72 65 64 20 64 75 72 e reprepared dur
157e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ing [sqlite3_ste
157f0 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a p()] due to a .*
15800 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e * schema change.
15810 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 Hence, the app
15820 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
15830 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a ensure that the.
15840 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f ** correct autho
15850 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 rizer callback r
15860 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 emains in place
15870 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 during the [sqli
15880 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a te3_step()]..**.
15890 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 ** Note that the
158a0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
158b0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
158c0 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b only during.** [
158d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
158e0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e )] or its varian
158f0 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 ts. Authorizati
15900 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 on is not.** per
15910 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 formed during st
15920 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 atement evaluati
15930 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 on in [sqlite3_s
15940 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a tep()], unless.*
15950 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 * as stated in t
15960 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 he previous para
15970 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 graph, sqlite3_s
15980 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a tep() invokes.**
15990 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
159a0 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 _v2() to reprepa
159b0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 re a statement a
159c0 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 fter a schema ch
159d0 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 ange..**.** Requ
159e0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
159f0 32 35 30 31 5d 20 5b 48 31 32 35 30 32 5d 20 5b 2501] [H12502] [
15a00 48 31 32 35 30 33 5d 20 5b 48 31 32 35 30 34 5d H12503] [H12504]
15a10 20 5b 48 31 32 35 30 35 5d 20 5b 48 31 32 35 30 [H12505] [H1250
15a20 36 5d 20 5b 48 31 32 35 30 37 5d 20 5b 48 31 32 6] [H12507] [H12
15a30 35 31 30 5d 0a 2a 2a 20 5b 48 31 32 35 31 31 5d 510].** [H12511]
15a40 20 5b 48 31 32 35 31 32 5d 20 5b 48 31 32 35 32 [H12512] [H1252
15a50 30 5d 20 5b 48 31 32 35 32 31 5d 20 5b 48 31 32 0] [H12521] [H12
15a60 35 32 32 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 522].*/.SQLITE_A
15a70 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
15a80 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
15a90 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
15aa0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a set_authorizer(.
15ab0 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e sqlite3*,. in
15ac0 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a t (*xAuth)(void*
15ad0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a ,int,const char*
15ae0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e ,const char*,con
15af0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 st char*,const c
15b00 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 har*),. void *p
15b10 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a UserData.);../*.
15b20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 ** CAPI3REF: Aut
15b30 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 horizer Return C
15b40 6f 64 65 73 20 7b 48 31 32 35 39 30 7d 20 3c 48 odes {H12590} <H
15b50 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 12500>.**.** The
15b60 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
15b70 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f thorizer | autho
15b80 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 rizer callback f
15b90 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a unction] must.**
15ba0 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b return either [
15bb0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e SQLITE_OK] or on
15bc0 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 e of these two c
15bd0 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 onstants in orde
15be0 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 r.** to signal S
15bf0 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 QLite whether or
15c00 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 not the action
15c10 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 is permitted. S
15c20 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ee the.** [sqlit
15c30 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
15c40 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 r | authorizer d
15c50 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f ocumentation] fo
15c60 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 r additional.**
15c70 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a information..*/.
15c80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
15c90 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f ENY 1 /* Abo
15ca0 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 rt the SQL state
15cb0 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 ment with an err
15cc0 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
15cd0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 LITE_IGNORE 2
15ce0 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 /* Don't allow a
15cf0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 ccess, but don't
15d00 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 generate an err
15d10 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 or */../*.** CAP
15d20 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 I3REF: Authorize
15d30 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b r Action Codes {
15d40 48 31 32 35 35 30 7d 20 3c 48 31 32 35 30 30 3e H12550} <H12500>
15d50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 .**.** The [sqli
15d60 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
15d70 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 er()] interface
15d80 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c registers a call
15d90 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a back function.**
15da0 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 that is invoked
15db0 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 to authorize ce
15dc0 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d rtain SQL statem
15dd0 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 ent actions. Th
15de0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 e.** second para
15df0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c meter to the cal
15e00 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 lback is an inte
15e10 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 ger code that sp
15e20 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 ecifies.** what
15e30 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 action is being
15e40 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 authorized. The
15e50 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 se are the integ
15e60 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 er action codes
15e70 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 that.** the auth
15e80 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
15e90 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a may be passed..*
15ea0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f *.** These actio
15eb0 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 n code values si
15ec0 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 gnify what kind
15ed0 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 of operation is
15ee0 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 to be.** authori
15ef0 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e zed. The 3rd an
15f00 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 d 4th parameters
15f10 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a to the authoriz
15f20 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 ation.** callbac
15f30 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 k function will
15f40 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 be parameters or
15f50 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 NULL depending
15f60 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 on which of thes
15f70 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 e.** codes is us
15f80 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
15f90 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 parameter. The
15fa0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 5th parameter t
15fb0 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 o the.** authori
15fc0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
15fd0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
15fe0 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 database ("main"
15ff0 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 , "temp",.** etc
16000 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 .) if applicable
16010 2e 20 20 54 68 65 20 36 74 68 20 70 61 72 61 6d . The 6th param
16020 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 eter to the auth
16030 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a orizer callback.
16040 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f ** is the name o
16050 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 f the inner-most
16060 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 trigger or view
16070 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 that is respons
16080 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 ible for.** the
16090 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f access attempt o
160a0 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 r NULL if this a
160b0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 ccess attempt is
160c0 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a directly from.*
160d0 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 * top-level SQL
160e0 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 code..**.** Requ
160f0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
16100 32 35 35 31 5d 20 5b 48 31 32 35 35 32 5d 20 5b 2551] [H12552] [
16110 48 31 32 35 35 33 5d 20 5b 48 31 32 35 35 34 5d H12553] [H12554]
16120 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a .*/./***********
16130 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
16140 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
16150 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 3rd ***********
16160 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a * 4th **********
16170 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16180 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 E_CREATE_INDEX
16190 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 1 /* I
161a0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
161b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
161c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
161d0 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 _CREATE_TABLE
161e0 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 2 /* Ta
161f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
16200 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
16210 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16220 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 CREATE_TEMP_INDE
16230 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 X 3 /* Ind
16240 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
16250 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
16260 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16270 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 REATE_TEMP_TABLE
16280 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 4 /* Tabl
16290 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
162a0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
162b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
162c0 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 EATE_TEMP_TRIGGE
162d0 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 R 5 /* Trigg
162e0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
162f0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
16300 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
16310 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 ATE_TEMP_VIEW
16320 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 6 /* View N
16330 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
16340 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
16350 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
16360 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 TE_TRIGGER
16370 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 7 /* Trigger
16380 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
16390 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
163a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
163b0 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 E_VIEW
163c0 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 8 /* View Nam
163d0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
163e0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
163f0 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 ne SQLITE_DELETE
16400 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
16410 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 9 /* Table Nam
16420 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
16430 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
16440 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e e SQLITE_DROP_IN
16450 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 DEX 10
16460 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
16470 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
16480 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
16490 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 SQLITE_DROP_TAB
164a0 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 LE 11
164b0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
164c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
164d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
164e0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
164f0 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 _INDEX 12
16500 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
16510 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
16520 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
16530 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
16540 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 TABLE 13
16550 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
16560 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
16570 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
16580 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 LITE_DROP_TEMP_T
16590 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f RIGGER 14 /
165a0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
165b0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
165c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
165d0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 ITE_DROP_TEMP_VI
165e0 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a EW 15 /*
165f0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
16600 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
16610 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16620 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 TE_DROP_TRIGGER
16630 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 16 /*
16640 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
16650 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
16660 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16670 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 E_DROP_VIEW
16680 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 17 /* V
16690 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
166a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
166b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
166c0 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 _INSERT
166d0 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 18 /* Ta
166e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
166f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
16700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16710 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 PRAGMA
16720 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 19 /* Pra
16730 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 gma Name 1st
16740 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a arg or NULL */.
16750 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
16760 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 EAD
16770 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 20 /* Tabl
16780 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 e Name Colu
16790 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 mn Name */.#
167a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 define SQLITE_SE
167b0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 LECT
167c0 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 21 /* NULL
167d0 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 NULL
167e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
167f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 efine SQLITE_TRA
16800 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 NSACTION
16810 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 22 /* Operat
16820 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ion NULL
16830 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
16840 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 fine SQLITE_UPDA
16850 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TE
16860 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 23 /* Table N
16870 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 ame Column
16880 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
16890 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 ine SQLITE_ATTAC
168a0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
168b0 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 24 /* Filename
168c0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 NULL
168d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
168e0 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 ne SQLITE_DETACH
168f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
16900 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 5 /* Database
16910 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 Name NULL
16920 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
16930 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 e SQLITE_ALTER_T
16940 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 ABLE 26
16950 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e /* Database N
16960 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 ame Table Name
16970 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
16980 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 SQLITE_REINDEX
16990 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 27
169a0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
169b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
169c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
169d0 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 SQLITE_ANALYZE
169e0 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 28
169f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
16a00 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
16a10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
16a20 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 QLITE_CREATE_VTA
16a30 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 BLE 29
16a40 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
16a50 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 Module Name
16a60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
16a70 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 LITE_DROP_VTABLE
16a80 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 30 /
16a90 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
16aa0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 Module Name
16ab0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
16ac0 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 ITE_FUNCTION
16ad0 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 31 /*
16ae0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
16af0 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 Function Name
16b00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16b10 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 TE_SAVEPOINT
16b20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 32 /*
16b30 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 Operation
16b40 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 Savepoint Name
16b50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16b60 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 E_COPY
16b70 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 0 /* N
16b80 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f o longer used */
16b90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
16ba0 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 : Tracing And Pr
16bb0 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e ofiling Function
16bc0 73 20 7b 48 31 32 32 38 30 7d 20 3c 53 36 30 34 s {H12280} <S604
16bd0 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 00>.** EXPERIMEN
16be0 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TAL.**.** These
16bf0 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 routines registe
16c00 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 r callback funct
16c10 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 ions that can be
16c20 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 used for.** tra
16c30 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 cing and profili
16c40 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e ng the execution
16c50 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e of SQL statemen
16c60 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 ts..**.** The ca
16c70 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
16c80 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 registered by sq
16c90 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 lite3_trace() is
16ca0 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 invoked at.** v
16cb0 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 arious times whe
16cc0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
16cd0 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 nt is being run
16ce0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 by [sqlite3_step
16cf0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c ()]..** The call
16d00 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 back returns a U
16d10 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f TF-8 rendering o
16d20 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d f the SQL statem
16d30 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 ent text.** as t
16d40 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 he statement fir
16d50 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 st begins execut
16d60 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c ing. Additional
16d70 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 callbacks occur
16d80 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 .** as each trig
16d90 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d gered subprogram
16da0 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 is entered. Th
16db0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 e callbacks for
16dc0 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 triggers.** cont
16dd0 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 ain a UTF-8 SQL
16de0 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 comment that ide
16df0 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 ntifies the trig
16e00 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ger..**.** The c
16e10 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
16e20 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 registered by s
16e30 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 qlite3_profile()
16e40 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 is invoked.** a
16e50 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 s each SQL state
16e60 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 ment finishes.
16e70 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c The profile call
16e80 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a back contains.**
16e90 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 the original st
16ea0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 atement text and
16eb0 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 an estimate of
16ec0 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a wall-clock time.
16ed0 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 ** of how long t
16ee0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f hat statement to
16ef0 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a ok to run..**.**
16f00 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
16f10 2a 20 5b 48 31 32 32 38 31 5d 20 5b 48 31 32 32 * [H12281] [H122
16f20 38 32 5d 20 5b 48 31 32 32 38 33 5d 20 5b 48 31 82] [H12283] [H1
16f30 32 32 38 34 5d 20 5b 48 31 32 32 38 35 5d 20 5b 2284] [H12285] [
16f40 48 31 32 32 38 37 5d 20 5b 48 31 32 32 38 38 5d H12287] [H12288]
16f50 20 5b 48 31 32 32 38 39 5d 0a 2a 2a 20 5b 48 31 [H12289].** [H1
16f60 32 32 39 30 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 2290].*/.SQLITE_
16f70 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
16f80 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
16f90 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 _API SQLITE_EXPE
16fa0 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 RIMENTAL void *s
16fb0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c qlite3_trace(sql
16fc0 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 ite3*, void(*xTr
16fd0 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 ace)(void*,const
16fe0 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b char*), void*);
16ff0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
17000 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
17010 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
17020 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c ITE_EXPERIMENTAL
17030 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 void *sqlite3_p
17040 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c rofile(sqlite3*,
17050 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 . void(*xProfi
17060 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 le)(void*,const
17070 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 char*,sqlite3_ui
17080 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a nt64), void*);..
17090 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
170a0 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 Query Progress C
170b0 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 31 30 allbacks {H12910
170c0 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a } <S60400>.**.**
170d0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f This routine co
170e0 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 nfigures a callb
170f0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 ack function - t
17100 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 he.** progress c
17110 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69 allback - that i
17120 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 s invoked period
17130 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f ically during lo
17140 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 ng.** running ca
17150 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
17160 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 exec()], [sqlite
17170 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 3_step()] and.**
17180 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 [sqlite3_get_ta
17190 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d ble()]. An exam
171a0 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 ple use for this
171b0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
171c0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 to keep a GUI u
171d0 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 pdated during a
171e0 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a large query..**.
171f0 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 ** If the progre
17200 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 ss callback retu
17210 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
17220 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a e operation is.*
17230 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 * interrupted.
17240 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e This feature can
17250 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c be used to impl
17260 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 ement a.** "Canc
17270 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 el" button on a
17280 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 GUI progress dia
17290 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 log box..**.** T
172a0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
172b0 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ler must not do
172c0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
172d0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
172e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
172f0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
17300 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 d the progress h
17310 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 andler..** Note
17320 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 that [sqlite3_pr
17330 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
17340 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
17350 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 both modify the
17360 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 ir.** database c
17370 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 onnections for t
17380 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d he meaning of "m
17390 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 odify" in this p
173a0 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 aragraph..**.**
173b0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
173c0 20 5b 48 31 32 39 31 31 5d 20 5b 48 31 32 39 31 [H12911] [H1291
173d0 32 5d 20 5b 48 31 32 39 31 33 5d 20 5b 48 31 32 2] [H12913] [H12
173e0 39 31 34 5d 20 5b 48 31 32 39 31 35 5d 20 5b 48 914] [H12915] [H
173f0 31 32 39 31 36 5d 20 5b 48 31 32 39 31 37 5d 20 12916] [H12917]
17400 5b 48 31 32 39 31 38 5d 0a 2a 2a 0a 2a 2f 0a 53 [H12918].**.*/.S
17410 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
17420 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
17430 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
17440 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 sqlite3_progress
17450 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 _handler(sqlite3
17460 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 *, int, int(*)(v
17470 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a oid*), void*);..
17480 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
17490 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 Opening A New Da
174a0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
174b0 6e 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32 n {H12700} <S402
174c0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 00>.**.** These
174d0 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e routines open an
174e0 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 SQLite database
174f0 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 file whose name
17500 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 is given by the
17510 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 .** filename arg
17520 75 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e ument. The filen
17530 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ame argument is
17540 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 interpreted as U
17550 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 TF-8 for.** sqli
17560 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 te3_open() and s
17570 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
17580 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 and as UTF-16 i
17590 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 n the native byt
175a0 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 e.** order for s
175b0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e qlite3_open16().
175c0 20 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e A [database con
175d0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 nection] handle
175e0 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 is usually.** re
175f0 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c turned in *ppDb,
17600 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f even if an erro
17610 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f r occurs. The o
17620 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 nly exception is
17630 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 that.** if SQLi
17640 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 te is unable to
17650 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 allocate memory
17660 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c to hold the [sql
17670 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a ite3] object,.**
17680 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 a NULL will be
17690 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 written into *pp
176a0 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 Db instead of a
176b0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b pointer to the [
176c0 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 sqlite3].** obje
176d0 63 74 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 ct. If the datab
176e0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 ase is opened (a
176f0 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 nd/or created) s
17700 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 uccessfully, the
17710 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d n.** [SQLITE_OK]
17720 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f is returned. O
17730 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 therwise an [err
17740 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
17750 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 rned. The.** [s
17760 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
17770 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 or [sqlite3_err
17780 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 msg16()] routine
17790 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f s can be used to
177a0 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e obtain.** an En
177b0 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 glish language d
177c0 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 escription of th
177d0 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 e error..**.** T
177e0 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 he default encod
177f0 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 ing for the data
17800 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 base will be UTF
17810 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 -8 if.** sqlite3
17820 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 _open() or sqlit
17830 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
17840 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 called and.** UT
17850 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 F-16 in the nati
17860 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 ve byte order if
17870 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
17880 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a ) is used..**.**
17890 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 Whether or not
178a0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 an error occurs
178b0 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 when it is opene
178c0 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 d, resources.**
178d0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
178e0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
178f0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 nnection] handle
17900 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 should be relea
17910 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e sed by.** passin
17920 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 g it to [sqlite3
17930 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 _close()] when i
17940 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 t is no longer r
17950 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 equired..**.** T
17960 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f he sqlite3_open_
17970 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 v2() interface w
17980 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 orks like sqlite
17990 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 3_open().** exce
179a0 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 pt that it accep
179b0 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 ts two additiona
179c0 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 l parameters for
179d0 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 additional cont
179e0 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 rol.** over the
179f0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e new database con
17a00 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c nection. The fl
17a10 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 ags parameter ca
17a20 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a n take one of.**
17a30 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 the following t
17a40 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 hree values, opt
17a50 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 ionally combined
17a60 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 with the .** [S
17a70 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
17a80 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f EX] or [SQLITE_O
17a90 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 PEN_FULLMUTEX] f
17aa0 6c 61 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e lags:.**.** <dl>
17ab0 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f .** <dt>[SQLITE_
17ac0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f OPEN_READONLY]</
17ad0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 dt>.** <dd>The d
17ae0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
17af0 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d d in read-only m
17b00 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 ode. If the dat
17b10 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a abase does not.*
17b20 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c * already exist,
17b30 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 an error is ret
17b40 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a urned.</dd>.**.*
17b50 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 * <dt>[SQLITE_OP
17b60 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 EN_READWRITE]</d
17b70 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 t>.** <dd>The da
17b80 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
17b90 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 for reading and
17ba0 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 writing if poss
17bb0 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 ible, or reading
17bc0 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 .** only if the
17bd0 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 file is write pr
17be0 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f otected by the o
17bf0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e perating system.
17c00 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 In either.** c
17c10 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 ase the database
17c20 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 must already ex
17c30 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 ist, otherwise a
17c40 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 n error is retur
17c50 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ned.</dd>.**.**
17c60 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e <dt>[SQLITE_OPEN
17c70 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 _READWRITE] | [S
17c80 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
17c90 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 E]</dt>.** <dd>T
17ca0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
17cb0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e pened for readin
17cc0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 g and writing, a
17cd0 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69 74 nd is creates it
17ce0 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e if.** it does n
17cf0 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 ot already exist
17d00 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 . This is the be
17d10 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 havior that is a
17d20 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a lways used for.*
17d30 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
17d40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 and sqlite3_ope
17d50 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c n16().</dd>.** <
17d60 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 /dl>.**.** If th
17d70 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
17d80 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
17d90 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 v2() is not one
17da0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e of the.** combin
17db0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f ations shown abo
17dc0 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 ve or one of the
17dd0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 combinations sh
17de0 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e own above combin
17df0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b ed.** with the [
17e00 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
17e10 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f TEX] or [SQLITE_
17e20 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 OPEN_FULLMUTEX]
17e30 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 flags,.** then t
17e40 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
17e50 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
17e60 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f If the [SQLITE_O
17e70 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 PEN_NOMUTEX] fla
17e80 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 g is set, then t
17e90 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
17ea0 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 ection.** opens
17eb0 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 in the multi-thr
17ec0 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d ead [threading m
17ed0 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 ode] as long as
17ee0 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 the single-threa
17ef0 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f d.** mode has no
17f00 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f t been set at co
17f10 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 mpile-time or st
17f20 61 72 74 2d 74 69 6d 65 2e 20 20 49 66 20 74 68 art-time. If th
17f30 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 e.** [SQLITE_OPE
17f40 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 N_FULLMUTEX] fla
17f50 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 g is set then th
17f60 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
17f70 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 ction opens.** i
17f80 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 n the serialized
17f90 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
17fa0 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d ] unless single-
17fb0 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 thread was.** pr
17fc0 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 eviously selecte
17fd0 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d d at compile-tim
17fe0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e e or start-time.
17ff0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 .**.** If the fi
18000 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f lename is ":memo
18010 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 ry:", then a pri
18020 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 vate, temporary
18030 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 in-memory databa
18040 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 se.** is created
18050 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 for the connect
18060 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 ion. This in-me
18070 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 mory database wi
18080 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a ll vanish when.*
18090 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
180a0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f onnection is clo
180b0 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 sed. Future ver
180c0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
180d0 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 might.** make us
180e0 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 e of additional
180f0 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 special filename
18100 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 s that begin wit
18110 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 h the ":" charac
18120 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 ter..** It is re
18130 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 commended that w
18140 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 hen a database f
18150 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 ilename actually
18160 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 does begin with
18170 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 .** a ":" charac
18180 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 ter you should p
18190 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 refix the filena
181a0 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 me with a pathna
181b0 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e me such as.** ".
181c0 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 /" to avoid ambi
181d0 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 guity..**.** If
181e0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 the filename is
181f0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c an empty string,
18200 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c then a private,
18210 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e temporary.** on
18220 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 -disk database w
18230 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 ill be created.
18240 20 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 This private da
18250 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a tabase will be.*
18260 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 * automatically
18270 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 deleted as soon
18280 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 as the database
18290 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c connection is cl
182a0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 osed..**.** The
182b0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
182c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
182d0 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d _v2() is the nam
182e0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c e of the.** [sql
182f0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
18300 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 that defines th
18310 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
18320 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 em interface tha
18330 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 t.** the new dat
18340 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
18350 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 should use. If
18360 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
18370 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 meter is.** a NU
18380 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
18390 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c the default [sql
183a0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
183b0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
183c0 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f <b>Note to Windo
183d0 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 ws users:</b> T
183e0 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 he encoding used
183f0 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d for the filenam
18400 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 e argument.** of
18410 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
18420 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e and sqlite3_open
18430 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 _v2() must be UT
18440 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 F-8, not whateve
18450 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 r.** codepage is
18460 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e currently defin
18470 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 ed. Filenames c
18480 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e ontaining intern
18490 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 ational.** chara
184a0 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f cters must be co
184b0 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 nverted to UTF-8
184c0 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e prior to passin
184d0 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 g them into.** s
184e0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 qlite3_open() or
184f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
18500 28 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ()..**.** Requir
18510 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 ements:.** [H127
18520 30 31 5d 20 5b 48 31 32 37 30 32 5d 20 5b 48 31 01] [H12702] [H1
18530 32 37 30 33 5d 20 5b 48 31 32 37 30 34 5d 20 5b 2703] [H12704] [
18540 48 31 32 37 30 36 5d 20 5b 48 31 32 37 30 37 5d H12706] [H12707]
18550 20 5b 48 31 32 37 30 39 5d 20 5b 48 31 32 37 31 [H12709] [H1271
18560 31 5d 0a 2a 2a 20 5b 48 31 32 37 31 32 5d 20 5b 1].** [H12712] [
18570 48 31 32 37 31 33 5d 20 5b 48 31 32 37 31 34 5d H12713] [H12714]
18580 20 5b 48 31 32 37 31 37 5d 20 5b 48 31 32 37 31 [H12717] [H1271
18590 39 5d 20 5b 48 31 32 37 32 31 5d 20 5b 48 31 32 9] [H12721] [H12
185a0 37 32 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 723].*/.SQLITE_A
185b0 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
185c0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
185d0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
185e0 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 open(. const ch
185f0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 ar *filename,
18600 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 /* Database file
18610 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a name (UTF-8) */.
18620 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 sqlite3 **ppDb
18630 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 /* OUT
18640 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 : SQLite db hand
18650 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f le */.);.SQLITE_
18660 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
18670 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
18680 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
18690 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 _open16(. const
186a0 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c void *filename,
186b0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 /* Database f
186c0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 ilename (UTF-16)
186d0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
186e0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a ppDb /*
186f0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
18700 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c handle */.);.SQL
18710 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
18720 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
18730 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
18740 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 ite3_open_v2(.
18750 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 const char *file
18760 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 name, /* Datab
18770 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 ase filename (UT
18780 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 F-8) */. sqlite
18790 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 3 **ppDb,
187a0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 /* OUT: SQLite
187b0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 db handle */.
187c0 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 int flags,
187d0 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 /* Flags
187e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
187f0 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a *zVfs /*
18800 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 Name of VFS mod
18810 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b ule to use */.);
18820 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
18830 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e : Error Codes An
18840 64 20 4d 65 73 73 61 67 65 73 20 7b 48 31 32 38 d Messages {H128
18850 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 00} <S60200>.**.
18860 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 ** The sqlite3_e
18870 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 rrcode() interfa
18880 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ce returns the n
18890 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 umeric [result c
188a0 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 ode] or.** [exte
188b0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
188c0 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 ] for the most r
188d0 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c ecent failed sql
188e0 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a ite3_* API call.
188f0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ** associated wi
18900 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 th a [database c
18910 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 onnection]. If a
18920 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 prior API call
18930 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 failed.** but th
18940 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 e most recent AP
18950 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 I call succeeded
18960 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c , the return val
18970 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 ue from.** sqlit
18980 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 e3_errcode() is
18990 75 6e 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20 undefined. The
189a0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
189b0 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e _errcode().** in
189c0 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 terface is the s
189d0 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 ame except that
189e0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e it always return
189f0 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e s the .** [exten
18a00 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d ded result code]
18a10 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e even when exten
18a20 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
18a30 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 are.** disabled
18a40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
18a50 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 te3_errmsg() and
18a60 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 sqlite3_errmsg1
18a70 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 6() return Engli
18a80 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 sh-language.** t
18a90 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 ext that describ
18aa0 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 es the error, as
18ab0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 either UTF-8 or
18ac0 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 UTF-16 respecti
18ad0 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 vely..** Memory
18ae0 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f to hold the erro
18af0 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 r message string
18b00 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 is managed inte
18b10 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 rnally..** The a
18b20 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 pplication does
18b30 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 not need to worr
18b40 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 y about freeing
18b50 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 the result..** H
18b60 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f owever, the erro
18b70 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 r string might b
18b80 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 e overwritten or
18b90 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a deallocated by.
18ba0 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 ** subsequent ca
18bb0 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c lls to other SQL
18bc0 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 ite interface fu
18bd0 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 nctions..**.** W
18be0 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a hen the serializ
18bf0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
18c00 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 de] is in use, i
18c10 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a t might be the.*
18c20 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 * case that a se
18c30 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 cond error occur
18c40 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 s on a separate
18c50 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 thread in betwee
18c60 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 n.** the time of
18c70 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 the first error
18c80 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f and the call to
18c90 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
18ca0 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 s..** When that
18cb0 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 happens, the sec
18cc0 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 ond error will b
18cd0 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 e reported since
18ce0 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 these.** interf
18cf0 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f aces always repo
18d00 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 rt the most rece
18d10 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 nt result. To a
18d20 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 void.** this, ea
18d30 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 ch thread can ob
18d40 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 tain exclusive u
18d50 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 se of the [datab
18d60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
18d70 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 D.** by invoking
18d80 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
18d90 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f enter]([sqlite3_
18da0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 db_mutex](D)) be
18db0 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a fore beginning.*
18dc0 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 * to use D and i
18dd0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 nvoking [sqlite3
18de0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 _mutex_leave]([s
18df0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d qlite3_db_mutex]
18e00 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c (D)) after.** al
18e10 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 l calls to the i
18e20 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 nterfaces listed
18e30 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 here are comple
18e40 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e ted..**.** If an
18e50 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 interface fails
18e60 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 with SQLITE_MIS
18e70 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 USE, that means
18e80 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a the interface.**
18e90 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 was invoked inc
18ea0 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 orrectly by the
18eb0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e application. In
18ec0 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a that case, the.
18ed0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e ** error code an
18ee0 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 d message may or
18ef0 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e may not be set.
18f00 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
18f10 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 38 30 31 5d nts:.** [H12801]
18f20 20 5b 48 31 32 38 30 32 5d 20 5b 48 31 32 38 30 [H12802] [H1280
18f30 33 5d 20 5b 48 31 32 38 30 37 5d 20 5b 48 31 32 3] [H12807] [H12
18f40 38 30 38 5d 20 5b 48 31 32 38 30 39 5d 0a 2a 2f 808] [H12809].*/
18f50 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
18f60 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
18f70 49 20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 I SQLITE_API int
18f80 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 sqlite3_errcode
18f90 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 (sqlite3 *db);.S
18fa0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
18fb0 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
18fc0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
18fd0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
18fe0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 errcode(sqlite3
18ff0 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 *db);.SQLITE_API
19000 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
19010 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
19020 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 I const char *sq
19030 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c lite3_errmsg(sql
19040 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 ite3*);.SQLITE_A
19050 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
19060 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
19070 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
19080 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
19090 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
190a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c ** CAPI3REF: SQL
190b0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 Statement Objec
190c0 74 20 7b 48 31 33 30 30 30 7d 20 3c 48 31 33 30 t {H13000} <H130
190d0 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 10>.** KEYWORDS:
190e0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 {prepared state
190f0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 ment} {prepared
19100 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a statements}.**.*
19110 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
19120 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 this object rep
19130 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 resents a single
19140 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a SQL statement..
19150 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 ** This object i
19160 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 s variously know
19170 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 n as a "prepared
19180 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 statement" or a
19190 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 .** "compiled SQ
191a0 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 L statement" or
191b0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 simply as a "sta
191c0 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 tement"..**.** T
191d0 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 he life of a sta
191e0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f tement object go
191f0 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b es something lik
19200 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f e this:.**.** <o
19210 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 l>.** <li> Creat
19220 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 e the object usi
19230 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ng [sqlite3_prep
19240 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 are_v2()] or a r
19250 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 elated.** f
19260 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e unction..** <li>
19270 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 Bind values to
19280 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 [host parameters
19290 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 ] using the sqli
192a0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 te3_bind_*().**
192b0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e interfaces.
192c0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 .** <li> Run the
192d0 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 SQL by calling
192e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
192f0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
19300 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 es..** <li> Rese
19310 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 t the statement
19320 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 using [sqlite3_r
19330 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 eset()] then go
19340 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 back.** to
19350 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 step 2. Do this
19360 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 zero or more ti
19370 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 mes..** <li> Des
19380 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 troy the object
19390 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
193a0 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c inalize()]..** <
193b0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 /ol>.**.** Refer
193c0 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f to documentatio
193d0 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 n on individual
193e0 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f methods above fo
193f0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 r additional.**
19400 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a information..*/.
19410 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
19420 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 qlite3_stmt sqli
19430 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a te3_stmt;../*.**
19440 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 CAPI3REF: Run-t
19450 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48 31 32 37 ime Limits {H127
19460 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a 60} <S20600>.**.
19470 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
19480 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a e allows the siz
19490 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e e of various con
194a0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 structs to be li
194b0 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f mited.** on a co
194c0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e nnection by conn
194d0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 ection basis. T
194e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
194f0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 er is the.** [da
19500 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
19510 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 n] whose limit i
19520 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 s to be set or q
19530 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 ueried. The.**
19540 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
19550 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b is one of the [
19560 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 limit categories
19570 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a ] that define a.
19580 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 ** class of cons
19590 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a tructs to be siz
195a0 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 e limited. The
195b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
195c0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 is the.** new li
195d0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e mit for that con
195e0 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e struct. The fun
195f0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
19600 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a e old limit..**.
19610 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20 6c 69 ** If the new li
19620 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 mit is a negativ
19630 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 e number, the li
19640 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 mit is unchanged
19650 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d ..** For the lim
19660 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53 it category of S
19670 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 QLITE_LIMIT_XYZ
19680 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b there is a .** [
19690 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 limits | hard up
196a0 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 per bound].** se
196b0 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 t by a compile-t
196c0 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65 73 73 ime C preprocess
196d0 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 0a or macro named .
196e0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c ** [limits | SQL
196f0 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a ITE_MAX_XYZ]..**
19700 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 (The "_LIMIT_"
19710 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 in the name is c
19720 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f hanged to "_MAX_
19730 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 ".).** Attempts
19740 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 to increase a li
19750 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 mit above its ha
19760 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 rd upper bound a
19770 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 re.** silently t
19780 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 runcated to the
19790 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d 69 74 hard upper limit
197a0 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 ..**.** Run time
197b0 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 limits are inte
197c0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 nded for use in
197d0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 applications tha
197e0 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 t manage.** both
197f0 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 their own inter
19800 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 nal database and
19810 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 also databases
19820 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c that are control
19830 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 led.** by untrus
19840 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 ted external sou
19850 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c rces. An exampl
19860 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 e application mi
19870 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 ght be a.** web
19880 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 browser that has
19890 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 its own databas
198a0 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 es for storing h
198b0 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 istory and.** se
198c0 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 parate databases
198d0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a controlled by J
198e0 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 avaScript applic
198f0 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 ations downloade
19900 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 d.** off the Int
19910 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 ernet. The inte
19920 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 rnal databases c
19930 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a an be given the.
19940 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c ** large, defaul
19950 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 t limits. Datab
19960 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 ases managed by
19970 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 external sources
19980 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e can.** be given
19990 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 much smaller li
199a0 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f mits designed to
199b0 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 prevent a denia
199c0 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 l of service.**
199d0 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 attack. Develop
199e0 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 ers might also w
199f0 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b ant to use the [
19a00 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
19a10 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 orizer()].** int
19a20 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 erface to furthe
19a30 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 r control untrus
19a40 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 ted SQL. The si
19a50 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 ze of the databa
19a60 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 se.** created by
19a70 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 an untrusted sc
19a80 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 ript can be cont
19a90 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a ained using the.
19aa0 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 ** [max_page_cou
19ab0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a nt] [PRAGMA]..**
19ac0 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 .** New run-time
19ad0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 limit categorie
19ae0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
19af0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
19b00 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 s..**.** Require
19b10 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 36 ments:.** [H1276
19b20 32 5d 20 5b 48 31 32 37 36 36 5d 20 5b 48 31 32 2] [H12766] [H12
19b30 37 36 39 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 769].*/.SQLITE_A
19b40 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
19b50 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
19b60 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
19b70 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 limit(sqlite3*,
19b80 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 int id, int newV
19b90 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 al);../*.** CAPI
19ba0 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 3REF: Run-Time L
19bb0 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 20 imit Categories
19bc0 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36 30 {H12790} <H12760
19bd0 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b >.** KEYWORDS: {
19be0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 limit category}
19bf0 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 {limit categorie
19c00 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 s}.**.** These c
19c10 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 onstants define
19c20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 various performa
19c30 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 nce limits.** th
19c40 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 at can be lowere
19c50 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 d at run-time us
19c60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d ing [sqlite3_lim
19c70 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 it()]..** The sy
19c80 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 nopsis of the me
19c90 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 anings of the va
19ca0 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 rious limits is
19cb0 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 shown below..**
19cc0 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 Additional infor
19cd0 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 mation is availa
19ce0 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c ble at [limits |
19cf0 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 Limits in SQLit
19d00 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a e]..**.** <dl>.*
19d10 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d * <dt>SQLITE_LIM
19d20 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a IT_LENGTH</dt>.*
19d30 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
19d40 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 m size of any st
19d50 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 ring or BLOB or
19d60 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a table row.<dd>.*
19d70 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
19d80 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 LIMIT_SQL_LENGTH
19d90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
19da0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 maximum length
19db0 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d of an SQL statem
19dc0 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ent.</dd>.**.**
19dd0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
19de0 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 _COLUMN</dt>.**
19df0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
19e00 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
19e10 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 s in a table def
19e20 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 inition or in th
19e30 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 e.** result set
19e40 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 of a [SELECT] or
19e50 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d the maximum num
19e60 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
19e70 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 n an index.** or
19e80 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 in an ORDER BY
19e90 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 or GROUP BY clau
19ea0 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c se.</dd>.**.** <
19eb0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
19ec0 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a EXPR_DEPTH</dt>.
19ed0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
19ee0 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 um depth of the
19ef0 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e parse tree on an
19f00 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 y expression.</d
19f10 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
19f20 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 ITE_LIMIT_COMPOU
19f30 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a ND_SELECT</dt>.*
19f40 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
19f50 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d m number of term
19f60 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 s in a compound
19f70 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 SELECT statement
19f80 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
19f90 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 >SQLITE_LIMIT_VD
19fa0 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 BE_OP</dt>.** <d
19fb0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
19fc0 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 mber of instruct
19fd0 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 ions in a virtua
19fe0 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 l machine progra
19ff0 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 m.** used to imp
1a000 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 lement an SQL st
1a010 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a atement.</dd>.**
1a020 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c .** <dt>SQLITE_L
1a030 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
1a040 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 G</dt>.** <dd>Th
1a050 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
1a060 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e of arguments on
1a070 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 a function.</dd
1a080 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
1a090 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 TE_LIMIT_ATTACHE
1a0a0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
1a0b0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
1a0c0 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 of [ATTACH | at
1a0d0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 tached databases
1a0e0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 ].</dd>.**.** <d
1a0f0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c t>SQLITE_LIMIT_L
1a100 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
1a110 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
1a120 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
1a130 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e h of the pattern
1a140 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
1a150 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 [LIKE] or.** [G
1a160 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c LOB] operators.<
1a170 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
1a180 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
1a190 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e ABLE_NUMBER</dt>
1a1a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
1a1b0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 mum number of va
1a1c0 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 riables in an SQ
1a1d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 L statement that
1a1e0 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 can.** be bound
1a1f0 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a .</dd>.** </dl>.
1a200 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1a210 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 E_LIMIT_LENGTH
1a220 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1a230 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
1a240 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e TE_LIMIT_SQL_LEN
1a250 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 GTH
1a260 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
1a270 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e ITE_LIMIT_COLUMN
1a280 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1a290 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
1a2a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
1a2b0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 DEPTH
1a2c0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
1a2d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 QLITE_LIMIT_COMP
1a2e0 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 OUND_SELECT
1a2f0 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 4.#define
1a300 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 SQLITE_LIMIT_VDB
1a310 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 E_OP
1a320 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 5.#define
1a330 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 SQLITE_LIMIT_FU
1a340 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 NCTION_ARG
1a350 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 6.#defin
1a360 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 e SQLITE_LIMIT_A
1a370 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 TTACHED
1a380 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 7.#defi
1a390 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
1a3a0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e LIKE_PATTERN_LEN
1a3b0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 GTH 8.#def
1a3c0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
1a3d0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
1a3e0 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 9../*
1a3f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
1a400 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 mpiling An SQL S
1a410 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 tatement {H13010
1a420 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 } <S10000>.** KE
1a430 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 YWORDS: {SQL sta
1a440 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d tement compiler}
1a450 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 .**.** To execut
1a460 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 e an SQL query,
1a470 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 it must first be
1a480 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 compiled into a
1a490 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 byte-code.** pr
1a4a0 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 ogram using one
1a4b0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
1a4c0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 s..**.** The fir
1a4d0 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 st argument, "db
1a4e0 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 ", is a [databas
1a4f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 e connection] ob
1a500 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a tained from a.**
1a510 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 prior successfu
1a520 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
1a530 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
1a540 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 ite3_open_v2()]
1a550 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f or.** [sqlite3_o
1a560 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 pen16()]. The d
1a570 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1a580 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 on must not have
1a590 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a been closed..**
1a5a0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 .** The second a
1a5b0 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c rgument, "zSql",
1a5c0 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e is the statemen
1a5d0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 t to be compiled
1a5e0 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 , encoded.** as
1a5f0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
1a600 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c UTF-16. The sql
1a610 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 ite3_prepare() a
1a620 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
1a630 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 re_v2().** inter
1a640 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c faces use UTF-8,
1a650 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
1a660 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c pare16() and sql
1a670 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
1a680 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 2().** use UTF-1
1a690 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6..**.** If the
1a6a0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 nByte argument i
1a6b0 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f s less than zero
1a6c0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 , then zSql is r
1a6d0 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a ead up to the.**
1a6e0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d first zero term
1a6f0 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 inator. If nByte
1a700 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
1a710 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 , then it is the
1a720 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 maximum.** numb
1a730 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 er of bytes rea
1a740 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 d from zSql. Wh
1a750 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d en nByte is non-
1a760 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a negative, the.**
1a770 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 zSql string end
1a780 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 s at either the
1a790 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 first '\000' or
1a7a0 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 '\u0000' charact
1a7b0 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 er or.** the nBy
1a7c0 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 te-th byte, whic
1a7d0 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 hever comes firs
1a7e0 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 t. If the caller
1a7f0 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 knows.** that t
1a800 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 he supplied stri
1a810 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e ng is nul-termin
1a820 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 ated, then there
1a830 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 is a small.** p
1a840 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e erformance advan
1a850 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 tage to be gaine
1a860 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 d by passing an
1a870 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 nByte parameter
1a880 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c that.** is equal
1a890 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f to the number o
1a8a0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 f bytes in the i
1a8b0 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 nput string <i>i
1a8c0 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 ncluding</i>.**
1a8d0 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 the nul-terminat
1a8e0 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 or bytes..**.**
1a8f0 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 If pzTail is not
1a900 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 NULL then *pzTa
1a910 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f il is made to po
1a920 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 int to the first
1a930 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 byte.** past th
1a940 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 e end of the fir
1a950 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 st SQL statement
1a960 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 in zSql. These
1a970 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a routines only.*
1a980 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 * compile the fi
1a990 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e rst statement in
1a9a0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 zSql, so *pzTai
1a9b0 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 l is left pointi
1a9c0 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 ng to.** what re
1a9d0 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 mains uncompiled
1a9e0 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 ..**.** *ppStmt
1a9f0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 is left pointing
1aa00 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b to a compiled [
1aa10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1aa20 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a nt] that can be.
1aa30 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e ** executed usin
1aa40 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 g [sqlite3_step(
1aa50 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 )]. If there is
1aa60 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 an error, *ppSt
1aa70 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 mt is set.** to
1aa80 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e NULL. If the in
1aa90 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e put text contain
1aaa0 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 s no SQL (if the
1aab0 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 input is an emp
1aac0 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 ty.** string or
1aad0 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 a comment) then
1aae0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 *ppStmt is set t
1aaf0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 o NULL..** The c
1ab00 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 alling procedure
1ab10 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
1ab20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 for deleting the
1ab30 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c compiled.** SQL
1ab40 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 statement using
1ab50 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
1ab60 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 ze()] after it h
1ab70 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
1ab80 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d it..** ppStmt m
1ab90 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a ay not be NULL..
1aba0 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 **.** On success
1abb0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 , [SQLITE_OK] is
1abc0 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 returned, other
1abd0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 wise an [error c
1abe0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ode] is returned
1abf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
1ac00 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1ac10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
1ac20 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 pare16_v2() inte
1ac30 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 rfaces are.** re
1ac40 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c commended for al
1ac50 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 l new programs.
1ac60 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e The two older in
1ac70 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 terfaces are ret
1ac80 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 ained.** for bac
1ac90 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
1aca0 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 lity, but their
1acb0 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 use is discourag
1acc0 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 ed..** In the "v
1acd0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 2" interfaces, t
1ace0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 he prepared stat
1acf0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 ement.** that is
1ad00 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b returned (the [
1ad10 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 sqlite3_stmt] ob
1ad20 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 ject) contains a
1ad30 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 copy of the.**
1ad40 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 original SQL tex
1ad50 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 t. This causes t
1ad60 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 he [sqlite3_step
1ad70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f ()] interface to
1ad80 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 .** behave a dif
1ad90 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 ferently in two
1ada0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e ways:.**.** <ol>
1adb0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 .** <li>.** If t
1adc0 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 he database sche
1add0 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 ma changes, inst
1ade0 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 ead of returning
1adf0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
1ae00 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 as it.** always
1ae10 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 used to do, [sq
1ae20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
1ae30 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ll automatically
1ae40 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 recompile the S
1ae50 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 QL.** statement
1ae60 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 and try to run i
1ae70 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 t again. If the
1ae80 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e schema has chan
1ae90 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 ged in.** a way
1aea0 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 that makes the s
1aeb0 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 tatement no long
1aec0 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 er valid, [sqlit
1aed0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 e3_step()] will
1aee0 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 still.** return
1aef0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e [SQLITE_SCHEMA].
1af00 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 But unlike the
1af10 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 legacy behavior
1af20 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 , [SQLITE_SCHEMA
1af30 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 ] is.** now a fa
1af40 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c tal error. Call
1af50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ing [sqlite3_pre
1af60 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e pare_v2()] again
1af70 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 will not make t
1af80 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 he.** error go a
1af90 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 way. Note: use
1afa0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
1afb0 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 )] to find the t
1afc0 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 ext.** of the pa
1afd0 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 rsing error that
1afe0 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b results in an [
1aff0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 SQLITE_SCHEMA] r
1b000 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a eturn..** </li>.
1b010 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 **.** <li>.** Wh
1b020 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 en an error occu
1b030 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 rs, [sqlite3_ste
1b040 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e p()] will return
1b050 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 one of the deta
1b060 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 iled.** [error c
1b070 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 odes] or [extend
1b080 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e ed error codes].
1b090 20 20 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 The legacy beh
1b0a0 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a avior was that.*
1b0b0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 * [sqlite3_step(
1b0c0 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 )] would only re
1b0d0 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b turn a generic [
1b0e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 SQLITE_ERROR] re
1b0f0 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 sult code.** and
1b100 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 you would have
1b110 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 to make a second
1b120 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
1b130 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 3_reset()] in or
1b140 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 der.** to find t
1b150 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 he underlying ca
1b160 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c use of the probl
1b170 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 em. With the "v2
1b180 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 " prepare.** int
1b190 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 erfaces, the und
1b1a0 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 erlying reason f
1b1b0 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 or the error is
1b1c0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 returned immedia
1b1d0 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a tely..** </li>.*
1b1e0 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 * </ol>.**.** Re
1b1f0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
1b200 48 31 33 30 31 31 5d 20 5b 48 31 33 30 31 32 5d H13011] [H13012]
1b210 20 5b 48 31 33 30 31 33 5d 20 5b 48 31 33 30 31 [H13013] [H1301
1b220 34 5d 20 5b 48 31 33 30 31 35 5d 20 5b 48 31 33 4] [H13015] [H13
1b230 30 31 36 5d 20 5b 48 31 33 30 31 39 5d 20 5b 48 016] [H13019] [H
1b240 31 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a 53 51 4c 13021].**.*/.SQL
1b250 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
1b260 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
1b270 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
1b280 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 ite3_prepare(.
1b290 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
1b2a0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
1b2b0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
1b2c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c const char *zSql
1b2d0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 , /* SQL s
1b2e0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 tatement, UTF-8
1b2f0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 encoded */. int
1b300 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 nByte,
1b310 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
1b320 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 length of zSql i
1b330 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 n bytes. */. sq
1b340 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 lite3_stmt **ppS
1b350 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 tmt, /* OUT: St
1b360 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a atement handle *
1b370 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
1b380 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f *pzTail /* O
1b390 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 UT: Pointer to u
1b3a0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 nused portion of
1b3b0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 zSql */.);.SQLI
1b3c0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
1b3d0 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
1b3e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
1b3f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a te3_prepare_v2(.
1b400 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
1b410 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
1b420 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
1b430 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 const char *zS
1b440 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
1b450 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
1b460 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 8 encoded */. i
1b470 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
1b480 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
1b490 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
1b4a0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
1b4b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
1b4c0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
1b4d0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
1b4e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
1b4f0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
1b500 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
1b510 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
1b520 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 of zSql */.);.SQ
1b530 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
1b540 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
1b550 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
1b560 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
1b570 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
1b580 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
1b590 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f tabase handle */
1b5a0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a . const void *z
1b5b0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 Sql, /* SQ
1b5c0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 L statement, UTF
1b5d0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 -16 encoded */.
1b5e0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 int nByte,
1b5f0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
1b600 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 mum length of zS
1b610 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a ql in bytes. */.
1b620 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a sqlite3_stmt *
1b630 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 *ppStmt, /* OUT
1b640 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 : Statement hand
1b650 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
1b660 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 id **pzTail
1b670 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 /* OUT: Pointer
1b680 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f to unused portio
1b690 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a n of zSql */.);.
1b6a0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
1b6b0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
1b6c0 20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 SQLITE_API int
1b6d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
1b6e0 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 6_v2(. sqlite3
1b6f0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
1b700 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
1b710 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
1b720 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 id *zSql,
1b730 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
1b740 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 , UTF-16 encoded
1b750 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
1b760 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
1b770 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
1b780 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
1b790 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
1b7a0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
1b7b0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
1b7c0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
1b7d0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c st void **pzTail
1b7e0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
1b7f0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
1b800 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
1b810 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
1b820 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 3REF: Retrieving
1b830 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b Statement SQL {
1b840 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30 3e H13100} <H13000>
1b850 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
1b860 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
1b870 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 d to retrieve a
1b880 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 saved copy of th
1b890 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 e original.** SQ
1b8a0 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 L text used to c
1b8b0 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 reate a [prepare
1b8c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 d statement] if
1b8d0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 that statement w
1b8e0 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 as.** compiled u
1b8f0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c sing either [sql
1b900 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1b910 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
1b920 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a repare16_v2()]..
1b930 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
1b940 74 73 3a 0a 2a 2a 20 5b 48 31 33 31 30 31 5d 20 ts:.** [H13101]
1b950 5b 48 31 33 31 30 32 5d 20 5b 48 31 33 31 30 33 [H13102] [H13103
1b960 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
1b970 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
1b980 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
1b990 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
1b9a0 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 ite3_sql(sqlite3
1b9b0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
1b9c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1b9d0 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 Dynamically Type
1b9e0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b d Value Object {
1b9f0 48 31 35 30 30 30 7d 20 3c 53 32 30 32 30 30 3e H15000} <S20200>
1ba00 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 .** KEYWORDS: {p
1ba10 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
1ba20 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 _value} {unprote
1ba30 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
1ba40 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ue}.**.** SQLite
1ba50 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 uses the sqlite
1ba60 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 3_value object t
1ba70 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 o represent all
1ba80 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 values.** that c
1ba90 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 an be stored in
1baa0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 a database table
1bab0 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 . SQLite uses dy
1bac0 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 namic typing.**
1bad0 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 for the values i
1bae0 74 20 73 74 6f 72 65 73 2e 20 56 61 6c 75 65 73 t stores. Values
1baf0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 stored in sqlit
1bb00 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
1bb10 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 .** can be integ
1bb20 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f ers, floating po
1bb30 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 int values, stri
1bb40 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e ngs, BLOBs, or N
1bb50 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 ULL..**.** An sq
1bb60 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
1bb70 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 ct may be either
1bb80 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 "protected" or
1bb90 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a "unprotected"..*
1bba0 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 * Some interface
1bbb0 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 s require a prot
1bbc0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
1bbd0 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 lue. Other inte
1bbe0 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 rfaces.** will a
1bbf0 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 ccept either a p
1bc00 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 rotected or an u
1bc10 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
1bc20 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 e3_value..** Eve
1bc30 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 ry interface tha
1bc40 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 t accepts sqlite
1bc50 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 3_value argument
1bc60 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 s specifies.** w
1bc70 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 hether or not it
1bc80 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 requires a prot
1bc90 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
1bca0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 lue..**.** The t
1bcb0 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 erms "protected"
1bcc0 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 and "unprotecte
1bcd0 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 d" refer to whet
1bce0 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 her or not.** a
1bcf0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 mutex is held.
1bd00 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 A internal mutex
1bd10 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 is held for a p
1bd20 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
1bd30 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
1bd40 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 but no mutex is
1bd50 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 held for an unp
1bd60 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
1bd70 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
1bd80 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 . If SQLite is
1bd90 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 compiled to be s
1bda0 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a ingle-threaded.*
1bdb0 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f * (with [SQLITE_
1bdc0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e THREADSAFE=0] an
1bdd0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f d with [sqlite3_
1bde0 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 threadsafe()] re
1bdf0 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 turning 0).** or
1be00 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 if SQLite is ru
1be10 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 n in one of redu
1be20 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 ced mutex modes
1be30 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
1be40 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d IG_SINGLETHREAD]
1be50 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 or [SQLITE_CONF
1be60 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a IG_MULTITHREAD].
1be70 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 ** then there is
1be80 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 no distinction
1be90 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 between protecte
1bea0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 d and unprotecte
1beb0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
1bec0 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 ue objects and t
1bed0 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 hey can be used
1bee0 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e interchangeably.
1bef0 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f However,.** fo
1bf00 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 r maximum code p
1bf10 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 ortability it is
1bf20 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 recommended tha
1bf30 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a t applications.*
1bf40 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 * still make the
1bf50 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 distinction bet
1bf60 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72 6f ween between pro
1bf70 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f tected and unpro
1bf80 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
1bf90 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 3_value objects
1bfa0 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 even when not st
1bfb0 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e rictly required.
1bfc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
1bfd0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
1bfe0 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 that are passed
1bff0 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 as parameters i
1c000 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 nto the.** imple
1c010 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 mentation of [ap
1c020 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
1c030 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d d SQL functions]
1c040 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a are protected..
1c050 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 ** The sqlite3_v
1c060 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 alue object retu
1c070 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 rned by.** [sqli
1c080 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 te3_column_value
1c090 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 ()] is unprotect
1c0a0 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 ed..** Unprotect
1c0b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
1c0c0 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c objects may onl
1c0d0 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a y be used with.*
1c0e0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c * [sqlite3_resul
1c0f0 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b t_value()] and [
1c100 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c sqlite3_bind_val
1c110 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 ue()]..** The [s
1c120 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f qlite3_value_blo
1c130 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 b | sqlite3_valu
1c140 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 e_type()] family
1c150 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 of.** interface
1c160 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 s require protec
1c170 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
1c180 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 e objects..*/.ty
1c190 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d pedef struct Mem
1c1a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a sqlite3_value;.
1c1b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1c1c0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f SQL Function Co
1c1d0 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 48 31 ntext Object {H1
1c1e0 36 30 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 6001} <S20200>.*
1c1f0 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 *.** The context
1c200 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c in which an SQL
1c210 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 function execut
1c220 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 es is stored in
1c230 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f an.** sqlite3_co
1c240 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 ntext object. A
1c250 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 pointer to an s
1c260 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f qlite3_context o
1c270 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 bject.** is alwa
1c280 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 ys first paramet
1c290 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 er to [applicati
1c2a0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
1c2b0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 unctions]..** Th
1c2c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
1c2d0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
1c2e0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
1c2f0 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 n will pass this
1c300 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f .** pointer thro
1c310 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 ugh into calls t
1c320 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c o [sqlite3_resul
1c330 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f t_int | sqlite3_
1c340 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 result()],.** [s
1c350 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
1c360 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 _context()], [sq
1c370 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 lite3_user_data(
1c380 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
1c390 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c context_db_handl
1c3a0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 e()], [sqlite3_g
1c3b0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a et_auxdata()],.*
1c3c0 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 * and/or [sqlite
1c3d0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 3_set_auxdata()]
1c3e0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
1c3f0 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 uct sqlite3_cont
1c400 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ext sqlite3_cont
1c410 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ext;../*.** CAPI
1c420 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 3REF: Binding Va
1c430 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 lues To Prepared
1c440 20 53 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 33 Statements {H13
1c450 35 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 500} <S70300>.**
1c460 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 KEYWORDS: {host
1c470 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 parameter} {hos
1c480 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 t parameters} {h
1c490 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 ost parameter na
1c4a0 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a me}.** KEYWORDS:
1c4b0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d {SQL parameter}
1c4c0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 {SQL parameters
1c4d0 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e } {parameter bin
1c4e0 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 ding}.**.** In t
1c4f0 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 he SQL strings i
1c500 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 nput to [sqlite3
1c510 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
1c520 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c nd its variants,
1c530 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 .** literals may
1c540 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 be replaced by
1c550 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e a [parameter] in
1c560 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 66 6f one of these fo
1c570 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a rms:.**.** <ul>.
1c580 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c ** <li> ?.** <l
1c590 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e i> ?NNN.** <li>
1c5a0 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 :VVV.** <li>
1c5b0 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 @VVV.** <li> $V
1c5c0 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a VV.** </ul>.**.*
1c5d0 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74 * In the paramet
1c5e0 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 er forms shown a
1c5f0 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 bove NNN is an i
1c600 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a nteger literal,.
1c610 2a 2a 20 61 6e 64 20 56 56 56 20 69 73 20 61 6e ** and VVV is an
1c620 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 alpha-numeric p
1c630 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20 54 arameter name. T
1c640 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 he values of the
1c650 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 se.** parameters
1c660 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 (also called "h
1c670 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 ost parameter na
1c680 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 mes" or "SQL par
1c690 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e ameters").** can
1c6a0 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 be set using th
1c6b0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
1c6c0 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 () routines defi
1c6d0 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 ned here..**.**
1c6e0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
1c6f0 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 nt to the sqlite
1c700 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
1c710 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a nes is always.**
1c720 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
1c730 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d e [sqlite3_stmt]
1c740 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 object returned
1c750 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 from.** [sqlite
1c760 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
1c770 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e or its variants.
1c780 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e .**.** The secon
1c790 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
1c7a0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 e index of the S
1c7b0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 QL parameter to
1c7c0 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 6c be set..** The l
1c7d0 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 eftmost SQL para
1c7e0 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 meter has an ind
1c7f0 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 ex of 1. When t
1c800 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a he same named.**
1c810 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 SQL parameter i
1c820 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e s used more than
1c830 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e once, second an
1c840 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 d subsequent.**
1c850 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 occurrences have
1c860 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 the same index
1c870 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 as the first occ
1c880 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 urrence..** The
1c890 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 index for named
1c8a0 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 parameters can b
1c8b0 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e e looked up usin
1c8c0 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 g the.** [sqlite
1c8d0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
1c8e0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 _index()] API if
1c8f0 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 desired. The i
1c900 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e ndex.** for "?NN
1c910 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 N" parameters is
1c920 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e the value of NN
1c930 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 N..** The NNN va
1c940 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 lue must be betw
1c950 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 een 1 and the [s
1c960 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a qlite3_limit()].
1c970 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 ** parameter [SQ
1c980 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 LITE_LIMIT_VARIA
1c990 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 BLE_NUMBER] (def
1c9a0 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 ault value: 999)
1c9b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 ..**.** The thir
1c9c0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
1c9d0 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 e value to bind
1c9e0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 to the parameter
1c9f0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 ..**.** In those
1ca00 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 routines that h
1ca10 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 ave a fourth arg
1ca20 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 ument, its value
1ca30 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 is the.** numbe
1ca40 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
1ca50 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f e parameter. To
1ca60 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 be clear: the v
1ca70 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e alue is the.** n
1ca80 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 umber of <u>byte
1ca90 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c s</u> in the val
1caa0 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 ue, not the numb
1cab0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
1cac0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 ..** If the four
1cad0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
1cae0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 negative, the le
1caf0 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 ngth of the stri
1cb00 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d ng is.** the num
1cb10 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 ber of bytes up
1cb20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 to the first zer
1cb30 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a o terminator..**
1cb40 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 72 .** The fifth ar
1cb50 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
1cb60 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 3_bind_blob(), s
1cb70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
1cb80 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 (), and.** sqlit
1cb90 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 e3_bind_text16()
1cba0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 is a destructor
1cbb0 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 used to dispose
1cbc0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a of the BLOB or.
1cbd0 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 ** string after
1cbe0 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 SQLite has finis
1cbf0 68 65 64 20 77 69 74 68 20 69 74 2e 20 49 66 20 hed with it. If
1cc00 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 the fifth argume
1cc10 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 nt is.** the spe
1cc20 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 cial value [SQLI
1cc30 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e TE_STATIC], then
1cc40 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 SQLite assumes
1cc50 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f that the.** info
1cc60 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 rmation is in st
1cc70 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 atic, unmanaged
1cc80 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e space and does n
1cc90 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 ot need to be fr
1cca0 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 eed..** If the f
1ccb0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 ifth argument ha
1ccc0 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c s the value [SQL
1ccd0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 ITE_TRANSIENT],
1cce0 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d then.** SQLite m
1ccf0 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 akes its own pri
1cd00 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 vate copy of the
1cd10 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c data immediatel
1cd20 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 y, before.** the
1cd30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
1cd40 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
1cd50 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c s..**.** The sql
1cd60 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c ite3_bind_zerobl
1cd70 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e ob() routine bin
1cd80 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e ds a BLOB of len
1cd90 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 gth N that.** is
1cda0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 filled with zer
1cdb0 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 oes. A zeroblob
1cdc0 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d uses a fixed am
1cdd0 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a ount of memory.*
1cde0 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 * (just an integ
1cdf0 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 er to hold its s
1ce00 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 ize) while it is
1ce10 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 being processed
1ce20 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 ..** Zeroblobs a
1ce30 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 re intended to s
1ce40 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c erve as placehol
1ce50 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 ders for BLOBs w
1ce60 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 hose.** content
1ce70 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e is later written
1ce80 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
1ce90 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 e3_blob_open | i
1cea0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 ncremental BLOB
1ceb0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a I/O] routines..*
1cec0 2a 20 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c * A negative val
1ced0 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 ue for the zerob
1cee0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 lob results in a
1cef0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f zero-length BLO
1cf00 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c B..**.** The sql
1cf10 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f ite3_bind_*() ro
1cf20 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 utines must be c
1cf30 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b alled after.** [
1cf40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1cf50 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 v2()] (and its v
1cf60 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c ariants) or [sql
1cf70 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e ite3_reset()] an
1cf80 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c d.** before [sql
1cf90 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a ite3_step()]..**
1cfa0 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f Bindings are no
1cfb0 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 t cleared by the
1cfc0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
1cfd0 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 )] routine..** U
1cfe0 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 nbound parameter
1cff0 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 s are interprete
1d000 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a d as NULL..**.**
1d010 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
1d020 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f return [SQLITE_O
1d030 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 K] on success or
1d040 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 an error code i
1d050 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f f.** anything go
1d060 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 es wrong. [SQLI
1d070 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 TE_RANGE] is ret
1d080 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 urned if the par
1d090 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 ameter.** index
1d0a0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e is out of range.
1d0b0 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d [SQLITE_NOMEM]
1d0c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 is returned if
1d0d0 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a malloc() fails..
1d0e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 ** [SQLITE_MISUS
1d0f0 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 E] might be retu
1d100 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 6f rned if these ro
1d110 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 utines are calle
1d120 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 d on a.** virtua
1d130 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 l machine that i
1d140 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 s the wrong stat
1d150 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 e or which has a
1d160 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 lready been fina
1d170 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 lized..** Detect
1d180 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73 ion of misuse is
1d190 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 unreliable. Ap
1d1a0 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c plications shoul
1d1b0 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 d not depend.**
1d1c0 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 on SQLITE_MISUSE
1d1d0 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 returns. SQLIT
1d1e0 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65 E_MISUSE is inte
1d1f0 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 nded to indicate
1d200 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 a.** a logic er
1d210 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69 ror in the appli
1d220 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 cation. Future
1d230 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
1d240 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 te might.** pani
1d250 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 65 c rather than re
1d260 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 turn SQLITE_MISU
1d270 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c SE..**.** See al
1d280 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
1d290 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
1d2a0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 t()],.** [sqlite
1d2b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
1d2c0 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 _name()], and [s
1d2d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1d2e0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
1d2f0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
1d300 74 73 3a 0a 2a 2a 20 5b 48 31 33 35 30 36 5d 20 ts:.** [H13506]
1d310 5b 48 31 33 35 30 39 5d 20 5b 48 31 33 35 31 32 [H13509] [H13512
1d320 5d 20 5b 48 31 33 35 31 35 5d 20 5b 48 31 33 35 ] [H13515] [H135
1d330 31 38 5d 20 5b 48 31 33 35 32 31 5d 20 5b 48 31 18] [H13521] [H1
1d340 33 35 32 34 5d 20 5b 48 31 33 35 32 37 5d 0a 2a 3524] [H13527].*
1d350 2a 20 5b 48 31 33 35 33 30 5d 20 5b 48 31 33 35 * [H13530] [H135
1d360 33 33 5d 20 5b 48 31 33 35 33 36 5d 20 5b 48 31 33] [H13536] [H1
1d370 33 35 33 39 5d 20 5b 48 31 33 35 34 32 5d 20 5b 3539] [H13542] [
1d380 48 31 33 35 34 35 5d 20 5b 48 31 33 35 34 38 5d H13545] [H13548]
1d390 20 5b 48 31 33 35 35 31 5d 0a 2a 2a 0a 2a 2f 0a [H13551].**.*/.
1d3a0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
1d3b0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
1d3c0 20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 SQLITE_API int
1d3d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
1d3e0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c b(sqlite3_stmt*,
1d3f0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 int, const void
1d400 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a *, int n, void(*
1d410 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
1d420 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
1d430 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
1d440 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
1d450 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 e3_bind_double(s
1d460 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
1d470 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 t, double);.SQLI
1d480 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
1d490 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
1d4a0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
1d4b0 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c te3_bind_int(sql
1d4c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
1d4d0 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 int);.SQLITE_AP
1d4e0 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
1d4f0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
1d500 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
1d510 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 ind_int64(sqlite
1d520 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 3_stmt*, int, sq
1d530 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 lite3_int64);.SQ
1d540 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
1d550 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
1d560 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
1d570 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 lite3_bind_null(
1d580 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
1d590 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
1d5a0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
1d5b0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
1d5c0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
1d5d0 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 d_text(sqlite3_s
1d5e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
1d5f0 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 char*, int n, v
1d600 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
1d610 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
1d620 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
1d630 20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 SQLITE_API int
1d640 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
1d650 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t16(sqlite3_stmt
1d660 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f *, int, const vo
1d670 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a id*, int, void(*
1d680 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
1d690 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
1d6a0 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
1d6b0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
1d6c0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 e3_bind_value(sq
1d6d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
1d6e0 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f , const sqlite3_
1d6f0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
1d700 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
1d710 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
1d720 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
1d730 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 _bind_zeroblob(s
1d740 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
1d750 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a t, int n);../*.*
1d760 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
1d770 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 er Of SQL Parame
1d780 74 65 72 73 20 7b 48 31 33 36 30 30 7d 20 3c 53 ters {H13600} <S
1d790 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 70300>.**.** Thi
1d7a0 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 s routine can be
1d7b0 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 used to find th
1d7c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c e number of [SQL
1d7d0 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 parameters].**
1d7e0 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 in a [prepared s
1d7f0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 tatement]. SQL
1d800 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 parameters are t
1d810 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 okens of the.**
1d820 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 form "?", "?NNN"
1d830 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 , ":AAA", "$AAA"
1d840 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 , or "@AAA" that
1d850 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 serve as.** pla
1d860 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 ceholders for va
1d870 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 lues that are [s
1d880 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
1d890 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 | bound].** to
1d8a0 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 the parameters a
1d8b0 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a t a later time..
1d8c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
1d8d0 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 ne actually retu
1d8e0 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 rns the index of
1d8f0 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 the largest (ri
1d900 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 ghtmost).** para
1d910 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 meter. For all f
1d920 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e orms except ?NNN
1d930 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 , this will corr
1d940 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a espond to the.**
1d950 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 number of uniqu
1d960 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 e parameters. I
1d970 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 f parameters of
1d980 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 the ?NNN are use
1d990 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 d,.** there may
1d9a0 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c be gaps in the l
1d9b0 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ist..**.** See a
1d9c0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
1d9d0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
1d9e0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c bind()],.** [sql
1d9f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
1da00 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 ter_name()], and
1da10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
1da20 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
1da30 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 x()]..**.** Requ
1da40 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
1da50 33 36 30 31 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 3601].*/.SQLITE_
1da60 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
1da70 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
1da80 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
1da90 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
1daa0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 count(sqlite3_st
1dab0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
1dac0 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 I3REF: Name Of A
1dad0 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20 Host Parameter
1dae0 7b 48 31 33 36 32 30 7d 20 3c 53 37 30 33 30 30 {H13620} <S70300
1daf0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 >.**.** This rou
1db00 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 tine returns a p
1db10 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61 ointer to the na
1db20 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a me of the n-th.*
1db30 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 * [SQL parameter
1db40 5d 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 ] in a [prepared
1db50 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 statement]..**
1db60 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f SQL parameters o
1db70 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e f the form "?NNN
1db80 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 " or ":AAA" or "
1db90 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a @AAA" or "$AAA".
1dba0 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 ** have a name w
1dbb0 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 hich is the stri
1dbc0 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 ng "?NNN" or ":A
1dbd0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 AA" or "@AAA" or
1dbe0 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 "$AAA".** respe
1dbf0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f ctively..** In o
1dc00 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
1dc10 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 initial ":" or "
1dc20 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 $" or "@" or "?"
1dc30 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 .** is included
1dc40 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e as part of the n
1dc50 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 ame..** Paramete
1dc60 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 rs of the form "
1dc70 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c ?" without a fol
1dc80 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 lowing integer h
1dc90 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 ave no name.** a
1dca0 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 65 66 65 nd are also refe
1dcb0 72 72 65 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e rred to as "anon
1dcc0 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 ymous parameters
1dcd0 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 "..**.** The fir
1dce0 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 st host paramete
1dcf0 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f r has an index o
1dd00 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a f 1, not 0..**.*
1dd10 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e * If the value n
1dd20 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
1dd30 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 or if the n-th
1dd40 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 parameter is.**
1dd50 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e nameless, then N
1dd60 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e ULL is returned.
1dd70 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 The returned s
1dd80 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 tring is.** alwa
1dd90 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f ys in UTF-8 enco
1dda0 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 ding even if the
1ddb0 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 named parameter
1ddc0 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c was.** original
1ddd0 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 ly specified as
1dde0 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 UTF-16 in [sqlit
1ddf0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 e3_prepare16()]
1de00 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 or.** [sqlite3_p
1de10 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a repare16_v2()]..
1de20 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
1de30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
1de40 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 ob|sqlite3_bind(
1de50 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
1de60 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
1de70 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 ount()], and.**
1de80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
1de90 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
1dea0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
1deb0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 32 31 ents:.** [H13621
1dec0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
1ded0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
1dee0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
1def0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
1df00 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
1df10 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 ter_name(sqlite3
1df20 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f _stmt*, int);../
1df30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
1df40 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 ndex Of A Parame
1df50 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e ter With A Given
1df60 20 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c Name {H13640} <
1df70 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 S70300>.**.** Re
1df80 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f turn the index o
1df90 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 f an SQL paramet
1dfa0 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d er given its nam
1dfb0 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 e. The.** index
1dfc0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
1dfd0 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 is suitable for
1dfe0 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e use as the secon
1dff0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 d.** parameter t
1e000 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f o [sqlite3_bind_
1e010 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
1e020 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a d()]. A zero.**
1e030 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 is returned if
1e040 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 no matching para
1e050 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 meter is found.
1e060 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a The parameter.*
1e070 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 * name must be g
1e080 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 iven in UTF-8 ev
1e090 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e en if the origin
1e0a0 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 al statement.**
1e0b0 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f was prepared fro
1e0c0 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 m UTF-16 text us
1e0d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ing [sqlite3_pre
1e0e0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a pare16_v2()]..**
1e0f0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
1e100 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
1e110 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
1e120 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
1e130 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
1e140 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 nt()], and.** [s
1e150 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1e160 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
1e170 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
1e180 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 34 31 5d 0a ts:.** [H13641].
1e190 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 */.SQLITE_API SQ
1e1a0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
1e1b0 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 69 API SQLITE_API i
1e1c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
1e1d0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
1e1e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 sqlite3_stmt*, c
1e1f0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
1e200 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1e210 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 EF: Reset All Bi
1e220 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 ndings On A Prep
1e230 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b ared Statement {
1e240 48 31 33 36 36 30 7d 20 3c 53 37 30 33 30 30 3e H13660} <S70300>
1e250 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 .**.** Contrary
1e260 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e to the intuition
1e270 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 of many, [sqlit
1e280 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 e3_reset()] does
1e290 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 not reset.** th
1e2a0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
1e2b0 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d blob | bindings]
1e2c0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 on a [prepared
1e2d0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 55 statement]..** U
1e2e0 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 se this routine
1e2f0 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 to reset all hos
1e300 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 t parameters to
1e310 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 NULL..**.** Requ
1e320 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
1e330 33 36 36 31 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 3661].*/.SQLITE_
1e340 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
1e350 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
1e360 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
1e370 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 _clear_bindings(
1e380 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
1e390 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1e3a0 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d Number Of Colum
1e3b0 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 ns In A Result S
1e3c0 65 74 20 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 et {H13710} <S10
1e3d0 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 700>.**.** Retur
1e3e0 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 n the number of
1e3f0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 columns in the r
1e400 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e esult set return
1e410 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 ed by the.** [pr
1e420 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1e430 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ]. This routine
1e440 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 returns 0 if pSt
1e450 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 mt is an SQL.**
1e460 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 statement that d
1e470 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 oes not return d
1e480 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 ata (for example
1e490 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a an [UPDATE])..*
1e4a0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
1e4b0 73 3a 0a 2a 2a 20 5b 48 31 33 37 31 31 5d 0a 2a s:.** [H13711].*
1e4c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c /.SQLITE_API SQL
1e4d0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
1e4e0 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e PI SQLITE_API in
1e4f0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
1e500 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 _count(sqlite3_s
1e510 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
1e520 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
1e530 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 lumn Names In A
1e540 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 Result Set {H137
1e550 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 20} <S10700>.**.
1e560 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
1e570 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d s return the nam
1e580 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 e assigned to a
1e590 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d particular colum
1e5a0 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 n.** in the resu
1e5b0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c lt set of a [SEL
1e5c0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 ECT] statement.
1e5d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c The sqlite3_col
1e5e0 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e umn_name().** in
1e5f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
1e600 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a a pointer to a z
1e610 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
1e620 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 TF-8 string.** a
1e630 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
1e640 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 n_name16() retur
1e650 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
1e660 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
1e670 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 d.** UTF-16 stri
1e680 6e 67 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 ng. The first p
1e690 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
1e6a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1e6b0 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 ent].** that imp
1e6c0 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c lements the [SEL
1e6d0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 ECT] statement.
1e6e0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
1e6f0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 eter is the.** c
1e700 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 olumn number. T
1e710 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 he leftmost colu
1e720 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a mn is number 0..
1e730 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e **.** The return
1e740 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 ed string pointe
1e750 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c r is valid until
1e760 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 either the [pre
1e770 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1e780 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 .** is destroyed
1e790 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e by [sqlite3_fin
1e7a0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 alize()] or unti
1e7b0 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 l the next call
1e7c0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f to.** sqlite3_co
1e7d0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 lumn_name() or s
1e7e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
1e7f0 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 me16() on the sa
1e800 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a me column..**.**
1e810 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c If sqlite3_mall
1e820 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e oc() fails durin
1e830 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 g the processing
1e840 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 of either routi
1e850 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 ne.** (for examp
1e860 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 le during a conv
1e870 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d ersion from UTF-
1e880 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 8 to UTF-16) the
1e890 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e n a.** NULL poin
1e8a0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ter is returned.
1e8b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 .**.** The name
1e8c0 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 of a result colu
1e8d0 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 mn is the value
1e8e0 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 of the "AS" clau
1e8f0 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 se for.** that c
1e900 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 olumn, if there
1e910 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e is an AS clause.
1e920 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f If there is no
1e930 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 AS clause.** th
1e940 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 en the name of t
1e950 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 he column is uns
1e960 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 pecified and may
1e970 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 change from.**
1e980 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 one release of S
1e990 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 QLite to the nex
1e9a0 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 t..**.** Require
1e9b0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 32 ments:.** [H1372
1e9c0 31 5d 20 5b 48 31 33 37 32 33 5d 20 5b 48 31 33 1] [H13723] [H13
1e9d0 37 32 34 5d 20 5b 48 31 33 37 32 35 5d 20 5b 48 724] [H13725] [H
1e9e0 31 33 37 32 36 5d 20 5b 48 31 33 37 32 37 5d 0a 13726] [H13727].
1e9f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 */.SQLITE_API SQ
1ea00 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
1ea10 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 63 API SQLITE_API c
1ea20 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
1ea30 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 e3_column_name(s
1ea40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
1ea50 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 t N);.SQLITE_API
1ea60 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
1ea70 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
1ea80 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
1ea90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
1eaa0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
1eab0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a *, int N);../*.*
1eac0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 * CAPI3REF: Sour
1ead0 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 ce Of Data In A
1eae0 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 Query Result {H1
1eaf0 33 37 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 3740} <S10700>.*
1eb00 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
1eb10 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 nes provide a me
1eb20 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 ans to determine
1eb30 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 what column of
1eb40 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e what.** table in
1eb50 20 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20 which database
1eb60 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20 5b 53 a result of a [S
1eb70 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
1eb80 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 comes from..**
1eb90 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 The name of the
1eba0 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c database or tabl
1ebb0 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 e or column can
1ebc0 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a be returned as.*
1ebd0 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 * either a UTF-8
1ebe0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e or UTF-16 strin
1ebf0 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61 73 g. The _databas
1ec00 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 e_ routines retu
1ec10 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 rn.** the databa
1ec20 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 se name, the _ta
1ec30 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 ble_ routines re
1ec40 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e turn the table n
1ec50 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 ame, and.** the
1ec60 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 origin_ routines
1ec70 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 return the colu
1ec80 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 mn name..** The
1ec90 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
1eca0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 is valid until t
1ecb0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
1ecc0 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 tement] is destr
1ecd0 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 oyed.** using [s
1ece0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
1ecf0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 )] or until the
1ed00 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e same information
1ed10 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a is requested.**
1ed20 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 again in a diff
1ed30 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a erent encoding..
1ed40 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 **.** The names
1ed50 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 returned are the
1ed60 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 original un-ali
1ed70 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 ased names of th
1ed80 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 e.** database, t
1ed90 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e able, and column
1eda0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
1edb0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
1edc0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c e following call
1edd0 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 s is a [prepared
1ede0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 statement]..**
1edf0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 These functions
1ee00 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 return informati
1ee10 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 on about the Nth
1ee20 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 column returned
1ee30 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 by.** the state
1ee40 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 ment, where N is
1ee50 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 the second func
1ee60 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a tion argument..*
1ee70 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20 *.** If the Nth
1ee80 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 column returned
1ee90 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 by the statement
1eea0 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f is an expressio
1eeb0 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 n or.** subquery
1eec0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f and is not a co
1eed0 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e lumn value, then
1eee0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 all of these fu
1eef0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a nctions return.*
1ef00 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72 * NULL. These r
1ef10 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 outine might als
1ef20 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 o return NULL if
1ef30 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
1ef40 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 tion error.** oc
1ef50 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65 curs. Otherwise
1ef60 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 , they return th
1ef70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 e name of the at
1ef80 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c tached database,
1ef90 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f table.** and co
1efa0 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 lumn that query
1efb0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 result column wa
1efc0 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d s extracted from
1efd0 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 ..**.** As with
1efe0 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 all other SQLite
1eff0 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 APIs, those pos
1f000 74 66 69 78 65 64 20 77 69 74 68 20 22 31 36 22 tfixed with "16"
1f010 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 return.** UTF-1
1f020 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 6 encoded string
1f030 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e s, the other fun
1f040 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 ctions return UT
1f050 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a F-8. {END}.**.**
1f060 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 These APIs are
1f070 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 only available i
1f080 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 f the library wa
1f090 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
1f0a0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 the.** [SQLITE_E
1f0b0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 NABLE_COLUMN_MET
1f0c0 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 ADATA] C-preproc
1f0d0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 essor symbol def
1f0e0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 ined..**.** {A13
1f0f0 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 751}.** If two o
1f100 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 r more threads c
1f110 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 all one or more
1f120 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
1f130 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 s against the sa
1f140 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 me.** prepared s
1f150 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c tatement and col
1f160 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 umn at the same
1f170 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 time then the re
1f180 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 sults are.** und
1f190 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 efined..**.** Re
1f1a0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
1f1b0 48 31 33 37 34 31 5d 20 5b 48 31 33 37 34 32 5d H13741] [H13742]
1f1c0 20 5b 48 31 33 37 34 33 5d 20 5b 48 31 33 37 34 [H13743] [H1374
1f1d0 34 5d 20 5b 48 31 33 37 34 35 5d 20 5b 48 31 33 4] [H13745] [H13
1f1e0 37 34 36 5d 20 5b 48 31 33 37 34 38 5d 0a 2a 2a 746] [H13748].**
1f1f0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f .** If two or mo
1f200 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 re threads call
1f210 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b one or more.** [
1f220 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
1f230 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 atabase_name | c
1f240 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 olumn metadata i
1f250 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f nterfaces].** fo
1f260 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 r the same [prep
1f270 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
1f280 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d and result colum
1f290 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 n.** at the same
1f2a0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 time then the r
1f2b0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 esults are undef
1f2c0 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ined..*/.SQLITE_
1f2d0 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
1f2e0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
1f2f0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
1f300 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
1f310 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 database_name(sq
1f320 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
1f330 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c ;.SQLITE_API SQL
1f340 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
1f350 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 63 6f PI SQLITE_API co
1f360 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
1f370 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 3_column_databas
1f380 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 e_name16(sqlite3
1f390 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c _stmt*,int);.SQL
1f3a0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
1f3b0 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
1f3c0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
1f3d0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
1f3e0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 umn_table_name(s
1f3f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
1f400 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 );.SQLITE_API SQ
1f410 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
1f420 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 63 API SQLITE_API c
1f430 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
1f440 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f e3_column_table_
1f450 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
1f460 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 tmt*,int);.SQLIT
1f470 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
1f480 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
1f490 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
1f4a0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
1f4b0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 n_origin_name(sq
1f4c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
1f4d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c ;.SQLITE_API SQL
1f4e0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
1f4f0 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 63 6f PI SQLITE_API co
1f500 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
1f510 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 3_column_origin_
1f520 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
1f530 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a tmt*,int);../*.*
1f540 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c * CAPI3REF: Decl
1f550 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 ared Datatype Of
1f560 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 A Query Result
1f570 7b 48 31 33 37 36 30 7d 20 3c 53 31 30 37 30 30 {H13760} <S10700
1f580 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 >.**.** The firs
1f590 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 t parameter is a
1f5a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1f5b0 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 ment]..** If thi
1f5c0 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 s statement is a
1f5d0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
1f5e0 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 ent and the Nth
1f5f0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a column of the.**
1f600 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 returned result
1f610 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 set of that [SE
1f620 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 LECT] is a table
1f630 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a column (not an.
1f640 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 ** expression or
1f650 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 subquery) then
1f660 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 the declared typ
1f670 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a e of the table.*
1f680 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 * column is retu
1f690 72 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74 rned. If the Nt
1f6a0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 h column of the
1f6b0 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e result set is an
1f6c0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f .** expression o
1f6d0 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e r subquery, then
1f6e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
1f6f0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 is returned..**
1f700 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
1f710 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 ing is always UT
1f720 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e F-8 encoded. {EN
1f730 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 D}.**.** For exa
1f740 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 mple, given the
1f750 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a database schema:
1f760 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 .**.** CREATE TA
1f770 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e BLE t1(c1 VARIAN
1f780 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 T);.**.** and th
1f790 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 e following stat
1f7a0 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 ement to be comp
1f7b0 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 iled:.**.** SELE
1f7c0 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 CT c1 + 1, c1 FR
1f7d0 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 OM t1;.**.** thi
1f7e0 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 s routine would
1f7f0 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e return the strin
1f800 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 g "VARIANT" for
1f810 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c the second resul
1f820 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d t.** column (i==
1f830 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 1), and a NULL p
1f840 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 ointer for the f
1f850 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 irst result colu
1f860 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a mn (i==0)..**.**
1f870 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e SQLite uses dyn
1f880 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 amic run-time ty
1f890 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 ping. So just b
1f8a0 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a ecause a column.
1f8b0 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 ** is declared t
1f8c0 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 o contain a part
1f8d0 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 icular type does
1f8e0 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 not mean that t
1f8f0 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 he.** data store
1f900 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e d in that column
1f910 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 is of the decla
1f920 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 red type. SQLit
1f930 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 e is.** strongly
1f940 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 typed, but the
1f950 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 typing is dynami
1f960 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 c not static. T
1f970 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 ype.** is associ
1f980 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 ated with indivi
1f990 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 dual values, not
1f9a0 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 with the contai
1f9b0 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 ners.** used to
1f9c0 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 hold those value
1f9d0 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 s..**.** Require
1f9e0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 36 ments:.** [H1376
1f9f0 31 5d 20 5b 48 31 33 37 36 32 5d 20 5b 48 31 33 1] [H13762] [H13
1fa00 37 36 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 763].*/.SQLITE_A
1fa10 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
1fa20 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
1fa30 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
1fa40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
1fa50 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f ecltype(sqlite3_
1fa60 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 stmt*,int);.SQLI
1fa70 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
1fa80 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
1fa90 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
1faa0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
1fab0 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 mn_decltype16(sq
1fac0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
1fad0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1fae0 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 F: Evaluate An S
1faf0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 QL Statement {H1
1fb00 33 32 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 3200} <S10000>.*
1fb10 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 *.** After a [pr
1fb20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1fb30 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 ] has been prepa
1fb40 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 red using either
1fb50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
1fb60 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 pare_v2()] or [s
1fb70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
1fb80 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 _v2()] or one of
1fb90 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 the legacy.** i
1fba0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 nterfaces [sqlit
1fbb0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
1fbc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1fbd0 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e e16()], this fun
1fbe0 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 ction.** must be
1fbf0 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d called one or m
1fc00 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 ore times to eva
1fc10 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d luate the statem
1fc20 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 ent..**.** The d
1fc30 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 etails of the be
1fc40 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 havior of the sq
1fc50 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 lite3_step() int
1fc60 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a erface depend.**
1fc70 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 on whether the
1fc80 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 statement was pr
1fc90 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 epared using the
1fca0 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 newer "v2" inte
1fcb0 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 rface.** [sqlite
1fcc0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
1fcd0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
1fce0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 pare16_v2()] or
1fcf0 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 the older legacy
1fd00 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 .** interface [s
1fd10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
1fd20 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
1fd30 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 repare16()]. Th
1fd40 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 e use of the.**
1fd50 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 new "v2" interfa
1fd60 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ce is recommende
1fd70 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 d for new applic
1fd80 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c ations but the l
1fd90 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 egacy.** interfa
1fda0 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 ce will continue
1fdb0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
1fdc0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c ..**.** In the l
1fdd0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c egacy interface,
1fde0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
1fdf0 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 e will be either
1fe00 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a [SQLITE_BUSY],.
1fe10 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d ** [SQLITE_DONE]
1fe20 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 , [SQLITE_ROW],
1fe30 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 [SQLITE_ERROR],
1fe40 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 or [SQLITE_MISUS
1fe50 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 E]..** With the
1fe60 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 "v2" interface,
1fe70 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 any of the other
1fe80 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 [result codes]
1fe90 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 or.** [extended
1fea0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 result codes] mi
1feb0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 ght be returned
1fec0 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b as well..**.** [
1fed0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 SQLITE_BUSY] mea
1fee0 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 ns that the data
1fef0 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 base engine was
1ff00 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 unable to acquir
1ff10 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 e the.** databas
1ff20 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 e locks it needs
1ff30 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 to do its job.
1ff40 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e If the statemen
1ff50 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a t is a [COMMIT].
1ff60 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 ** or occurs out
1ff70 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 side of an expli
1ff80 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c cit transaction,
1ff90 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 then you can re
1ffa0 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 try the.** state
1ffb0 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 ment. If the st
1ffc0 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 atement is not a
1ffd0 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 [COMMIT] and oc
1ffe0 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a curs within a.**
1fff0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 explicit transa
20000 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 ction then you s
20010 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 hould rollback t
20020 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 he transaction b
20030 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 efore.** continu
20040 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 ing..**.** [SQLI
20050 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 TE_DONE] means t
20060 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e hat the statemen
20070 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 t has finished e
20080 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 xecuting.** succ
20090 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 essfully. sqlit
200a0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 e3_step() should
200b0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 not be called a
200c0 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 gain on this vir
200d0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 tual.** machine
200e0 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 without first ca
200f0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 lling [sqlite3_r
20100 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 eset()] to reset
20110 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 the virtual.**
20120 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 machine back to
20130 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 its initial stat
20140 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 e..**.** If the
20150 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 SQL statement be
20160 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 ing executed ret
20170 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 urns any data, t
20180 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d hen [SQLITE_ROW]
20190 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
201a0 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 each time a new
201b0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 row of data is r
201c0 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 eady for process
201d0 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 ing by the.** ca
201e0 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 ller. The values
201f0 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 may be accessed
20200 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 using the [colu
20210 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 mn access functi
20220 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 ons]..** sqlite3
20230 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 _step() is calle
20240 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 d again to retri
20250 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 eve the next row
20260 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 of data..**.**
20270 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d [SQLITE_ERROR] m
20280 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d eans that a run-
20290 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 time error (such
202a0 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 as a constraint
202b0 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 .** violation) h
202c0 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 as occurred. sq
202d0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f lite3_step() sho
202e0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 uld not be calle
202f0 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 d again on.** th
20300 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 e VM. More infor
20310 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f mation may be fo
20320 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b und by calling [
20330 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
20340 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c ]..** With the l
20350 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c egacy interface,
20360 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 a more specific
20370 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 error code (for
20380 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 example,.** [SQ
20390 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c LITE_INTERRUPT],
203a0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
203b0 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 , [SQLITE_CORRUP
203c0 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 T], and so forth
203d0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 ).** can be obta
203e0 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 ined by calling
203f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
20400 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 ] on the.** [pre
20410 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
20420 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 . In the "v2" i
20430 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 nterface,.** the
20440 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 more specific e
20450 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 rror code is ret
20460 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 urned directly b
20470 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 y sqlite3_step()
20480 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ..**.** [SQLITE_
20490 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 MISUSE] means th
204a0 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 at the this rout
204b0 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 ine was called i
204c0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a nappropriately..
204d0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 ** Perhaps it wa
204e0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 s called on a [p
204f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
20500 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 t] that has.** a
20510 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c lready been [sql
20520 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 ite3_finalize |
20530 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e finalized] or on
20540 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a one that had.**
20550 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 previously retu
20560 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 rned [SQLITE_ERR
20570 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 OR] or [SQLITE_D
20580 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 ONE]. Or it cou
20590 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 ld.** be the cas
205a0 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 e that the same
205b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
205c0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 ion is being use
205d0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d d by two or.** m
205e0 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 ore threads at t
205f0 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 he same moment i
20600 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 n time..**.** <b
20610 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 >Goofy Interface
20620 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 Alert:</b> In t
20630 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
20640 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 ace, the sqlite3
20650 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 _step().** API a
20660 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 lways returns a
20670 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f generic error co
20680 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f de, [SQLITE_ERRO
20690 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e R], following an
206a0 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 y.** error other
206b0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 than [SQLITE_BU
206c0 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f SY] and [SQLITE_
206d0 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 MISUSE]. You mu
206e0 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 st call.** [sqli
206f0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 te3_reset()] or
20700 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
20710 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f e()] in order to
20720 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 find one of the
20730 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 .** specific [er
20740 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 ror codes] that
20750 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 better describes
20760 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 the error..** W
20770 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 e admit that thi
20780 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 s is a goofy des
20790 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 ign. The proble
207a0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 m has been fixed
207b0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 .** with the "v2
207c0 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 " interface. If
207d0 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c you prepare all
207e0 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 of your SQL sta
207f0 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 tements.** using
20800 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 either [sqlite3
20810 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
20820 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
20830 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 re16_v2()] inste
20840 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 ad.** of the leg
20850 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 acy [sqlite3_pre
20860 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c pare()] and [sql
20870 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
20880 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a ] interfaces,.**
20890 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 then the more s
208a0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 pecific [error c
208b0 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e odes] are return
208c0 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 ed directly.** b
208d0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 y sqlite3_step()
208e0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 . The use of th
208f0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
20900 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e is recommended.
20910 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
20920 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 32 30 32 5d nts:.** [H13202]
20930 20 5b 48 31 35 33 30 34 5d 20 5b 48 31 35 33 30 [H15304] [H1530
20940 36 5d 20 5b 48 31 35 33 30 38 5d 20 5b 48 31 35 6] [H15308] [H15
20950 33 31 30 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 310].*/.SQLITE_A
20960 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
20970 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
20980 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
20990 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d step(sqlite3_stm
209a0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
209b0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 3REF: Number of
209c0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 columns in a res
209d0 75 6c 74 20 73 65 74 20 7b 48 31 33 37 37 30 7d ult set {H13770}
209e0 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S10700>.**.**
209f0 52 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 Returns the numb
20a00 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 er of values in
20a10 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 the current row
20a20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
20a30 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 t..**.** Require
20a40 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 37 ments:.** [H1377
20a50 31 5d 20 5b 48 31 33 37 37 32 5d 0a 2a 2f 0a 53 1] [H13772].*/.S
20a60 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
20a70 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
20a80 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
20a90 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
20aa0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
20ab0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
20ac0 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 API3REF: Fundame
20ad0 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b ntal Datatypes {
20ae0 48 31 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e H10265} <S10110>
20af0 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 <S10120>.** KEYW
20b00 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 ORDS: SQLITE_TEX
20b10 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d T.**.** {H10266}
20b20 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 Every value in
20b30 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f SQLite has one o
20b40 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 f five fundament
20b50 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a al datatypes:.**
20b60 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
20b70 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 64-bit signed i
20b80 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 nteger.** <li> 6
20b90 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 4-bit IEEE float
20ba0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 ing point number
20bb0 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a .** <li> string.
20bc0 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 ** <li> BLOB.**
20bd0 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 <li> NULL.** </u
20be0 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 l> {END}.**.** T
20bf0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 hese constants a
20c00 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 re codes for eac
20c10 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 h of those types
20c20 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
20c30 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 t the SQLITE_TEX
20c40 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 T constant was a
20c50 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 lso used in SQLi
20c60 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 te version 2.**
20c70 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 for a completely
20c80 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 different meani
20c90 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 ng. Software th
20ca0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 at links against
20cb0 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 both.** SQLite
20cc0 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 version 2 and SQ
20cd0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 Lite version 3 s
20ce0 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 hould use SQLITE
20cf0 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 3_TEXT, not.** S
20d00 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 QLITE_TEXT..*/.#
20d10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
20d20 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 TEGER 1.#define
20d30 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 SQLITE_FLOAT
20d40 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
20d50 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 E_BLOB 4.#de
20d60 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c fine SQLITE_NULL
20d70 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 5.#ifdef SQ
20d80 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 LITE_TEXT.# unde
20d90 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 f SQLITE_TEXT.#e
20da0 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c lse.# define SQL
20db0 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 ITE_TEXT 3.#
20dc0 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 endif.#define SQ
20dd0 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 LITE3_TEXT 3
20de0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
20df0 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 : Result Values
20e00 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31 From A Query {H1
20e10 33 38 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 3800} <S10700>.*
20e20 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c * KEYWORDS: {col
20e30 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 umn access funct
20e40 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ions}.**.** Thes
20e50 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 e routines form
20e60 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 the "result set
20e70 71 75 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 query" interface
20e80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
20e90 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e utines return in
20ea0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 formation about
20eb0 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 a single column
20ec0 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a of the current.*
20ed0 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 * result row of
20ee0 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 a query. In eve
20ef0 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 ry case the firs
20f00 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 t argument is a
20f10 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 pointer.** to th
20f20 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
20f30 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 ement] that is b
20f40 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 eing evaluated (
20f50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d the [sqlite3_stm
20f60 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 t*].** that was
20f70 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 returned from [s
20f80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
20f90 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 2()] or one of i
20fa0 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 ts variants).**
20fb0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 and the second a
20fc0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 rgument is the i
20fd0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 ndex of the colu
20fe0 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 mn for which inf
20ff0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 ormation.** shou
21000 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 ld be returned.
21010 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f The leftmost co
21020 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 lumn of the resu
21030 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 lt set has the i
21040 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 ndex 0..**.** If
21050 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
21060 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 nt does not curr
21070 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 ently point to a
21080 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 valid row, or i
21090 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 f the.** column
210a0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 index is out of
210b0 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c range, the resul
210c0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a t is undefined..
210d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
210e0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 s may only be ca
210f0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f lled when the mo
21100 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
21110 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 o.** [sqlite3_st
21120 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e ep()] has return
21130 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 ed [SQLITE_ROW]
21140 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b and neither.** [
21150 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
21160 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 nor [sqlite3_fi
21170 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 nalize()] have b
21180 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 een called subse
21190 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 quently..** If a
211a0 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
211b0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
211c0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 after [sqlite3_r
211d0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
211e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
211f0 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c )] or after [sql
21200 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 ite3_step()] has
21210 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d returned.** som
21220 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 ething other tha
21230 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 n [SQLITE_ROW],
21240 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
21250 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 undefined..** If
21260 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
21270 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
21280 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
21290 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a e3_finalize()].*
212a0 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f * are called fro
212b0 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 m a different th
212c0 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f read while any o
212d0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
212e0 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c .** are pending,
212f0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
21300 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
21310 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
21320 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
21330 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
21340 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
21350 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 INTEGER | dataty
21360 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 pe code] for the
21370 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 initial data ty
21380 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 pe.** of the res
21390 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 ult column. The
213a0 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 returned value
213b0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 is one of [SQLIT
213c0 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b E_INTEGER],.** [
213d0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b SQLITE_FLOAT], [
213e0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 SQLITE_TEXT], [S
213f0 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 QLITE_BLOB], or
21400 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 [SQLITE_NULL].
21410 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 The value.** ret
21420 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
21430 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 _column_type() i
21440 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 s only meaningfu
21450 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 l if no type.**
21460 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 conversions have
21470 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 occurred as des
21480 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 cribed below. A
21490 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 fter a type conv
214a0 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 ersion,.** the v
214b0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
214c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
214d0 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 type() is undefi
214e0 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 ned. Future.**
214f0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
21500 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 te may change th
21510 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 e behavior of sq
21520 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
21530 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 e().** following
21540 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 a type conversi
21550 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 on..**.** If the
21560 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f result is a BLO
21570 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e B or UTF-8 strin
21580 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 g then the sqlit
21590 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
215a0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 ).** routine ret
215b0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
215c0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
215d0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e BLOB or string.
215e0 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c .** If the resul
215f0 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 t is a UTF-16 st
21600 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 ring, then sqlit
21610 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
21620 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 ) converts.** th
21630 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d e string to UTF-
21640 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 8 and then retur
21650 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
21660 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 bytes..** If th
21670 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 e result is a nu
21680 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e meric value then
21690 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
216a0 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 bytes() uses.**
216b0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
216c0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 f()] to convert
216d0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 that value to a
216e0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 UTF-8 string and
216f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 returns.** the
21700 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
21710 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a in that string..
21720 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 ** The value ret
21730 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 urned does not i
21740 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 nclude the zero
21750 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 terminator at th
21760 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 e end.** of the
21770 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 string. For cla
21780 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 rity: the value
21790 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 returned is the
217a0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 number of.** byt
217b0 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 es in the string
217c0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 , not the number
217d0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a of characters..
217e0 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 **.** Strings re
217f0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
21800 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
21810 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
21820 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 mn_text16(),.**
21830 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e even empty strin
21840 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a gs, are always z
21850 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 ero terminated.
21860 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 The return.** v
21870 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
21880 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 3_column_blob()
21890 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 for a zero-lengt
218a0 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 h BLOB is an arb
218b0 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 itrary.** pointe
218c0 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e r, possibly even
218d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
218e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
218f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
21900 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 6() routine is s
21910 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 imilar to sqlite
21920 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
21930 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 .** but leaves t
21940 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 he result in UTF
21950 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 -16 in native by
21960 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 te order instead
21970 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 of UTF-8..** Th
21980 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f e zero terminato
21990 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 r is not include
219a0 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e d in this count.
219b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 .**.** The objec
219c0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 t returned by [s
219d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
219e0 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 lue()] is an.**
219f0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
21a00 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
21a10 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 ct. An unprotec
21a20 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
21a30 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 e object.** may
21a40 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 only be used wit
21a50 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f h [sqlite3_bind_
21a60 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 value()] and [sq
21a70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
21a80 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 ue()]..** If the
21a90 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
21aa0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
21ab0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a ect returned by.
21ac0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
21ad0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 mn_value()] is u
21ae0 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 sed in any other
21af0 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 way, including
21b00 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 calls.** to rout
21b10 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 ines like [sqlit
21b20 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c e3_value_int()],
21b30 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
21b40 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b text()],.** or [
21b50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
21b60 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 tes()], then the
21b70 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
21b80 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 efined..**.** Th
21b90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 ese routines att
21ba0 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 empt to convert
21bb0 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 the value where
21bc0 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f appropriate. Fo
21bd0 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 r.** example, if
21be0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 the internal re
21bf0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 presentation is
21c00 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 FLOAT and a text
21c10 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 result.** is re
21c20 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 quested, [sqlite
21c30 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 3_snprintf()] is
21c40 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 used internally
21c50 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a to perform the.
21c60 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 ** conversion au
21c70 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 tomatically. Th
21c80 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c e following tabl
21c90 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f e details the co
21ca0 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 nversions.** tha
21cb0 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a t are applied:.*
21cc0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
21cd0 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 >.** <table bord
21ce0 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c er="1">.** <tr><
21cf0 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e th> Internal<br>
21d00 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 Type <th> Reques
21d10 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e ted<br>Type <th>
21d20 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a Conversion.**.
21d30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c ** <tr><td> NUL
21d40 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 L <td> INTEGE
21d50 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 R <td> Result
21d60 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e is 0.** <tr><td>
21d70 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 NULL <td>
21d80 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 FLOAT <td> Re
21d90 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c sult is 0.0.** <
21da0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
21db0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 <td> TEXT
21dc0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e <td> Result is N
21dd0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c ULL pointer.** <
21de0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
21df0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
21e00 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e <td> Result is N
21e10 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c ULL pointer.** <
21e20 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 tr><td> INTEGER
21e30 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 <td> FLOAT
21e40 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f <td> Convert fro
21e50 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f m integer to flo
21e60 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 at.** <tr><td> I
21e70 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 NTEGER <td> T
21e80 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 EXT <td> ASCI
21e90 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 I rendering of t
21ea0 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 he integer.** <t
21eb0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 r><td> INTEGER
21ec0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
21ed0 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 td> Same as INTE
21ee0 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 GER->TEXT.** <tr
21ef0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c ><td> FLOAT <
21f00 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 td> INTEGER <t
21f10 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 d> Convert from
21f20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 float to integer
21f30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c .** <tr><td> FL
21f40 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 OAT <td> TEX
21f50 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 T <td> ASCII
21f60 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
21f70 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 float.** <tr><t
21f80 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
21f90 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
21fa0 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 Same as FLOAT->T
21fb0 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 EXT.** <tr><td>
21fc0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e TEXT <td> IN
21fd0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 TEGER <td> Use
21fe0 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c atoi().** <tr><
21ff0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 td> TEXT <td
22000 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
22010 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c Use atof().** <
22020 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 tr><td> TEXT
22030 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
22040 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a <td> No change.*
22050 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
22060 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
22070 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
22080 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 to TEXT then use
22090 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c atoi().** <tr><
220a0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 td> BLOB <td
220b0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
220c0 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 Convert to TEXT
220d0 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 then use atof()
220e0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c .** <tr><td> BL
220f0 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 OB <td> TEX
22100 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 T <td> Add a
22110 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 zero terminator
22120 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 if needed.** </t
22130 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b able>.** </block
22140 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
22150 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b table above mak
22160 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 es reference to
22170 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
22180 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f ry functions ato
22190 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 i().** and atof(
221a0 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 ). SQLite does
221b0 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 not really use t
221c0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 hese functions.
221d0 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f It has its.** o
221e0 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e wn equivalent in
221f0 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e ternal routines.
22200 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 The atoi() and
22210 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 atof() names ar
22220 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 e.** used in the
22230 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 table for brevi
22240 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 ty and because t
22250 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 hey are familiar
22260 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 to most.** C pr
22270 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a ogrammers..**.**
22280 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 Note that when
22290 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 type conversions
222a0 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 occur, pointers
222b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 returned by pri
222c0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 or.** calls to s
222d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
222e0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f ob(), sqlite3_co
222f0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 lumn_text(), and
22300 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 /or.** sqlite3_c
22310 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d olumn_text16() m
22320 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 ay be invalidate
22330 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 d..** Type conve
22340 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 rsions and point
22350 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 er invalidations
22360 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 might occur.**
22370 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 in the following
22380 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 cases:.**.** <u
22390 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 l>.** <li> The i
223a0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
223b0 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c s a BLOB and sql
223c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
223d0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 () or.** sq
223e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
223f0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e t16() is called.
22400 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 A zero-termina
22410 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 tor might.**
22420 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 need to be add
22430 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 ed to the string
22440 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 .</li>.** <li> T
22450 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
22460 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 nt is UTF-8 text
22470 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
22480 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 umn_bytes16() or
22490 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 .** sqlite3
224a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
224b0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 is called. The
224c0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 content must be
224d0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 converted.**
224e0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c to UTF-16.</l
224f0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 i>.** <li> The i
22500 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
22510 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e s UTF-16 text an
22520 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
22530 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 _bytes() or.**
22540 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 sqlite3_colu
22550 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c mn_text() is cal
22560 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e led. The conten
22570 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 t must be conver
22580 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 ted.** to U
22590 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f TF-8.</li>.** </
225a0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 ul>.**.** Conver
225b0 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 sions between UT
225c0 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 F-16be and UTF-1
225d0 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6le are always d
225e0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 one in place and
225f0 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c do.** not inval
22600 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f idate a prior po
22610 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 inter, though of
22620 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 course the cont
22630 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 ent of the buffe
22640 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 r.** that the pr
22650 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e ior pointer poin
22660 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 ts to will have
22670 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 been modified.
22680 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f Other kinds.** o
22690 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 f conversion are
226a0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 done in place w
226b0 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 hen it is possib
226c0 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 le, but sometime
226d0 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f s they.** are no
226e0 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 t possible and i
226f0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 n those cases pr
22700 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 ior pointers are
22710 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a invalidated..**
22720 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 .** The safest a
22730 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 nd easiest to re
22740 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 member policy is
22750 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 to invoke these
22760 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 routines.** in
22770 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
22780 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a wing ways:.**.**
22790 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 <ul>.** <li>sq
227a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
227b0 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 t() followed by
227c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
227d0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 ytes()</li>.**
227e0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 <li>sqlite3_colu
227f0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 mn_blob() follow
22800 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
22810 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 lumn_bytes()</li
22820 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 >.** <li>sqlite
22830 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
22840 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 ) followed by sq
22850 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
22860 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c es16()</li>.** <
22870 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 /ul>.**.** In ot
22880 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 her words, you s
22890 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 hould call sqlit
228a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
228b0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c ,.** sqlite3_col
228c0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 umn_blob(), or s
228d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
228e0 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 xt16() first to
228f0 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 force the result
22900 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 .** into the des
22910 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 ired format, the
22920 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 n invoke sqlite3
22930 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
22940 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f or.** sqlite3_co
22950 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 lumn_bytes16() t
22960 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 o find the size
22970 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 of the result.
22980 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 Do not mix calls
22990 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 .** to sqlite3_c
229a0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 olumn_text() or
229b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
229c0 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 lob() with calls
229d0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 to.** sqlite3_c
229e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c olumn_bytes16(),
229f0 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 and do not mix
22a00 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
22a10 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
22a20 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 .** with calls t
22a30 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
22a40 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 _bytes()..**.**
22a50 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 The pointers ret
22a60 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 urned are valid
22a70 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e until a type con
22a80 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 version occurs a
22a90 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 s.** described a
22aa0 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b bove, or until [
22ab0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
22ac0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 or [sqlite3_rese
22ad0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 t()] or.** [sqli
22ae0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
22af0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 is called. The
22b00 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 memory space use
22b10 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 d to hold string
22b20 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 s.** and BLOBs i
22b30 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 s freed automati
22b40 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f cally. Do <b>no
22b50 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 t</b> pass the p
22b60 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 ointers returned
22b70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
22b80 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 umn_blob()], [sq
22b90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
22ba0 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a t()], etc. into.
22bb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
22bc0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 ()]..**.** If a
22bd0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
22be0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 n error occurs d
22bf0 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 uring the evalua
22c00 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f tion of any.** o
22c10 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
22c20 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 , a default valu
22c30 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 e is returned.
22c40 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 The default valu
22c50 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 e.** is either t
22c60 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 he integer 0, th
22c70 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 e floating point
22c80 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 number 0.0, or
22c90 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 a NULL.** pointe
22ca0 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 r. Subsequent c
22cb0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
22cc0 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c _errcode()] will
22cd0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 return.** [SQLI
22ce0 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a TE_NOMEM]..**.**
22cf0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
22d00 2a 20 5b 48 31 33 38 30 33 5d 20 5b 48 31 33 38 * [H13803] [H138
22d10 30 36 5d 20 5b 48 31 33 38 30 39 5d 20 5b 48 31 06] [H13809] [H1
22d20 33 38 31 32 5d 20 5b 48 31 33 38 31 35 5d 20 5b 3812] [H13815] [
22d30 48 31 33 38 31 38 5d 20 5b 48 31 33 38 32 31 5d H13818] [H13821]
22d40 20 5b 48 31 33 38 32 34 5d 0a 2a 2a 20 5b 48 31 [H13824].** [H1
22d50 33 38 32 37 5d 20 5b 48 31 33 38 33 30 5d 0a 2a 3827] [H13830].*
22d60 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c /.SQLITE_API SQL
22d70 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
22d80 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 63 6f PI SQLITE_API co
22d90 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
22da0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 3_column_blob(sq
22db0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
22dc0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
22dd0 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
22de0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
22df0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
22e00 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c column_bytes(sql
22e10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
22e20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 iCol);.SQLITE_AP
22e30 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
22e40 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
22e50 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
22e60 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 olumn_bytes16(sq
22e70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
22e80 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
22e90 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
22ea0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
22eb0 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 API double sqlit
22ec0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 e3_column_double
22ed0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
22ee0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 int iCol);.SQLIT
22ef0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
22f00 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
22f10 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
22f20 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 e3_column_int(sq
22f30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
22f40 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
22f50 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
22f60 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
22f70 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 API sqlite3_int6
22f80 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 4 sqlite3_column
22f90 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 _int64(sqlite3_s
22fa0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
22fb0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
22fc0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
22fd0 49 20 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e I SQLITE_API con
22fe0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 st unsigned char
22ff0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
23000 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 _text(sqlite3_st
23010 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
23020 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
23030 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
23040 20 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 SQLITE_API cons
23050 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
23060 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 column_text16(sq
23070 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
23080 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
23090 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
230a0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
230b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
230c0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 column_type(sqli
230d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
230e0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
230f0 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
23100 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
23110 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 I sqlite3_value
23120 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
23130 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 value(sqlite3_st
23140 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
23150 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
23160 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 Destroy A Prepa
23170 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 red Statement Ob
23180 6a 65 63 74 20 7b 48 31 33 33 30 30 7d 20 3c 53 ject {H13300} <S
23190 37 30 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 70300><S30100>.*
231a0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
231b0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 _finalize() func
231c0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 tion is called t
231d0 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 o delete a [prep
231e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
231f0 0a 2a 2a 20 49 66 20 74 68 65 20 73 74 61 74 65 .** If the state
23200 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74 65 ment was execute
23210 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f d successfully o
23220 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 r not executed a
23230 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 t all, then.** S
23240 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 QLITE_OK is retu
23250 72 6e 65 64 2e 20 49 66 20 65 78 65 63 75 74 69 rned. If executi
23260 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d on of the statem
23270 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 ent failed then
23280 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 an.** [error cod
23290 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 e] or [extended
232a0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
232b0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 eturned..**.** T
232c0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 his routine can
232d0 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 be called at any
232e0 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 point during th
232f0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 e execution of t
23300 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
23310 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 statement]. If
23320 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 the virtual mach
23330 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 ine has not.** c
23340 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 ompleted executi
23350 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 on when this rou
23360 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 tine is called,
23370 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 that is like.**
23380 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 encountering an
23390 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c error or an [sql
233a0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c ite3_interrupt |
233b0 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 interrupt]..**
233c0 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 Incomplete updat
233d0 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 es may be rolled
233e0 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 back and transa
233f0 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c ctions canceled,
23400 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e .** depending on
23410 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 the circumstanc
23420 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b es, and the.** [
23430 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 error code] retu
23440 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 rned will be [SQ
23450 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a LITE_ABORT]..**.
23460 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
23470 0a 2a 2a 20 5b 48 31 31 33 30 32 5d 20 5b 48 31 .** [H11302] [H1
23480 31 33 30 34 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 1304].*/.SQLITE_
23490 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
234a0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
234b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
234c0 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 _finalize(sqlite
234d0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
234e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
234f0 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 Reset A Prepare
23500 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 d Statement Obje
23510 63 74 20 7b 48 31 33 33 33 30 7d 20 3c 53 37 30 ct {H13330} <S70
23520 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 300>.**.** The s
23530 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 qlite3_reset() f
23540 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 unction is calle
23550 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 d to reset a [pr
23560 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
23570 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b ].** object back
23580 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 to its initial
23590 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 state, ready to
235a0 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a be re-executed..
235b0 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 ** Any SQL state
235c0 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 ment variables t
235d0 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 hat had values b
235e0 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 ound to them usi
235f0 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 ng.** the [sqlit
23600 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 e3_bind_blob | s
23610 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
23620 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 API] retain thei
23630 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 r values..** Use
23640 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f [sqlite3_clear_
23650 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 bindings()] to r
23660 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 eset the binding
23670 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 32 s..**.** {H11332
23680 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 } The [sqlite3_r
23690 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 eset(S)] interfa
236a0 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 ce resets the [p
236b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
236c0 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 t] S.**
236d0 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 back to the beg
236e0 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 inning of its pr
236f0 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ogram..**.** {H1
23700 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 1334} If the mos
23710 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
23720 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
23730 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 )] for the.**
23740 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 [prepared
23750 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 statement] S re
23760 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 turned [SQLITE_R
23770 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 OW] or [SQLITE_D
23780 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 ONE],.**
23790 20 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 or if [sqlite3
237a0 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 _step(S)] has ne
237b0 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 ver before been
237c0 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 called on S,.**
237d0 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 then [s
237e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
237f0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
23800 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 _OK]..**.** {H11
23810 33 33 36 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 336} If the most
23820 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 recent call to
23830 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
23840 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 ] for the.**
23850 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 [prepared
23860 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 statement] S ind
23870 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c icated an error,
23880 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 then.**
23890 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 [sqlite3_reset
238a0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 (S)] returns an
238b0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 appropriate [err
238c0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 or code]..**.**
238d0 7b 48 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71 {H11338} The [sq
238e0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 lite3_reset(S)]
238f0 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e interface does n
23900 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 ot change the va
23910 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 lues.**
23920 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 of any [sqlite3
23930 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 _bind_blob|bindi
23940 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 ngs] on the [pre
23950 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
23960 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 S..*/.SQLITE_AP
23970 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
23980 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
23990 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 PI int sqlite3_r
239a0 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d eset(sqlite3_stm
239b0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
239c0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 * CAPI3REF: Crea
239d0 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 te Or Redefine S
239e0 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 QL Functions {H1
239f0 36 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 6100} <S20200>.*
23a00 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e * KEYWORDS: {fun
23a10 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 ction creation r
23a20 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 outines}.** KEYW
23a30 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 ORDS: {applicati
23a40 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
23a50 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 unction}.** KEYW
23a60 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 ORDS: {applicati
23a70 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
23a80 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 unctions}.**.**
23a90 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 These two functi
23aa0 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c ons (collectivel
23ab0 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 y known as "func
23ac0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f tion creation ro
23ad0 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 utines").** are
23ae0 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 used to add SQL
23af0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 functions or agg
23b00 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 regates or to re
23b10 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 define the behav
23b20 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 ior.** of existi
23b30 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ng SQL functions
23b40 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 or aggregates.
23b50 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 The only differ
23b60 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 ence between the
23b70 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 61 74 20 .** two is that
23b80 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
23b90 65 74 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f eter, the name o
23ba0 66 20 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 f the (scalar) f
23bb0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
23bc0 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f gregate, is enco
23bd0 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 ded in UTF-8 for
23be0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
23bf0 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 function() and U
23c00 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c TF-16.** for sql
23c10 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
23c20 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 tion16()..**.**
23c30 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
23c40 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 ter is the [data
23c50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
23c60 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 to which the SQ
23c70 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 L.** function is
23c80 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49 to be added. I
23c90 66 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 f a single progr
23ca0 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 am uses more tha
23cb0 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a n one database.*
23cc0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 * connection int
23cd0 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 ernally, then SQ
23ce0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 L functions must
23cf0 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 be added indivi
23d00 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 dually to.** eac
23d10 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 h database conne
23d20 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ction..**.** The
23d30 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
23d40 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 r is the name of
23d50 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
23d60 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 n to be created
23d70 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e or.** redefined.
23d80 20 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 The length of
23d90 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 the name is limi
23da0 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 ted to 255 bytes
23db0 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a , exclusive of.*
23dc0 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 * the zero-termi
23dd0 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 nator. Note tha
23de0 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 t the name lengt
23df0 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 h limit is in by
23e00 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 tes, not.** char
23e10 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 acters. Any att
23e20 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 empt to create a
23e30 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
23e40 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 longer name.**
23e50 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b will result in [
23e60 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 SQLITE_ERROR] be
23e70 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a ing returned..**
23e80 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70 61 .** The third pa
23e90 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a rameter (nArg).*
23ea0 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 * is the number
23eb0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 of arguments tha
23ec0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 t the SQL functi
23ed0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 on or.** aggrega
23ee0 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 te takes. If thi
23ef0 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d s parameter is -
23f00 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 1, then the SQL
23f10 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 function or.** a
23f20 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b ggregate may tak
23f30 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 e any number of
23f40 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 arguments betwee
23f50 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 n 0 and the limi
23f60 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c t.** set by [sql
23f70 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c ite3_limit]([SQL
23f80 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 ITE_LIMIT_FUNCTI
23f90 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 ON_ARG]). If th
23fa0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d e third.** param
23fb0 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 eter is less tha
23fc0 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 n -1 or greater
23fd0 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 than 127 then th
23fe0 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a e behavior is.**
23ff0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
24000 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 * The fourth par
24010 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 ameter, eTextRep
24020 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 , specifies what
24030 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 .** [SQLITE_UTF8
24040 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 | text encoding
24050 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 ] this SQL funct
24060 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a ion prefers for.
24070 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 ** its parameter
24080 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 s. Any SQL func
24090 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
240a0 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 ion should be ab
240b0 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f le to work.** wo
240c0 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 rk with UTF-8, U
240d0 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d TF-16le, or UTF-
240e0 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 16be. But some
240f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
24100 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 may be.** more e
24110 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e fficient with on
24120 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 e encoding than
24130 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20 another. It is
24140 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e allowed to.** in
24150 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 voke sqlite3_cre
24160 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f ate_function() o
24170 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 r sqlite3_create
24180 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 _function16() mu
24190 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 ltiple.** times
241a0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 with the same fu
241b0 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 nction but with
241c0 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 different values
241d0 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a of eTextRep..**
241e0 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 When multiple i
241f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f mplementations o
24200 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 f the same funct
24210 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c ion are availabl
24220 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c e, SQLite.** wil
24230 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 l pick the one t
24240 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 hat involves the
24250 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 least amount of
24260 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e data conversion
24270 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 ..** If there is
24280 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 only a single i
24290 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 mplementation wh
242a0 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 ich does not car
242b0 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 e what text.** e
242c0 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c ncoding is used,
242d0 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 then the fourth
242e0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 argument should
242f0 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d be [SQLITE_ANY]
24300 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 ..**.** The fift
24310 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 h parameter is a
24320 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e n arbitrary poin
24330 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d ter. The implem
24340 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a entation of the.
24350 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 ** function can
24360 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 gain access to t
24370 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e his pointer usin
24380 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f g [sqlite3_user_
24390 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 data()]..**.** T
243a0 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 he seventh, eigh
243b0 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 th and ninth par
243c0 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 ameters, xFunc,
243d0 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c xStep and xFinal
243e0 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 , are.** pointer
243f0 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 s to C-language
24400 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 functions that i
24410 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c mplement the SQL
24420 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 function or.**
24430 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 aggregate. A sca
24440 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e lar SQL function
24450 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 requires an imp
24460 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
24470 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c he xFunc.** call
24480 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 back only, NULL
24490 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 pointers should
244a0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
244b0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 xStep and xFina
244c0 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e l.** parameters.
244d0 20 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 An aggregate SQ
244e0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 L function requi
244f0 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 res an implement
24500 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a ation of xStep.*
24510 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 * and xFinal and
24520 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 NULL should be
24530 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 passed for xFunc
24540 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 . To delete an e
24550 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 xisting.** SQL f
24560 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 unction or aggre
24570 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 gate, pass NULL
24580 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 for all three fu
24590 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 nction callbacks
245a0 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 ..**.** It is pe
245b0 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 rmitted to regis
245c0 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 ter multiple imp
245d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 lementations of
245e0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 the same.** func
245f0 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 tions with the s
24600 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 ame name but wit
24610 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 h either differi
24620 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a ng numbers of.**
24630 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 arguments or di
24640 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 ffering preferre
24650 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 d text encodings
24660 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 . SQLite will u
24670 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d se.** the implem
24680 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c entation most cl
24690 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 osely matches th
246a0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 e way in which t
246b0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 he.** SQL functi
246c0 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 41 20 66 on is used. A f
246d0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
246e0 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f tation with a no
246f0 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 n-negative.** nA
24700 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 rg parameter is
24710 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 a better match t
24720 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 han a function i
24730 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
24740 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 th.** a negative
24750 20 6e 41 72 67 2e 20 20 41 20 66 75 6e 63 74 69 nArg. A functi
24760 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 on where the pre
24770 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f ferred text enco
24780 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 ding.** matches
24790 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 the database enc
247a0 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 oding is a bette
247b0 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 r.** match than
247c0 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 a function where
247d0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 the encoding is
247e0 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a different. .**
247f0 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 A function wher
24800 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 e the encoding d
24810 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 ifference is bet
24820 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 ween UTF16le and
24830 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 UTF16be.** is a
24840 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 closer match th
24850 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 an a function wh
24860 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 ere the encoding
24870 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a difference is.*
24880 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 * between UTF8 a
24890 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 nd UTF16..**.**
248a0 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f Built-in functio
248b0 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f ns may be overlo
248c0 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c aded by new appl
248d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
248e0 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 functions..** Th
248f0 65 20 66 69 72 73 74 20 61 70 70 6c 69 63 61 74 e first applicat
24900 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
24910 74 69 6f 6e 20 77 69 74 68 20 61 20 67 69 76 65 tion with a give
24920 6e 20 6e 61 6d 65 20 6f 76 65 72 72 69 64 65 73 n name overrides
24930 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e all.** built-in
24940 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 functions in th
24950 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 e same [database
24960 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74 connection] wit
24970 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e h the same name.
24980 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 .** Subsequent a
24990 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
249a0 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 ed functions of
249b0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e the same name on
249c0 6c 79 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 ly override .**
249d0 70 72 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f prior applicatio
249e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
249f0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 61 6e 20 ons that are an
24a00 65 78 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20 exact match for
24a10 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
24a20 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 parameters and
24a30 70 72 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69 preferred encodi
24a40 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70 ng..**.** An app
24a50 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
24a60 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 function is per
24a70 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f mitted to call o
24a80 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 ther.** SQLite i
24a90 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 nterfaces. Howe
24aa0 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 ver, such calls
24ab0 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 must not.** clos
24ac0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 e the database c
24ad0 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 onnection nor fi
24ae0 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 nalize or reset
24af0 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 the prepared.**
24b00 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 statement in whi
24b10 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 ch the function
24b20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a is running..**.*
24b30 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
24b40 2a 2a 20 5b 48 31 36 31 30 33 5d 20 5b 48 31 36 ** [H16103] [H16
24b50 31 30 36 5d 20 5b 48 31 36 31 30 39 5d 20 5b 48 106] [H16109] [H
24b60 31 36 31 31 32 5d 20 5b 48 31 36 31 31 38 5d 20 16112] [H16118]
24b70 5b 48 31 36 31 32 31 5d 20 5b 48 31 36 31 32 37 [H16121] [H16127
24b80 5d 0a 2a 2a 20 5b 48 31 36 31 33 30 5d 20 5b 48 ].** [H16130] [H
24b90 31 36 31 33 33 5d 20 5b 48 31 36 31 33 36 5d 20 16133] [H16136]
24ba0 5b 48 31 36 31 33 39 5d 20 5b 48 31 36 31 34 32 [H16139] [H16142
24bb0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
24bc0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
24bd0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
24be0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 int sqlite3_cre
24bf0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 ate_function(.
24c00 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
24c10 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 onst char *zFunc
24c20 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 tionName,. int
24c30 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 nArg,. int eTex
24c40 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 tRep,. void *pA
24c50 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 pp,. void (*xFu
24c60 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
24c70 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
24c80 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
24c90 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
24ca0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
24cb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
24cc0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
24cd0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
24ce0 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 xt*).);.SQLITE_A
24cf0 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
24d00 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
24d10 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
24d20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
24d30 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 6(. sqlite3 *db
24d40 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a ,. const void *
24d50 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 zFunctionName,.
24d60 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 int nArg,. int
24d70 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 eTextRep,. voi
24d80 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 d *pApp,. void
24d90 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 (*xFunc)(sqlite3
24da0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
24db0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
24dc0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 void (*xStep)(
24dd0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
24de0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
24df0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
24e00 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f xFinal)(sqlite3_
24e10 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a context*).);../*
24e20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 .** CAPI3REF: Te
24e30 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31 xt Encodings {H1
24e40 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c 0267} <S50200> <
24e50 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 H16100>.**.** Th
24e60 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 ese constant def
24e70 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 ine integer code
24e80 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 s that represent
24e90 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 the various.**
24ea0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 text encodings s
24eb0 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 upported by SQLi
24ec0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 te..*/.#define S
24ed0 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 QLITE_UTF8
24ee0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
24ef0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 QLITE_UTF16LE
24f00 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
24f10 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 QLITE_UTF16BE
24f20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
24f30 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 QLITE_UTF16
24f40 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 4 /* Use
24f50 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
24f60 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 er */.#define SQ
24f70 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 LITE_ANY
24f80 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 5 /* sqli
24f90 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
24fa0 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 ion only */.#def
24fb0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
24fc0 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f _ALIGNED 8 /
24fd0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 * sqlite3_create
24fe0 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 _collation only
24ff0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
25000 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 EF: Deprecated F
25010 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 unctions.** DEPR
25020 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 ECATED.**.** The
25030 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 se functions are
25040 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 [deprecated].
25050 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e In order to main
25060 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 tain.** backward
25070 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 s compatibility
25080 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c with older code,
25090 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
250a0 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f continue .** to
250b0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 be supported.
250c0 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 However, new app
250d0 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 lications should
250e0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 avoid.** the us
250f0 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 e of these funct
25100 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 ions. To help e
25110 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 ncourage people
25120 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e to avoid.** usin
25130 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e g these function
25140 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f s, we are not go
25150 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 ing to tell you
25160 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f what they do..*/
25170 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f .#ifndef SQLITE_
25180 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a OMIT_DEPRECATED.
25190 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
251a0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
251b0 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
251c0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
251d0 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 t sqlite3_aggreg
251e0 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 ate_count(sqlite
251f0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 3_context*);.SQL
25200 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
25210 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
25220 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
25230 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 DEPRECATED int s
25240 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 qlite3_expired(s
25250 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 qlite3_stmt*);.S
25260 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
25270 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
25280 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
25290 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
252a0 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 sqlite3_transfe
252b0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 r_bindings(sqlit
252c0 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 e3_stmt*, sqlite
252d0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 3_stmt*);.SQLITE
252e0 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
252f0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
25300 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 E_API SQLITE_DEP
25310 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
25320 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 te3_global_recov
25330 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 er(void);.SQLITE
25340 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
25350 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
25360 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 E_API SQLITE_DEP
25370 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c RECATED void sql
25380 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 ite3_thread_clea
25390 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 nup(void);.SQLIT
253a0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
253b0 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
253c0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 TE_API SQLITE_DE
253d0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c PRECATED int sql
253e0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 ite3_memory_alar
253f0 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c m(void(*)(void*,
25400 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e sqlite3_int64,in
25410 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 t),void*,sqlite3
25420 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a _int64);.#endif.
25430 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
25440 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 Obtaining SQL F
25450 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 unction Paramete
25460 72 20 56 61 6c 75 65 73 20 7b 48 31 35 31 30 30 r Values {H15100
25470 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a } <S20200>.**.**
25480 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 The C-language
25490 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
254a0 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 f SQL functions
254b0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 and aggregates u
254c0 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 ses.** this set
254d0 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 of interface rou
254e0 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 tines to access
254f0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 the parameter va
25500 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 lues on.** the f
25510 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 unction or aggre
25520 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 gate..**.** The
25530 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 xFunc (for scala
25540 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 r functions) or
25550 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 xStep (for aggre
25560 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 gates) parameter
25570 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 s.** to [sqlite3
25580 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
25590 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
255a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
255b0 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 16()].** define
255c0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 callbacks that i
255d0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c mplement the SQL
255e0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 functions and a
255f0 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 ggregates..** Th
25600 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
25610 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 to these callbac
25620 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f ks is an array o
25630 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a f pointers to.**
25640 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
25650 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
25660 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e ts. There is on
25670 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
25680 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 ] object for.**
25690 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 each parameter t
256a0 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 o the SQL functi
256b0 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 on. These routi
256c0 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a nes are used to.
256d0 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 ** extract value
256e0 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 s from the [sqli
256f0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
25700 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ts..**.** These
25710 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e routines work on
25720 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 ly with [protect
25730 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
25740 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e ] objects..** An
25750 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 y attempt to use
25760 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
25770 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 on an [unprotect
25780 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
25790 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 ].** object resu
257a0 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 lts in undefined
257b0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a behavior..**.**
257c0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
257d0 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 work just like t
257e0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
257f0 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 [column access
25800 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 functions].** ex
25810 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 cept that these
25820 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 routines take a
25830 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 single [protect
25840 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
25850 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e ] object.** poin
25860 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 ter instead of a
25870 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d [sqlite3_stmt*]
25880 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 pointer and an
25890 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e integer column n
258a0 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 umber..**.** The
258b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
258c0 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 ext16() interfac
258d0 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 e extracts a UTF
258e0 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e -16 string.** in
258f0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
25900 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f -order of the ho
25910 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 st machine. The
25920 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
25930 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 e_text16be() and
25940 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
25950 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 ext16le() interf
25960 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 aces.** extract
25970 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 UTF-16 strings a
25980 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 s big-endian and
25990 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 little-endian r
259a0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a espectively..**.
259b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 ** The sqlite3_v
259c0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 alue_numeric_typ
259d0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 e() interface at
259e0 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a tempts to apply.
259f0 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e ** numeric affin
25a00 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 ity to the value
25a10 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 . This means th
25a20 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 at an attempt is
25a30 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 .** made to conv
25a40 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f ert the value to
25a50 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 an integer or f
25a60 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 loating point.
25a70 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e If.** such a con
25a80 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 version is possi
25a90 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 ble without loss
25aa0 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 of information
25ab0 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 (in other.** wor
25ac0 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 ds, if the value
25ad0 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 is a string tha
25ae0 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e t looks like a n
25af0 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 umber).** then t
25b00 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 he conversion is
25b10 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 performed. Oth
25b20 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 erwise no conver
25b30 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 sion occurs..**
25b40 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 The [SQLITE_INTE
25b50 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 GER | datatype]
25b60 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e after conversion
25b70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
25b80 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 .** Please pay p
25b90 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 articular attent
25ba0 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 ion to the fact
25bb0 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 that the pointer
25bc0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f returned.** fro
25bd0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 m [sqlite3_value
25be0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 _blob()], [sqlit
25bf0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d e3_value_text()]
25c00 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 , or.** [sqlite3
25c10 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d _value_text16()]
25c20 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 can be invalida
25c30 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 ted by a subsequ
25c40 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b ent call to.** [
25c50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
25c60 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 tes()], [sqlite3
25c70 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 _value_bytes16()
25c80 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
25c90 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 e_text()],.** or
25ca0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
25cb0 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a text16()]..**.**
25cc0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
25cd0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
25ce0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
25cf0 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 ead as.** the SQ
25d00 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 L function that
25d10 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 supplied the [sq
25d20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 lite3_value*] pa
25d30 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 rameters..**.**
25d40 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
25d50 20 5b 48 31 35 31 30 33 5d 20 5b 48 31 35 31 30 [H15103] [H1510
25d60 36 5d 20 5b 48 31 35 31 30 39 5d 20 5b 48 31 35 6] [H15109] [H15
25d70 31 31 32 5d 20 5b 48 31 35 31 31 35 5d 20 5b 48 112] [H15115] [H
25d80 31 35 31 31 38 5d 20 5b 48 31 35 31 32 31 5d 20 15118] [H15121]
25d90 5b 48 31 35 31 32 34 5d 0a 2a 2a 20 5b 48 31 35 [H15124].** [H15
25da0 31 32 37 5d 20 5b 48 31 35 31 33 30 5d 20 5b 48 127] [H15130] [H
25db0 31 35 31 33 33 5d 20 5b 48 31 35 31 33 36 5d 0a 15133] [H15136].
25dc0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 */.SQLITE_API SQ
25dd0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
25de0 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 63 API SQLITE_API c
25df0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
25e00 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 e3_value_blob(sq
25e10 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
25e20 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
25e30 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
25e40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
25e50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 qlite3_value_byt
25e60 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 es(sqlite3_value
25e70 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 *);.SQLITE_API S
25e80 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
25e90 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
25ea0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
25eb0 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 e_bytes16(sqlite
25ec0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
25ed0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
25ee0 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
25ef0 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 TE_API double sq
25f00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 lite3_value_doub
25f10 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 le(sqlite3_value
25f20 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 *);.SQLITE_API S
25f30 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
25f40 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
25f50 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
25f60 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 e_int(sqlite3_va
25f70 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
25f80 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
25f90 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
25fa0 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 PI sqlite3_int64
25fb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 sqlite3_value_i
25fc0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c nt64(sqlite3_val
25fd0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
25fe0 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
25ff0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
26000 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 I const unsigned
26010 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 char *sqlite3_v
26020 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 alue_text(sqlite
26030 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
26040 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
26050 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
26060 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
26070 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
26080 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f _text16(sqlite3_
26090 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
260a0 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
260b0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
260c0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
260d0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
260e0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f ext16le(sqlite3_
260f0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
26100 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
26110 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
26120 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
26130 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
26140 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f ext16be(sqlite3_
26150 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
26160 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
26170 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
26180 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
26190 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 _value_type(sqli
261a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c te3_value*);.SQL
261b0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
261c0 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
261d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
261e0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 ite3_value_numer
261f0 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f ic_type(sqlite3_
26200 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 value*);../*.**
26210 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e CAPI3REF: Obtain
26220 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 Aggregate Funct
26230 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31 36 ion Context {H16
26240 32 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 210} <S20200>.**
26250 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e .** The implemen
26260 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 tation of aggreg
26270 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ate SQL function
26280 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 s use this routi
26290 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a ne to allocate.*
262a0 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f * a structure fo
262b0 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 r storing their
262c0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 state..**.** The
262d0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 first time the
262e0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
262f0 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 e_context() rout
26300 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 66 6f ine is called fo
26310 72 20 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 r a.** particula
26320 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c r aggregate, SQL
26330 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 ite allocates nB
26340 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 ytes of memory,
26350 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 0a zeroes out that.
26360 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 ** memory, and r
26370 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
26380 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e to it. On secon
26390 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 d and subsequent
263a0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c calls to.** sql
263b0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
263c0 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 ontext() for the
263d0 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 same aggregate
263e0 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a function index,.
263f0 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 ** the same buff
26400 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 er is returned.
26410 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 The implementati
26420 6f 6e 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 on of the aggreg
26430 61 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74 ate can use.** t
26440 68 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 he returned buff
26450 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 er to accumulate
26460 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c data..**.** SQL
26470 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ite automaticall
26480 79 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f y frees the allo
26490 63 61 74 65 64 20 62 75 66 66 65 72 20 77 68 65 cated buffer whe
264a0 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a n the aggregate.
264b0 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 ** query conclud
264c0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 es..**.** The fi
264d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68 rst parameter sh
264e0 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f ould be a copy o
264f0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
26500 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 3_context | SQL
26510 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 function context
26520 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 ] that is the fi
26530 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a rst parameter.**
26540 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
26550 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d routine that im
26560 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 plements the agg
26570 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e regate function.
26580 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
26590 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c ine must be call
265a0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 ed from the same
265b0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 thread in which
265c0 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 .** the aggregat
265d0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 e SQL function i
265e0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a s running..**.**
265f0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
26600 2a 20 5b 48 31 36 32 31 31 5d 20 5b 48 31 36 32 * [H16211] [H162
26610 31 33 5d 20 5b 48 31 36 32 31 35 5d 20 5b 48 31 13] [H16215] [H1
26620 36 32 31 37 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 6217].*/.SQLITE_
26630 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
26640 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
26650 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 _API void *sqlit
26660 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
26670 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e text(sqlite3_con
26680 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 text*, int nByte
26690 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 s);../*.** CAPI3
266a0 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 REF: User Data F
266b0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 or Functions {H1
266c0 36 32 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 6240} <S20200>.*
266d0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
266e0 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 _user_data() int
266f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
26700 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
26710 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 pointer that was
26720 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 the pUserData p
26730 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 arameter (the 5t
26740 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 h parameter).**
26750 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
26760 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
26770 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 )].** and [sqlit
26780 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
26790 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 on16()] routines
267a0 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 that originally
267b0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 .** registered t
267c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
267d0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
267e0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 {END}.**.** Thi
267f0 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 s routine must b
26800 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
26810 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e e same thread in
26820 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 which.** the ap
26830 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
26840 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 d function is ru
26850 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 nning..**.** Req
26860 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
26870 31 36 32 34 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 16243].*/.SQLITE
26880 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
26890 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
268a0 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 E_API void *sqli
268b0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 te3_user_data(sq
268c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
268d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
268e0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 : Database Conne
268f0 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 ction For Functi
26900 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20 3c 53 36 ons {H16250} <S6
26910 30 36 30 30 3e 3c 53 32 30 32 30 30 3e 0a 2a 2a 0600><S20200>.**
26920 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
26930 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c context_db_handl
26940 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 e() interface re
26950 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a turns a copy of.
26960 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 ** the pointer t
26970 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 o the [database
26980 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 connection] (the
26990 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 1st parameter).
269a0 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
269b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
269c0 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 on()].** and [sq
269d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
269e0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 ction16()] routi
269f0 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 nes that origina
26a00 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 lly.** registere
26a10 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f d the applicatio
26a20 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n defined functi
26a30 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 on..**.** Requir
26a40 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 ements:.** [H162
26a50 35 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 53].*/.SQLITE_AP
26a60 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
26a70 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
26a80 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 PI sqlite3 *sqli
26a90 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 te3_context_db_h
26aa0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f andle(sqlite3_co
26ab0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ntext*);../*.**
26ac0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 CAPI3REF: Functi
26ad0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 on Auxiliary Dat
26ae0 61 20 7b 48 31 36 32 37 30 7d 20 3c 53 32 30 32 a {H16270} <S202
26af0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 00>.**.** The fo
26b00 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 llowing two func
26b10 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 tions may be use
26b20 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 d by scalar SQL
26b30 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 functions to.**
26b40 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 associate metada
26b50 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 ta with argument
26b60 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 values. If the
26b70 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 same value is pa
26b80 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 ssed to.** multi
26b90 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 ple invocations
26ba0 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 of the same SQL
26bb0 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 function during
26bc0 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c query execution,
26bd0 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 under.** some c
26be0 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 ircumstances the
26bf0 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 associated meta
26c00 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 data may be pres
26c10 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a erved. This may.
26c20 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 ** be used, for
26c30 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 example, to add
26c40 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 a regular-expres
26c50 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 sion matching sc
26c60 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e alar.** function
26c70 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 . The compiled v
26c80 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 ersion of the re
26c90 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e gular expression
26ca0 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a is stored as.**
26cb0 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 metadata associ
26cc0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 ated with the SQ
26cd0 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 L value passed a
26ce0 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 s the regular ex
26cf0 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 pression.** patt
26d00 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c ern. The compil
26d10 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 ed regular expre
26d20 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 ssion can be reu
26d30 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a sed on multiple.
26d40 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f ** invocations o
26d50 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 f the same funct
26d60 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 ion so that the
26d70 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e original pattern
26d80 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 string.** does
26d90 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 not need to be r
26da0 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 ecompiled on eac
26db0 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a h invocation..**
26dc0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
26dd0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e get_auxdata() in
26de0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
26df0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
26e00 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 metadata.** ass
26e10 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 ociated by the s
26e20 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
26e30 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 ta() function wi
26e40 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d th the Nth argum
26e50 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 ent.** value to
26e60 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
26e70 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
26e80 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 . If no metadata
26e90 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a has been ever.*
26ea0 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 * been set for t
26eb0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 he Nth argument
26ec0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c of the function,
26ed0 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 or if the corre
26ee0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 sponding.** func
26ef0 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 tion parameter h
26f00 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 as changed since
26f10 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 the meta-data w
26f20 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 as set,.** then
26f30 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
26f40 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 ata() returns a
26f50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
26f60 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
26f70 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e set_auxdata() in
26f80 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 terface saves th
26f90 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f e metadata.** po
26fa0 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 inted to by its
26fb0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 3rd parameter as
26fc0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f the metadata fo
26fd0 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 r the N-th.** ar
26fe0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 gument of the ap
26ff0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
27000 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 d function. Sub
27010 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 sequent.** calls
27020 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f to sqlite3_get_
27030 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 auxdata() might
27040 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 return this data
27050 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e , if it has.** n
27060 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 ot been destroye
27070 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69 73 20 6e d..** If it is n
27080 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 ot NULL, SQLite
27090 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 will invoke the
270a0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 destructor.** fu
270b0 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 nction given by
270c0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
270d0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 r to sqlite3_set
270e0 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a _auxdata() on.**
270f0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 the metadata wh
27100 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e en the correspon
27110 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 ding function pa
27120 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a rameter changes.
27130 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 ** or when the S
27140 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d QL statement com
27150 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 pletes, whicheve
27160 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a r comes first..*
27170 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 *.** SQLite is f
27180 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 ree to call the
27190 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 destructor and d
271a0 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 rop metadata on
271b0 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 any.** parameter
271c0 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e of any function
271d0 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54 at any time. T
271e0 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 he only guarante
271f0 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 e is that.** the
27200 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c destructor will
27210 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 be called befor
27220 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 e the metadata i
27230 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a s dropped..**.**
27240 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 In practice, me
27250 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 tadata is preser
27260 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 ved between func
27270 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a tion calls for.*
27280 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 * expressions th
27290 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 at are constant
272a0 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e at compile time.
272b0 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c This includes l
272c0 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 iteral.** values
272d0 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c and SQL variabl
272e0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 es..**.** These
272f0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 routines must be
27300 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
27310 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 same thread in
27320 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c which.** the SQL
27330 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e function is run
27340 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 ning..**.** Requ
27350 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
27360 36 32 37 32 5d 20 5b 48 31 36 32 37 34 5d 20 5b 6272] [H16274] [
27370 48 31 36 32 37 36 5d 20 5b 48 31 36 32 37 37 5d H16276] [H16277]
27380 20 5b 48 31 36 32 37 38 5d 20 5b 48 31 36 32 37 [H16278] [H1627
27390 39 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 9].*/.SQLITE_API
273a0 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
273b0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
273c0 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f I void *sqlite3_
273d0 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 get_auxdata(sqli
273e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
273f0 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 t N);.SQLITE_API
27400 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
27410 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
27420 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 I void sqlite3_s
27430 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 et_auxdata(sqlit
27440 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
27450 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 N, void*, void
27460 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f (*)(void*));.../
27470 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
27480 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e onstants Definin
27490 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 g Special Destru
274a0 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20 7b 48 ctor Behavior {H
274b0 31 30 32 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a 10280} <S30100>.
274c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 **.** These are
274d0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 special values f
274e0 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f or the destructo
274f0 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 r that is passed
27500 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 in as the.** fi
27510 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 nal argument to
27520 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 routines like [s
27530 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
27540 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 ob()]. If the d
27550 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 estructor.** arg
27560 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f ument is SQLITE_
27570 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 STATIC, it means
27580 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e that the conten
27590 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e t pointer is con
275a0 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c stant.** and wil
275b0 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 l never change.
275c0 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 It does not nee
275d0 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 d to be destroye
275e0 64 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 d. The.** SQLIT
275f0 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 E_TRANSIENT valu
27600 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 e means that the
27610 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 content will li
27620 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a kely change in.*
27630 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 * the near futur
27640 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 e and that SQLit
27650 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 e should make it
27660 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f s own private co
27670 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e py of.** the con
27680 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 tent before retu
27690 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 rning..**.** The
276a0 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 typedef is nece
276b0 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 ssary to work ar
276c0 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e ound problems in
276d0 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 certain.** C++
276e0 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 compilers. See
276f0 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f ticket #2191..*/
27700 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a .typedef void (*
27710 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
27720 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b or_type)(void*);
27730 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
27740 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 STATIC ((sq
27750 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 lite3_destructor
27760 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 _type)0).#define
27770 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e SQLITE_TRANSIEN
27780 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 T ((sqlite3_de
27790 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 structor_type)-1
277a0 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 )../*.** CAPI3RE
277b0 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 F: Setting The R
277c0 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 esult Of An SQL
277d0 46 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34 30 30 Function {H16400
277e0 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a } <S20200>.**.**
277f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
27800 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 are used by the
27810 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 xFunc or xFinal
27820 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a callbacks that.*
27830 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 * implement SQL
27840 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 functions and ag
27850 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a gregates. See.*
27860 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 * [sqlite3_creat
27870 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e e_function()] an
27880 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
27890 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a e_function16()].
278a0 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 ** for additiona
278b0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
278c0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
278d0 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d ions work very m
278e0 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 uch like the [pa
278f0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d rameter binding]
27900 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 family of.** fu
27910 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 nctions used to
27920 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 bind values to h
27930 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 ost parameters i
27940 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 n prepared state
27950 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 ments..** Refer
27960 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 to the [SQL para
27970 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 meter] documenta
27980 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f tion for additio
27990 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
279a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
279b0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 e3_result_blob()
279c0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
279d0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a the result from.
279e0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f ** an applicatio
279f0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
27a00 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f on to be the BLO
27a10 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 B whose content
27a20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f is pointed.** to
27a30 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 by the second p
27a40 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 arameter and whi
27a50 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f ch is N bytes lo
27a60 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 ng where N is th
27a70 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d e.** third param
27a80 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eter..**.** The
27a90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a sqlite3_result_z
27aa0 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 eroblob() interf
27ab0 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 aces set the res
27ac0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 ult of.** the ap
27ad0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
27ae0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
27af0 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 a BLOB containi
27b00 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 ng all zero.** b
27b10 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 ytes and N bytes
27b20 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 in size, where
27b30 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f N is the value o
27b40 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 f the 2nd parame
27b50 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ter..**.** The s
27b60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f qlite3_result_do
27b70 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 uble() interface
27b80 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 sets the result
27b90 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c from.** an appl
27ba0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
27bb0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
27bc0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
27bd0 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a value specified.
27be0 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 ** by its 2nd ar
27bf0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 gument..**.** Th
27c00 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
27c10 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c _error() and sql
27c20 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
27c30 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a r16() functions.
27c40 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 ** cause the imp
27c50 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e lemented SQL fun
27c60 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 ction to throw a
27c70 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 n exception..**
27c80 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 SQLite uses the
27c90 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 string pointed t
27ca0 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 o by the.** 2nd
27cb0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c parameter of sql
27cc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
27cd0 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 r() or sqlite3_r
27ce0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a esult_error16().
27cf0 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f ** as the text o
27d00 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 f an error messa
27d10 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65 ge. SQLite inte
27d20 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 rprets the error
27d30 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 .** message stri
27d40 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ng from sqlite3_
27d50 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 result_error() a
27d60 73 20 55 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a s UTF-8. SQLite.
27d70 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 ** interprets th
27d80 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 e string from sq
27d90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
27da0 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 or16() as UTF-16
27db0 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 in native.** by
27dc0 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68 te order. If th
27dd0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
27de0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 r to sqlite3_res
27df0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f ult_error().** o
27e00 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
27e10 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 _error16() is ne
27e20 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 gative then SQLi
27e30 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 te takes as the
27e40 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 error.** message
27e50 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 all text up thr
27e60 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a ough the first z
27e70 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a ero character..*
27e80 2a 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 * If the third p
27e90 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
27ea0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
27eb0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 () or.** sqlite3
27ec0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
27ed0 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 ) is non-negativ
27ee0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 e then SQLite ta
27ef0 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a kes that many.**
27f00 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 bytes (not char
27f10 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 acters) from the
27f20 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 2nd parameter a
27f30 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 s the error mess
27f40 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 age..** The sqli
27f50 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
27f60 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 () and sqlite3_r
27f70 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a esult_error16().
27f80 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 ** routines make
27f90 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 a private copy
27fa0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 of the error mes
27fb0 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 sage text before
27fc0 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e .** they return.
27fd0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c Hence, the cal
27fe0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 ling function ca
27ff0 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a n deallocate or.
28000 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 ** modify the te
28010 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 xt after they re
28020 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 turn without har
28030 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 m..** The sqlite
28040 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 3_result_error_c
28050 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 ode() function c
28060 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 hanges the error
28070 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 code.** returne
28080 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 d by SQLite as a
28090 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 result of an er
280a0 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f ror in a functio
280b0 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a n. By default,.
280c0 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 ** the error cod
280d0 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f e is SQLITE_ERRO
280e0 52 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e 74 R. A subsequent
280f0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
28100 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a _result_error().
28110 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ** or sqlite3_re
28120 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 sult_error16() r
28130 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 esets the error
28140 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 code to SQLITE_E
28150 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 RROR..**.** The
28160 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
28170 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 oobig() interfac
28180 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 e causes SQLite
28190 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f to throw an erro
281a0 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 r.** indicating
281b0 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 that a string or
281c0 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 BLOB is to long
281d0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a to represent..*
281e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
281f0 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 _result_nomem()
28200 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 interface causes
28210 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 SQLite to throw
28220 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 an error.** ind
28230 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d icating that a m
28240 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
28250 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 failed..**.** T
28260 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
28270 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 t_int() interfac
28280 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 e sets the retur
28290 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 n value.** of th
282a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
282b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
282c0 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 o be the 32-bit
282d0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a signed integer.*
282e0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e * value given in
282f0 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e the 2nd argumen
28300 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 t..** The sqlite
28310 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 3_result_int64()
28320 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
28330 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
28340 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 .** of the appli
28350 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
28360 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 unction to be th
28370 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 e 64-bit signed
28380 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 integer.** value
28390 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e given in the 2n
283a0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a d argument..**.*
283b0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
283c0 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 sult_null() inte
283d0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
283e0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f eturn value.** o
283f0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
28400 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
28410 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a on to be NULL..*
28420 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
28430 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 _result_text(),
28440 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
28450 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 ext16(),.** sqli
28460 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
28470 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 6le(), and sqlit
28480 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
28490 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a be() interfaces.
284a0 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 ** set the retur
284b0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 n value of the a
284c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
284d0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
284e0 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 e.** a text stri
284f0 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 ng which is repr
28500 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 esented as UTF-8
28510 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 , UTF-16 native
28520 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 byte order,.** U
28530 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 TF-16 little end
28540 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 ian, or UTF-16 b
28550 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 ig endian, respe
28560 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 ctively..** SQLi
28570 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 te takes the tex
28580 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 t result from th
28590 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 e application fr
285a0 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 om.** the 2nd pa
285b0 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 rameter of the s
285c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
285d0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a xt* interfaces..
285e0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 ** If the 3rd pa
285f0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
28600 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
28610 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a xt* interfaces.*
28620 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 * is negative, t
28630 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 hen SQLite takes
28640 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f result text fro
28650 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 m the 2nd parame
28660 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 ter.** through t
28670 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 he first zero ch
28680 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 aracter..** If t
28690 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 he 3rd parameter
286a0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
286b0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
286c0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f erfaces.** is no
286d0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e n-negative, then
286e0 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 as many bytes (
286f0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 not characters)
28700 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 of the text.** p
28710 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 ointed to by the
28720 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 2nd parameter a
28730 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 re taken as the
28740 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
28750 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ned.** function
28760 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 result..** If th
28770 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
28780 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
28790 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
287a0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c rfaces.** or sql
287b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
287c0 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 is a non-NULL p
287d0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c ointer, then SQL
287e0 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a ite calls that.*
287f0 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 * function as th
28800 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 e destructor on
28810 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 the text or BLOB
28820 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 result when it
28830 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 has.** finished
28840 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c using that resul
28850 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 t..** If the 4th
28860 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
28870 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
28880 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
28890 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f s or.** sqlite3_
288a0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 result_blob is t
288b0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 he special const
288c0 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 ant SQLITE_STATI
288d0 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a C, then SQLite.*
288e0 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 * assumes that t
288f0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 he text or BLOB
28900 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e result is in con
28910 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 stant space and
28920 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 does not.** copy
28930 20 74 68 65 20 69 74 20 6f 72 20 63 61 6c 6c 20 the it or call
28940 61 20 64 65 73 74 72 75 63 74 6f 72 20 77 68 65 a destructor whe
28950 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 n it has finishe
28960 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 d using that res
28970 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 ult..** If the 4
28980 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
28990 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
289a0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
289b0 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 ces.** or sqlite
289c0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 3_result_blob is
289d0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e the special con
289e0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 stant SQLITE_TRA
289f0 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 NSIENT.** then S
28a00 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f QLite makes a co
28a10 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 py of the result
28a20 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 into space obta
28a30 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f ined from.** fro
28a40 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
28a50 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 c()] before it r
28a60 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 eturns..**.** Th
28a70 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
28a80 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 _value() interfa
28a90 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 ce sets the resu
28aa0 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 lt of.** the app
28ab0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
28ac0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
28ad0 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 a copy the.** [u
28ae0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
28af0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
28b00 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
28b10 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e e 2nd parameter.
28b20 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 The.** sqlite3
28b30 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
28b40 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 interface makes
28b50 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 a copy of the [s
28b60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
28b70 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 so that the [sq
28b80 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 lite3_value] spe
28b90 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 cified in the pa
28ba0 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e rameter may chan
28bb0 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c ge or.** be deal
28bc0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 located after sq
28bd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
28be0 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 ue() returns wit
28bf0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 hout harm..** A
28c00 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
28c10 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
28c20 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 may always be u
28c30 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 sed where an.**
28c40 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
28c50 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
28c60 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 ct is required,
28c70 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e so either.** kin
28c80 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 d of [sqlite3_va
28c90 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 lue] object can
28ca0 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 be used with thi
28cb0 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a s interface..**.
28cc0 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 ** If these rout
28cd0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
28ce0 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 from within the
28cf0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
28d00 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 .** than the one
28d10 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
28d20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
28d30 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 ned function tha
28d40 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 t received.** th
28d50 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 e [sqlite3_conte
28d60 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 xt] pointer, the
28d70 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
28d80 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 efined..**.** Re
28d90 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
28da0 48 31 36 34 30 33 5d 20 5b 48 31 36 34 30 36 5d H16403] [H16406]
28db0 20 5b 48 31 36 34 30 39 5d 20 5b 48 31 36 34 31 [H16409] [H1641
28dc0 32 5d 20 5b 48 31 36 34 31 35 5d 20 5b 48 31 36 2] [H16415] [H16
28dd0 34 31 38 5d 20 5b 48 31 36 34 32 31 5d 20 5b 48 418] [H16421] [H
28de0 31 36 34 32 34 5d 0a 2a 2a 20 5b 48 31 36 34 32 16424].** [H1642
28df0 37 5d 20 5b 48 31 36 34 33 30 5d 20 5b 48 31 36 7] [H16430] [H16
28e00 34 33 33 5d 20 5b 48 31 36 34 33 36 5d 20 5b 48 433] [H16436] [H
28e10 31 36 34 33 39 5d 20 5b 48 31 36 34 34 32 5d 20 16439] [H16442]
28e20 5b 48 31 36 34 34 35 5d 20 5b 48 31 36 34 34 38 [H16445] [H16448
28e30 5d 0a 2a 2a 20 5b 48 31 36 34 35 31 5d 20 5b 48 ].** [H16451] [H
28e40 31 36 34 35 34 5d 20 5b 48 31 36 34 35 37 5d 20 16454] [H16457]
28e50 5b 48 31 36 34 36 30 5d 20 5b 48 31 36 34 36 33 [H16460] [H16463
28e60 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
28e70 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
28e80 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
28e90 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 void sqlite3_re
28ea0 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 sult_blob(sqlite
28eb0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
28ec0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f t void*, int, vo
28ed0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 id(*)(void*));.S
28ee0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
28ef0 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
28f00 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
28f10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 sqlite3_result_d
28f20 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f ouble(sqlite3_co
28f30 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b ntext*, double);
28f40 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
28f50 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
28f60 49 20 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 I SQLITE_API voi
28f70 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
28f80 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 _error(sqlite3_c
28f90 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 ontext*, const c
28fa0 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 har*, int);.SQLI
28fb0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
28fc0 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
28fd0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
28fe0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
28ff0 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 r16(sqlite3_cont
29000 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ext*, const void
29010 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f *, int);.SQLITE_
29020 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
29030 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
29040 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 _API void sqlite
29050 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 3_result_error_t
29060 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f oobig(sqlite3_co
29070 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f ntext*);.SQLITE_
29080 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
29090 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
290a0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 _API void sqlite
290b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 3_result_error_n
290c0 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e omem(sqlite3_con
290d0 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 text*);.SQLITE_A
290e0 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
290f0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
29100 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
29110 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f _result_error_co
29120 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 de(sqlite3_conte
29130 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 xt*, int);.SQLIT
29140 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
29150 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
29160 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
29170 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 te3_result_int(s
29180 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
29190 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 int);.SQLITE_AP
291a0 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
291b0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
291c0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
291d0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c result_int64(sql
291e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 ite3_context*, s
291f0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 qlite3_int64);.S
29200 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
29210 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
29220 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
29230 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e sqlite3_result_n
29240 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ull(sqlite3_cont
29250 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ext*);.SQLITE_AP
29260 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
29270 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
29280 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
29290 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 result_text(sqli
292a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
292b0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 nst char*, int,
292c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
292d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
292e0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
292f0 49 20 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 I SQLITE_API voi
29300 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
29310 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f _text16(sqlite3_
29320 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
29330 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 void*, int, void
29340 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c (*)(void*));.SQL
29350 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
29360 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
29370 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
29380 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
29390 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f t16le(sqlite3_co
293a0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f ntext*, const vo
293b0 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 id*, int,void(*)
293c0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 (void*));.SQLITE
293d0 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
293e0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
293f0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
29400 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
29410 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 be(sqlite3_conte
29420 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
29430 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f , int,void(*)(vo
29440 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 id*));.SQLITE_AP
29450 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
29460 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
29470 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
29480 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c result_value(sql
29490 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 ite3_context*, s
294a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
294b0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
294c0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
294d0 20 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 SQLITE_API void
294e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
294f0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 zeroblob(sqlite3
29500 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e _context*, int n
29510 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
29520 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 EF: Define New C
29530 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 ollating Sequenc
29540 65 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 es {H16600} <S20
29550 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 300>.**.** These
29560 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 functions are u
29570 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 sed to add new c
29580 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
29590 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 es to the.** [da
295a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
295b0 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 n] specified as
295c0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
295d0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 nt..**.** The na
295e0 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f me of the new co
295f0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
29600 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73 is specified as
29610 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a a UTF-8 string.
29620 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 ** for sqlite3_c
29630 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 reate_collation(
29640 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 ) and sqlite3_cr
29650 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
29660 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2().** and a UTF
29670 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 -16 string for s
29680 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
29690 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 llation16(). In
296a0 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 all cases.** the
296b0 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 name is passed
296c0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 as the second fu
296d0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e nction argument.
296e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 .**.** The third
296f0 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 argument may be
29700 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 one of the cons
29710 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 tants [SQLITE_UT
29720 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f F8],.** [SQLITE_
29730 55 54 46 31 36 4c 45 5d 2c 20 6f 72 20 5b 53 51 UTF16LE], or [SQ
29740 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 LITE_UTF16BE], i
29750 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 ndicating that t
29760 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 he user-supplied
29770 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 .** routine expe
29780 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 cts to be passed
29790 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
297a0 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 ings encoded usi
297b0 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 ng UTF-8,.** UTF
297c0 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 -16 little-endia
297d0 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 n, or UTF-16 big
297e0 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 -endian, respect
297f0 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 ively. The.** th
29800 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 ird argument mig
29810 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 ht also be [SQLI
29820 54 45 5f 55 54 46 31 36 5d 20 74 6f 20 69 6e 64 TE_UTF16] to ind
29830 69 63 61 74 65 20 74 68 61 74 20 74 68 65 20 72 icate that the r
29840 6f 75 74 69 6e 65 0a 2a 2a 20 65 78 70 65 63 74 outine.** expect
29850 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 62 65 s pointers to be
29860 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 UTF-16 strings
29870 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
29880 74 65 20 6f 72 64 65 72 2c 20 6f 72 20 74 68 65 te order, or the
29890 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 63 61 6e .** argument can
298a0 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 be [SQLITE_UTF1
298b0 36 5f 41 4c 49 47 4e 45 44 5d 20 69 66 20 74 68 6_ALIGNED] if th
298c0 65 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 e.** the routine
298d0 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 expects pointer
298e0 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 s to 16-bit word
298f0 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 aligned strings
29900 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e .** of UTF-16 in
29910 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
29920 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 order..**.** A
29930 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 pointer to the u
29940 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 ser supplied rou
29950 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 tine must be pas
29960 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68 sed as the fifth
29970 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 .** argument. I
29980 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 f it is NULL, th
29990 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 is is the same a
299a0 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 s deleting the c
299b0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 ollation.** sequ
299c0 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 ence (so that SQ
299d0 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c Lite cannot call
299e0 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a it anymore)..**
299f0 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 Each time the a
29a00 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c pplication suppl
29a10 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ied function is
29a20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 invoked, it is p
29a30 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 assed.** as its
29a40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
29a50 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f a copy of the vo
29a60 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 id* passed as th
29a70 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e e fourth argumen
29a80 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f t.** to sqlite3_
29a90 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
29aa0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 () or sqlite3_cr
29ab0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 eate_collation16
29ac0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 ()..**.** The re
29ad0 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 maining argument
29ae0 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 s to the applica
29af0 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f tion-supplied ro
29b00 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 utine are two st
29b10 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 rings,.** each r
29b20 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 epresented by a
29b30 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 (length, data) p
29b40 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 air and encoded
29b50 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a in the encoding.
29b60 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73 ** that was pass
29b70 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 ed as the third
29b80 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 argument when th
29b90 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 e collation sequ
29ba0 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 ence was.** regi
29bb0 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54 stered. {END} T
29bc0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
29bd0 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e efined collation
29be0 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a routine should.
29bf0 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 ** return negati
29c00 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 ve, zero or posi
29c10 74 69 76 65 20 69 66 20 74 68 65 20 66 69 72 73 tive if the firs
29c20 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 t string is less
29c30 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 than,.** equal
29c40 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 to, or greater t
29c50 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73 han the second s
29c60 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 tring. i.e. (STR
29c70 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e ING1 - STRING2).
29c80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
29c90 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
29ca0 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c ion_v2() works l
29cb0 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 ike sqlite3_crea
29cc0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a te_collation().*
29cd0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 * except that it
29ce0 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 takes an extra
29cf0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
29d00 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 s a destructor f
29d10 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 or.** the collat
29d20 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75 ion. The destru
29d30 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 ctor is called w
29d40 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f hen the collatio
29d50 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 n is.** destroye
29d60 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 d and is passed
29d70 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f a copy of the fo
29d80 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 urth parameter v
29d90 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 oid* pointer.**
29da0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 of the sqlite3_c
29db0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
29dc0 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 v2()..** Collati
29dd0 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 ons are destroye
29de0 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 d when they are
29df0 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 overridden by la
29e00 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 ter calls to the
29e10 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 .** collation cr
29e20 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 eation functions
29e30 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61 or when the [da
29e40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
29e50 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 n] is closed.**
29e60 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 using [sqlite3_c
29e70 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 lose()]..**.** S
29e80 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 ee also: [sqlit
29e90 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
29ea0 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ded()] and [sqli
29eb0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
29ec0 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a eded16()]..**.**
29ed0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
29ee0 2a 20 5b 48 31 36 36 30 33 5d 20 5b 48 31 36 36 * [H16603] [H166
29ef0 30 34 5d 20 5b 48 31 36 36 30 36 5d 20 5b 48 31 04] [H16606] [H1
29f00 36 36 30 39 5d 20 5b 48 31 36 36 31 32 5d 20 5b 6609] [H16612] [
29f10 48 31 36 36 31 35 5d 20 5b 48 31 36 36 31 38 5d H16615] [H16618]
29f20 20 5b 48 31 36 36 32 31 5d 0a 2a 2a 20 5b 48 31 [H16621].** [H1
29f30 36 36 32 34 5d 20 5b 48 31 36 36 32 37 5d 20 5b 6624] [H16627] [
29f40 48 31 36 36 33 30 5d 0a 2a 2f 0a 53 51 4c 49 54 H16630].*/.SQLIT
29f50 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
29f60 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
29f70 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
29f80 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
29f90 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c ion(. sqlite3*,
29fa0 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a . const char *
29fb0 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 zName, . int eT
29fc0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a extRep, . void*
29fd0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 ,. int(*xCompar
29fe0 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e e)(void*,int,con
29ff0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e st void*,int,con
2a000 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c st void*).);.SQL
2a010 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
2a020 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
2a030 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2a040 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
2a050 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 ation_v2(. sqli
2a060 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 te3*, . const c
2a070 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 har *zName, . i
2a080 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 nt eTextRep, .
2a090 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 void*,. int(*xC
2a0a0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e ompare)(void*,in
2a0b0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e t,const void*,in
2a0c0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a t,const void*),.
2a0d0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 void(*xDestroy
2a0e0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 )(void*).);.SQLI
2a0f0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
2a100 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
2a110 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
2a120 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
2a130 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 tion16(. sqlite
2a140 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 3*, . const voi
2a150 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 d *zName,. int
2a160 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 eTextRep, . voi
2a170 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 d*,. int(*xComp
2a180 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 are)(void*,int,c
2a190 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 onst void*,int,c
2a1a0 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a onst void*).);..
2a1b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2a1c0 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 Collation Needed
2a1d0 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37 Callbacks {H167
2a1e0 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 00} <S20300>.**.
2a1f0 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 ** To avoid havi
2a200 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 ng to register a
2a210 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 ll collation seq
2a220 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 uences before a
2a230 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 database.** can
2a240 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c be used, a singl
2a250 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
2a260 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 ion may be regis
2a270 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a tered with the.*
2a280 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
2a290 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61 ection] to be ca
2a2a0 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e lled whenever an
2a2b0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 undefined colla
2a2c0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 tion.** sequence
2a2d0 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a is required..**
2a2e0 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 .** If the funct
2a2f0 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 ion is registere
2a300 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 d using the sqli
2a310 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
2a320 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 eded() API,.** t
2a330 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 hen it is passed
2a340 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e the names of un
2a350 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f defined collatio
2a360 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 n sequences as s
2a370 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 trings.** encode
2a380 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36 d in UTF-8. {H16
2a390 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 703} If sqlite3_
2a3a0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
2a3b0 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 16() is used,.**
2a3c0 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 the names are p
2a3d0 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 assed as UTF-16
2a3e0 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 in machine nativ
2a3f0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a e byte order..**
2a400 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 A call to eithe
2a410 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 r function repla
2a420 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 ces any existing
2a430 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a callback..**.**
2a440 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 When the callba
2a450 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 ck is invoked, t
2a460 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2a470 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f t passed is a co
2a480 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 py.** of the sec
2a490 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
2a4a0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
2a4b0 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a n_needed() or.**
2a4c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
2a4d0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 on_needed16().
2a4e0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
2a4f0 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 ent is the datab
2a500 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
2a510 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 n. The third ar
2a520 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 gument is one of
2a530 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 [SQLITE_UTF8],
2a540 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d [SQLITE_UTF16BE]
2a550 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f ,.** or [SQLITE_
2a560 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 UTF16LE], indica
2a570 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 ting the most de
2a580 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 sirable form of
2a590 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a the collation.**
2a5a0 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 sequence functi
2a5b0 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 on required. Th
2a5c0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
2a5d0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f er is the name o
2a5e0 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 f the.** require
2a5f0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 d collation sequ
2a600 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ence..**.** The
2a610 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
2a620 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 n should registe
2a630 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f r the desired co
2a640 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a llation using.**
2a650 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
2a660 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b _collation()], [
2a670 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
2a680 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f ollation16()], o
2a690 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 r.** [sqlite3_cr
2a6a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
2a6b0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 2()]..**.** Requ
2a6c0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
2a6d0 36 37 30 32 5d 20 5b 48 31 36 37 30 34 5d 20 5b 6702] [H16704] [
2a6e0 48 31 36 37 30 36 5d 0a 2a 2f 0a 53 51 4c 49 54 H16706].*/.SQLIT
2a6f0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
2a700 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
2a710 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2a720 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
2a730 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c ded(. sqlite3*,
2a740 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f . void*, . vo
2a750 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 id(*)(void*,sqli
2a760 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 te3*,int eTextRe
2a770 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 p,const char*).)
2a780 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c ;.SQLITE_API SQL
2a790 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
2a7a0 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e PI SQLITE_API in
2a7b0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 t sqlite3_collat
2a7c0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 ion_needed16(.
2a7d0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 sqlite3*, . voi
2a7e0 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f d*,. void(*)(vo
2a7f0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 id*,sqlite3*,int
2a800 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 eTextRep,const
2a810 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a void*).);../*.**
2a820 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 Specify the key
2a830 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 for an encrypte
2a840 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 d database. Thi
2a850 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 s routine should
2a860 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 be.** called ri
2a870 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 ght after sqlite
2a880 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 3_open()..**.**
2a890 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c The code to impl
2a8a0 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 ement this API i
2a8b0 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 s not available
2a8c0 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 in the public re
2a8d0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 lease.** of SQLi
2a8e0 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 te..*/.SQLITE_AP
2a8f0 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
2a900 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
2a910 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b PI int sqlite3_k
2a920 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 ey(. sqlite3 *d
2a930 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 b,
2a940 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
2a950 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a to be rekeyed *
2a960 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
2a970 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 pKey, int nKey
2a980 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f /* The key */
2a990 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 .);../*.** Chang
2a9a0 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 e the key on an
2a9b0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 open database.
2a9c0 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 If the current d
2a9d0 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a atabase is not.*
2a9e0 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 * encrypted, thi
2a9f0 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 s routine will e
2aa00 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 ncrypt it. If p
2aa10 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d New==0 or nNew==
2aa20 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 0, the.** databa
2aa30 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e se is decrypted.
2aa40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 .**.** The code
2aa50 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 to implement thi
2aa60 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 s API is not ava
2aa70 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 ilable in the pu
2aa80 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 blic release.**
2aa90 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 of SQLite..*/.SQ
2aaa0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
2aab0 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
2aac0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
2aad0 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 lite3_rekey(. s
2aae0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
2aaf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2ab00 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 Database to be
2ab10 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e rekeyed */. con
2ab20 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 st void *pKey, i
2ab30 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 nt nKey /* T
2ab40 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b he new key */.);
2ab50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2ab60 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 : Suspend Execut
2ab70 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 ion For A Short
2ab80 54 69 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c 53 Time {H10530} <S
2ab90 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 40410>.**.** The
2aba0 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 sqlite3_sleep()
2abb0 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 function causes
2abc0 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 the current thr
2abd0 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 ead to suspend e
2abe0 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 xecution.** for
2abf0 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 at least a numbe
2ac00 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 r of millisecond
2ac10 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 s specified in i
2ac20 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a ts parameter..**
2ac30 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 .** If the opera
2ac40 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 ting system does
2ac50 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 not support sle
2ac60 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 ep requests with
2ac70 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 .** millisecond
2ac80 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c time resolution,
2ac90 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 then the time w
2aca0 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 ill be rounded u
2acb0 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 p to.** the near
2acc0 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 est second. The
2acd0 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 number of millis
2ace0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 econds of sleep
2acf0 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 actually.** requ
2ad00 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f ested from the o
2ad10 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 perating system
2ad20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
2ad30 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d ** SQLite implem
2ad40 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 ents this interf
2ad50 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 ace by calling t
2ad60 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d he xSleep().** m
2ad70 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 ethod of the def
2ad80 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
2ad90 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a s] object..**.**
2ada0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b Requirements: [
2adb0 48 31 30 35 33 33 5d 20 5b 48 31 30 35 33 36 5d H10533] [H10536]
2adc0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 .*/.SQLITE_API S
2add0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
2ade0 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
2adf0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 int sqlite3_slee
2ae00 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 p(int);../*.** C
2ae10 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 API3REF: Name Of
2ae20 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 The Folder Hold
2ae30 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 ing Temporary Fi
2ae40 6c 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 les {H10310} <S2
2ae50 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 0000>.**.** If t
2ae60 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 his global varia
2ae70 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 ble is made to p
2ae80 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 oint to a string
2ae90 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 which is.** the
2aea0 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 name of a folde
2aeb0 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 r (a.k.a. direct
2aec0 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 ory), then all t
2aed0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a emporary files.*
2aee0 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c * created by SQL
2aef0 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 ite will be plac
2af00 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 ed in that direc
2af10 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 tory. If this v
2af20 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 ariable.** is a
2af30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 NULL pointer, th
2af40 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 en SQLite perfor
2af50 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 ms a search for
2af60 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a an appropriate.*
2af70 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 * temporary file
2af80 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a directory..**.*
2af90 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 * It is not safe
2afa0 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 to read or modi
2afb0 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 fy this variable
2afc0 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e in more than on
2afd0 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 e.** thread at a
2afe0 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f time. It is no
2aff0 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f t safe to read o
2b000 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 r modify this va
2b010 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b riable.** if a [
2b020 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2b030 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 ion] is being us
2b040 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 ed at the same t
2b050 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 ime in a separat
2b060 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 e.** thread..**
2b070 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 It is intended t
2b080 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c hat this variabl
2b090 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a e be set once.**
2b0a0 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 as part of proc
2b0b0 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 ess initializati
2b0c0 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e on and before an
2b0d0 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 y SQLite interfa
2b0e0 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 ce.** routines h
2b0f0 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 ave been called
2b100 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61 and that this va
2b110 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e riable remain un
2b120 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 changed.** there
2b130 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 after..**.** The
2b140 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 [temp_store_dir
2b150 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d ectory pragma] m
2b160 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 ay modify this v
2b170 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 ariable and caus
2b180 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 e.** it to point
2b190 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 to memory obtai
2b1a0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
2b1b0 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 46 75 72 74 3_malloc]. Furt
2b1c0 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 hermore,.** the
2b1d0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
2b1e0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c ctory pragma] al
2b1f0 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 ways assumes tha
2b200 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 t any string.**
2b210 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 that this variab
2b220 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 le points to is
2b230 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f held in memory o
2b240 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a btained from .**
2b250 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
2b260 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 ] and the pragma
2b270 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 may attempt to
2b280 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 free that memory
2b290 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 .** using [sqlit
2b2a0 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e e3_free]..** Hen
2b2b0 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 ce, if this vari
2b2c0 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 able is modified
2b2d0 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 directly, eithe
2b2e0 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a r it should be.*
2b2f0 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d * made NULL or m
2b300 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 ade to point to
2b310 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
2b320 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
2b330 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 lloc].** or else
2b340 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 the use of the
2b350 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
2b360 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 ctory pragma] sh
2b370 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e ould be avoided.
2b380 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 .*/.SQLITE_API S
2b390 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
2b3a0 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
2b3b0 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 SQLITE_EXTERN ch
2b3c0 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 ar *sqlite3_temp
2b3d0 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a _directory;../*.
2b3e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 ** CAPI3REF: Tes
2b3f0 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 t For Auto-Commi
2b400 74 20 4d 6f 64 65 20 7b 48 31 32 39 33 30 7d 20 t Mode {H12930}
2b410 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 <S60200>.** KEYW
2b420 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 ORDS: {autocommi
2b430 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 t mode}.**.** Th
2b440 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 e sqlite3_get_au
2b450 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 tocommit() inter
2b460 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e face returns non
2b470 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f -zero or.** zero
2b480 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 if the given da
2b490 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2b4a0 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 n is or is not i
2b4b0 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 n autocommit mod
2b4c0 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 e,.** respective
2b4d0 6c 79 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 ly. Autocommit
2b4e0 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 mode is on by de
2b4f0 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f fault..** Autoco
2b500 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 mmit mode is dis
2b510 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 abled by a [BEGI
2b520 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a N] statement..**
2b530 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 Autocommit mode
2b540 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 is re-enabled b
2b550 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 y a [COMMIT] or
2b560 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a [ROLLBACK]..**.*
2b570 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e * If certain kin
2b580 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 ds of errors occ
2b590 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e ur on a statemen
2b5a0 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 t within a multi
2b5b0 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 -statement.** tr
2b5c0 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 ansaction (error
2b5d0 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c s including [SQL
2b5e0 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 ITE_FULL], [SQLI
2b5f0 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 TE_IOERR],.** [S
2b600 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 QLITE_NOMEM], [S
2b610 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 QLITE_BUSY], and
2b620 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 [SQLITE_INTERRU
2b630 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a PT]) then the.**
2b640 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 transaction mig
2b650 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 ht be rolled bac
2b660 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e k automatically.
2b670 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 The only way t
2b680 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 o.** find out wh
2b690 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 ether SQLite aut
2b6a0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 omatically rolle
2b6b0 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 d back the trans
2b6c0 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 action after.**
2b6d0 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 an error is to u
2b6e0 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e se this function
2b6f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 ..**.** If anoth
2b700 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 er thread change
2b710 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 s the autocommit
2b720 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 status of the d
2b730 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
2b740 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 ction while this
2b750 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e routine is runn
2b760 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 ing, then the re
2b770 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 turn value.** is
2b780 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
2b790 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 * Requirements:
2b7a0 5b 48 31 32 39 33 31 5d 20 5b 48 31 32 39 33 32 [H12931] [H12932
2b7b0 5d 20 5b 48 31 32 39 33 33 5d 20 5b 48 31 32 39 ] [H12933] [H129
2b7c0 33 34 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 34].*/.SQLITE_AP
2b7d0 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
2b7e0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
2b7f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 PI int sqlite3_g
2b800 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 et_autocommit(sq
2b810 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
2b820 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 CAPI3REF: Find T
2b830 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 he Database Hand
2b840 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 le Of A Prepared
2b850 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 Statement {H131
2b860 32 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 20} <S60600>.**.
2b870 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 ** The sqlite3_d
2b880 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 b_handle interfa
2b890 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b ce returns the [
2b8a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2b8b0 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 ion] handle.** t
2b8c0 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 o which a [prepa
2b8d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 red statement] b
2b8e0 65 6c 6f 6e 67 73 2e 20 20 54 68 65 20 5b 64 61 elongs. The [da
2b8f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2b900 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 n].** returned b
2b910 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e y sqlite3_db_han
2b920 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 dle is the same
2b930 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2b940 74 69 6f 6e 5d 20 74 68 61 74 20 77 61 73 20 74 tion] that was t
2b950 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2b960 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c t.** to the [sql
2b970 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2b980 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 )] call (or its
2b990 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 variants) that w
2b9a0 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 as used to.** cr
2b9b0 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 eate the stateme
2b9c0 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 nt in the first
2b9d0 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 place..**.** Req
2b9e0 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31 uirements: [H131
2b9f0 32 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 23].*/.SQLITE_AP
2ba00 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
2ba10 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
2ba20 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 PI sqlite3 *sqli
2ba30 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 te3_db_handle(sq
2ba40 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f lite3_stmt*);../
2ba50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
2ba60 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 ind the next pre
2ba70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
2ba80 7b 48 31 33 31 34 30 7d 20 3c 53 36 30 36 30 30 {H13140} <S60600
2ba90 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 >.**.** This int
2baa0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
2bab0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
2bac0 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 next [prepared s
2bad0 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a tatement] after.
2bae0 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 ** pStmt associa
2baf0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 ted with the [da
2bb00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2bb10 6e 5d 20 70 44 62 2e 20 20 49 66 20 70 53 74 6d n] pDb. If pStm
2bb20 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 t is NULL.** the
2bb30 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 n this interface
2bb40 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
2bb50 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 er to the first
2bb60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2bb70 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 nt.** associated
2bb80 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 with the databa
2bb90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 se connection pD
2bba0 62 2e 20 20 49 66 20 6e 6f 20 70 72 65 70 61 72 b. If no prepar
2bbb0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 ed statement.**
2bbc0 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f satisfies the co
2bbd0 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 nditions of this
2bbe0 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 routine, it ret
2bbf0 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a urns NULL..**.**
2bc00 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 The [database c
2bc10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 onnection] point
2bc20 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 er D in a call t
2bc30 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 o.** [sqlite3_ne
2bc40 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 xt_stmt(D,S)] mu
2bc50 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f st refer to an o
2bc60 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 pen database.**
2bc70 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 connection and i
2bc80 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 n particular mus
2bc90 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 t not be a NULL
2bca0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 52 pointer..**.** R
2bcb0 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 equirements: [H1
2bcc0 33 31 34 33 5d 20 5b 48 31 33 31 34 36 5d 20 5b 3143] [H13146] [
2bcd0 48 31 33 31 34 39 5d 20 5b 48 31 33 31 35 32 5d H13149] [H13152]
2bce0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 .*/.SQLITE_API S
2bcf0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
2bd00 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
2bd10 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 sqlite3_stmt *sq
2bd20 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 lite3_next_stmt(
2bd30 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 sqlite3 *pDb, sq
2bd40 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
2bd50 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2bd60 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 REF: Commit And
2bd70 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 Rollback Notific
2bd80 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 ation Callbacks
2bd90 7b 48 31 32 39 35 30 7d 20 3c 53 36 30 34 30 30 {H12950} <S60400
2bda0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
2bdb0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 te3_commit_hook(
2bdc0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ) interface regi
2bdd0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b sters a callback
2bde0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 .** function to
2bdf0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 be invoked whene
2be00 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f ver a transactio
2be10 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 n is [COMMIT | c
2be20 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 41 6e ommitted]..** An
2be30 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 y callback set b
2be40 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c y a previous cal
2be50 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d l to sqlite3_com
2be60 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f mit_hook().** fo
2be70 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 r the same datab
2be80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
2be90 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a s overridden..**
2bea0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c The sqlite3_rol
2beb0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 lback_hook() int
2bec0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 erface registers
2bed0 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 a callback.** f
2bee0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e unction to be in
2bef0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 voked whenever a
2bf00 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
2bf10 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c [ROLLBACK | roll
2bf20 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 41 6e 79 ed back]..** Any
2bf30 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 callback set by
2bf40 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c a previous call
2bf50 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d to sqlite3_comm
2bf60 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 it_hook().** for
2bf70 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
2bf80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
2bf90 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 overridden..**
2bfa0 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e The pArg argumen
2bfb0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f t is passed thro
2bfc0 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 ugh to the callb
2bfd0 61 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 ack..** If the c
2bfe0 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d allback on a com
2bff0 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f mit hook functio
2c000 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 n returns non-ze
2c010 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 ro,.** then the
2c020 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 commit is conver
2c030 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 ted into a rollb
2c040 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e ack..**.** If an
2c050 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 other function w
2c060 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 as previously re
2c070 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a gistered, its.**
2c080 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 pArg value is r
2c090 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 eturned. Otherw
2c0a0 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 ise NULL is retu
2c0b0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rned..**.** The
2c0c0 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 callback impleme
2c0d0 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ntation must not
2c0e0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 do anything tha
2c0f0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a t will modify.**
2c100 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
2c110 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e nnection that in
2c120 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 voked the callba
2c130 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 ck. Any actions
2c140 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 .** to modify th
2c150 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
2c160 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 ction must be de
2c170 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 ferred until aft
2c180 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 er the.** comple
2c190 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c tion of the [sql
2c1a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c ite3_step()] cal
2c1b0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 l that triggered
2c1c0 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f the commit.** o
2c1d0 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 r rollback hook
2c1e0 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 in the first pla
2c1f0 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 ce..** Note that
2c200 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2c210 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c e_v2()] and [sql
2c220 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 ite3_step()] bot
2c230 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a h modify their.*
2c240 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
2c250 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d ctions for the m
2c260 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 eaning of "modif
2c270 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 y" in this parag
2c280 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 raph..**.** Regi
2c290 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 stering a NULL f
2c2a0 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 unction disables
2c2b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a the callback..*
2c2c0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 6f *.** When the co
2c2d0 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 mmit hook callba
2c2e0 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ck routine retur
2c2f0 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f ns zero, the [CO
2c300 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 MMIT].** operati
2c310 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f on is allowed to
2c320 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c continue normal
2c330 6c 79 2e 20 20 49 66 20 74 68 65 20 63 6f 6d 6d ly. If the comm
2c340 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 it hook.** retur
2c350 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 ns non-zero, the
2c360 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 n the [COMMIT] i
2c370 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f s converted into
2c380 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a a [ROLLBACK]..*
2c390 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 * The rollback h
2c3a0 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f ook is invoked o
2c3b0 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 n a rollback tha
2c3c0 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 t results from a
2c3d0 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 commit.** hook
2c3e0 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 returning non-ze
2c3f0 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 ro, just as it w
2c400 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 ould be with any
2c410 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e other rollback.
2c420 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 .**.** For the p
2c430 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 urposes of this
2c440 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 API, a transacti
2c450 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 on is said to ha
2c460 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 ve been.** rolle
2c470 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 d back if an exp
2c480 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 licit "ROLLBACK"
2c490 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 statement is ex
2c4a0 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e ecuted, or.** an
2c4b0 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 error or constr
2c4c0 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 aint causes an i
2c4d0 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b mplicit rollback
2c4e0 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 to occur..** Th
2c4f0 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 e rollback callb
2c500 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b ack is not invok
2c510 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 ed if a transact
2c520 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 ion is.** automa
2c530 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 tically rolled b
2c540 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 ack because the
2c550 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2c560 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a ion is closed..*
2c570 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 * The rollback c
2c580 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 allback is not i
2c590 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e nvoked if a tran
2c5a0 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f saction is.** ro
2c5b0 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 lled back becaus
2c5c0 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 e a commit callb
2c5d0 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e ack returned non
2c5e0 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e -zero..** <todo>
2c5f0 20 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c Check on this <
2c600 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 53 65 65 /todo>.**.** See
2c610 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 also the [sqlit
2c620 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 e3_update_hook()
2c630 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a ] interface..**.
2c640 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
2c650 0a 2a 2a 20 5b 48 31 32 39 35 31 5d 20 5b 48 31 .** [H12951] [H1
2c660 32 39 35 32 5d 20 5b 48 31 32 39 35 33 5d 20 5b 2952] [H12953] [
2c670 48 31 32 39 35 34 5d 20 5b 48 31 32 39 35 35 5d H12954] [H12955]
2c680 0a 2a 2a 20 5b 48 31 32 39 36 31 5d 20 5b 48 31 .** [H12961] [H1
2c690 32 39 36 32 5d 20 5b 48 31 32 39 36 33 5d 20 5b 2962] [H12963] [
2c6a0 48 31 32 39 36 34 5d 0a 2a 2f 0a 53 51 4c 49 54 H12964].*/.SQLIT
2c6b0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
2c6c0 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
2c6d0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c TE_API void *sql
2c6e0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b ite3_commit_hook
2c6f0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a (sqlite3*, int(*
2c700 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 )(void*), void*)
2c710 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c ;.SQLITE_API SQL
2c720 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
2c730 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 76 6f PI SQLITE_API vo
2c740 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c id *sqlite3_roll
2c750 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 back_hook(sqlite
2c760 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 3*, void(*)(void
2c770 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a *), void*);../*
2c780 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 .** CAPI3REF: Da
2c790 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 ta Change Notifi
2c7a0 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 cation Callbacks
2c7b0 20 7b 48 31 32 39 37 30 7d 20 3c 53 36 30 34 30 {H12970} <S6040
2c7c0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0>.**.** The sql
2c7d0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b ite3_update_hook
2c7e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 () interface reg
2c7f0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 isters a callbac
2c800 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 k function.** wi
2c810 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 th the [database
2c820 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 connection] ide
2c830 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66 ntified by the f
2c840 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a irst argument.**
2c850 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 to be invoked w
2c860 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 henever a row is
2c870 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 updated, insert
2c880 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a ed or deleted..*
2c890 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 * Any callback s
2c8a0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 et by a previous
2c8b0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 call to this fu
2c8c0 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 nction.** for th
2c8d0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
2c8e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 connection is ov
2c8f0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 erridden..**.**
2c900 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
2c910 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ent is a pointer
2c920 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e to the function
2c930 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 to invoke when
2c940 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 a.** row is upda
2c950 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 ted, inserted or
2c960 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 54 68 65 deleted..** The
2c970 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
2c980 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
2c990 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
2c9a0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a third argument.
2c9b0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 ** to sqlite3_up
2c9c0 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 date_hook()..**
2c9d0 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 The second callb
2c9e0 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ack argument is
2c9f0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 one of [SQLITE_I
2ca00 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f NSERT], [SQLITE_
2ca10 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b DELETE],.** or [
2ca20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 SQLITE_UPDATE],
2ca30 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 depending on the
2ca40 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 operation that
2ca50 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 caused the callb
2ca60 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 ack.** to be inv
2ca70 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 oked..** The thi
2ca80 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 rd and fourth ar
2ca90 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 guments to the c
2caa0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 allback contain
2cab0 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a pointers to the.
2cac0 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 ** database and
2cad0 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 table name conta
2cae0 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 ining the affect
2caf0 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 ed row..** The f
2cb00 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 inal callback pa
2cb10 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b rameter is the [
2cb20 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72 6f rowid] of the ro
2cb30 77 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 63 61 73 w..** In the cas
2cb40 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 e of an update,
2cb50 74 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77 this is the [row
2cb60 69 64 5d 20 61 66 74 65 72 20 74 68 65 20 75 70 id] after the up
2cb70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 date takes place
2cb80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 ..**.** The upda
2cb90 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 te hook is not i
2cba0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 nvoked when inte
2cbb0 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c rnal system tabl
2cbc0 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 es are.** modifi
2cbd0 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f ed (i.e. sqlite_
2cbe0 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 master and sqlit
2cbf0 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a e_sequence)..**.
2cc00 2a 2a 20 49 6e 20 74 68 65 20 63 75 72 72 65 6e ** In the curren
2cc10 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e t implementation
2cc20 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f , the update hoo
2cc30 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f k.** is not invo
2cc40 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 ked when duplica
2cc50 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 tion rows are de
2cc60 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 leted because of
2cc70 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c an.** [ON CONFL
2cc80 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 ICT | ON CONFLIC
2cc90 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 T REPLACE] claus
2cca0 65 2e 20 20 4e 6f 72 20 69 73 20 74 68 65 20 75 e. Nor is the u
2ccb0 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e pdate hook.** in
2ccc0 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 voked when rows
2ccd0 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e are deleted usin
2cce0 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 g the [truncate
2ccf0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a optimization]..*
2cd00 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 * The exceptions
2cd10 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 defined in this
2cd20 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 paragraph might
2cd30 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 change in a fut
2cd40 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f ure.** release o
2cd50 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
2cd60 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 The update hook
2cd70 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d implementation m
2cd80 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 ust not do anyth
2cd90 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f ing that will mo
2cda0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 dify.** the data
2cdb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2cdc0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
2cdd0 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 update hook. A
2cde0 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f ny actions.** to
2cdf0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 modify the data
2ce00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2ce10 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 must be deferred
2ce20 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 until after the
2ce30 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f .** completion o
2ce40 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 f the [sqlite3_s
2ce50 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 tep()] call that
2ce60 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75 triggered the u
2ce70 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e pdate hook..** N
2ce80 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 ote that [sqlite
2ce90 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2cea0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 and [sqlite3_ste
2ceb0 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 p()] both modify
2cec0 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 their.** databa
2ced0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 se connections f
2cee0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f or the meaning o
2cef0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 f "modify" in th
2cf00 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a is paragraph..**
2cf10 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 .** If another f
2cf20 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 unction was prev
2cf30 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 iously registere
2cf40 64 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c 75 d, its pArg valu
2cf50 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 e.** is returned
2cf60 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c . Otherwise NUL
2cf70 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a L is returned..*
2cf80 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 *.** See also th
2cf90 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 e [sqlite3_commi
2cfa0 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 t_hook()] and [s
2cfb0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f qlite3_rollback_
2cfc0 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 hook()].** inter
2cfd0 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 faces..**.** Req
2cfe0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
2cff0 31 32 39 37 31 5d 20 5b 48 31 32 39 37 33 5d 20 12971] [H12973]
2d000 5b 48 31 32 39 37 35 5d 20 5b 48 31 32 39 37 37 [H12975] [H12977
2d010 5d 20 5b 48 31 32 39 37 39 5d 20 5b 48 31 32 39 ] [H12979] [H129
2d020 38 31 5d 20 5b 48 31 32 39 38 33 5d 20 5b 48 31 81] [H12983] [H1
2d030 32 39 38 36 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 2986].*/.SQLITE_
2d040 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
2d050 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
2d060 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 _API void *sqlit
2d070 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a e3_update_hook(.
2d080 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 sqlite3*, . v
2d090 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e oid(*)(void *,in
2d0a0 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c t ,char const *,
2d0b0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c char const *,sql
2d0c0 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 ite3_int64),. v
2d0d0 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 oid*.);../*.** C
2d0e0 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 API3REF: Enable
2d0f0 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 Or Disable Share
2d100 64 20 50 61 67 65 72 20 43 61 63 68 65 20 7b 48 d Pager Cache {H
2d110 31 30 33 33 30 7d 20 3c 53 33 30 39 30 30 3e 0a 10330} <S30900>.
2d120 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 ** KEYWORDS: {sh
2d130 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a ared cache}.**.*
2d140 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 * This routine e
2d150 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c nables or disabl
2d160 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f es the sharing o
2d170 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 f the database c
2d180 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 ache.** and sche
2d190 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 ma data structur
2d1a0 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 es between [data
2d1b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2d1c0 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a | connections].*
2d1d0 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 * to the same da
2d1e0 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 tabase. Sharing
2d1f0 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 is enabled if th
2d200 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 e argument is tr
2d210 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c ue.** and disabl
2d220 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 ed if the argume
2d230 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a nt is false..**.
2d240 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 ** Cache sharing
2d250 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 is enabled and
2d260 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 disabled for an
2d270 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a entire process..
2d280 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61 ** This is a cha
2d290 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 nge as of SQLite
2d2a0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 version 3.5.0.
2d2b0 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e In prior version
2d2c0 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 s of SQLite,.**
2d2d0 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62 sharing was enab
2d2e0 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 led or disabled
2d2f0 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 for each thread
2d300 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a separately..**.*
2d310 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72 * The cache shar
2d320 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 ing mode set by
2d330 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 this interface e
2d340 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 ffects all subse
2d350 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 quent.** calls t
2d360 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 o [sqlite3_open(
2d370 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
2d380 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 n_v2()], and [sq
2d390 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e lite3_open16()].
2d3a0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 .** Existing dat
2d3b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2d3c0 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 s continue use t
2d3d0 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a he sharing mode.
2d3e0 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65 ** that was in e
2d3f0 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d ffect at the tim
2d400 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e e they were open
2d410 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 ed..**.** Virtua
2d420 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 l tables cannot
2d430 62 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73 be used with a s
2d440 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 57 68 hared cache. Wh
2d450 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 en shared.** cac
2d460 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 he is enabled, t
2d470 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
2d480 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49 te_module()] API
2d490 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 used to registe
2d4a0 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 r.** virtual tab
2d4b0 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 les will always
2d4c0 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e return an error.
2d4d0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
2d4e0 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ine returns [SQL
2d4f0 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 ITE_OK] if share
2d500 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 d cache was enab
2d510 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a led or disabled.
2d520 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e ** successfully.
2d530 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 An [error code
2d540 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 ] is returned ot
2d550 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 herwise..**.** S
2d560 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 hared cache is d
2d570 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
2d580 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 lt. But this mig
2d590 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 ht change in.**
2d5a0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
2d5b0 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c of SQLite. Appl
2d5c0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 ications that ca
2d5d0 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a re about shared.
2d5e0 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 ** cache setting
2d5f0 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 should set it e
2d600 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a xplicitly..**.**
2d610 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c See Also: [SQL
2d620 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 ite Shared-Cache
2d630 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a 20 52 65 71 Mode].**.** Req
2d640 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 33 uirements: [H103
2d650 33 31 5d 20 5b 48 31 30 33 33 36 5d 20 5b 48 31 31] [H10336] [H1
2d660 30 33 33 37 5d 20 5b 48 31 30 33 33 39 5d 0a 2a 0337] [H10339].*
2d670 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c /.SQLITE_API SQL
2d680 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
2d690 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e PI SQLITE_API in
2d6a0 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 t sqlite3_enable
2d6b0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e _shared_cache(in
2d6c0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2d6d0 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 REF: Attempt To
2d6e0 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 Free Heap Memory
2d6f0 20 7b 48 31 37 33 34 30 7d 20 3c 53 33 30 32 32 {H17340} <S3022
2d700 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0>.**.** The sql
2d710 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d ite3_release_mem
2d720 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 ory() interface
2d730 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 attempts to free
2d740 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 N bytes.** of h
2d750 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 eap memory by de
2d760 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 allocating non-e
2d770 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 ssential memory
2d780 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 allocations.** h
2d790 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62 eld by the datab
2d7a0 61 73 65 20 6c 69 62 72 61 72 79 2e 20 7b 45 4e ase library. {EN
2d7b0 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 D} Memory used
2d7c0 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 to cache databas
2d7d0 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d e.** pages to im
2d7e0 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 prove performanc
2d7f0 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 e is an example
2d800 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c of non-essential
2d810 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 73 71 6c 69 memory..** sqli
2d820 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f te3_release_memo
2d830 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 65 ry() returns the
2d840 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2d850 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c actually freed,
2d860 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20 .** which might
2d870 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 be more or less
2d880 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 than the amount
2d890 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a requested..**.**
2d8a0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b Requirements: [
2d8b0 48 31 37 33 34 31 5d 20 5b 48 31 37 33 34 32 5d H17341] [H17342]
2d8c0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 .*/.SQLITE_API S
2d8d0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
2d8e0 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
2d8f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 int sqlite3_rele
2d900 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b ase_memory(int);
2d910 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2d920 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 : Impose A Limit
2d930 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 20 7b 48 On Heap Size {H
2d940 31 37 33 35 30 7d 20 3c 53 33 30 32 32 30 3e 0a 17350} <S30220>.
2d950 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
2d960 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 3_soft_heap_limi
2d970 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 70 6c t() interface pl
2d980 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c 69 aces a "soft" li
2d990 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 6d mit.** on the am
2d9a0 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d ount of heap mem
2d9b0 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 ory that may be
2d9c0 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c allocated by SQL
2d9d0 69 74 65 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 6e ite..** If an in
2d9e0 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f ternal allocatio
2d9f0 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20 74 n is requested t
2da00 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 hat would exceed
2da10 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65 61 the.** soft hea
2da20 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 p limit, [sqlite
2da30 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 3_release_memory
2da40 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f ()] is invoked o
2da50 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 69 ne or.** more ti
2da60 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 mes to free up s
2da70 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 ome space before
2da80 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 the allocation
2da90 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a is performed..**
2daa0 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20 69 73 .** The limit is
2dab0 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 called "soft",
2dac0 62 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c 69 because if [sqli
2dad0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f te3_release_memo
2dae0 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 20 ry()].** cannot
2daf0 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74 20 free sufficient
2db00 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e memory to preven
2db10 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d t the limit from
2db20 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c being exceeded,
2db30 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 .** the memory i
2db40 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 s allocated anyw
2db50 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 ay and the curre
2db60 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f nt operation pro
2db70 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e ceeds..**.** A n
2db80 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 egative or zero
2db90 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e value for N mean
2dba0 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20 s that there is
2dbb0 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d no soft heap lim
2dbc0 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 it and.** [sqlit
2dbd0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 e3_release_memor
2dbe0 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 y()] will only b
2dbf0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 e called when me
2dc00 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74 65 mory is exhauste
2dc10 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c d..** The defaul
2dc20 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 t value for the
2dc30 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 soft heap limit
2dc40 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 is zero..**.** S
2dc50 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65 QLite makes a be
2dc60 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e st effort to hon
2dc70 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 or the soft heap
2dc80 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42 75 74 20 69 limit..** But i
2dc90 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 f the soft heap
2dca0 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 62 65 20 limit cannot be
2dcb0 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75 74 69 honored, executi
2dcc0 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 on will.** conti
2dcd0 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 72 6f nue without erro
2dce0 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 6f r or notificatio
2dcf0 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 79 20 n. This is why
2dd00 74 68 65 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 the limit is.**
2dd10 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20 called a "soft"
2dd20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64 limit. It is ad
2dd30 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a visory only..**.
2dd40 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 ** Prior to SQLi
2dd50 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 te version 3.5.0
2dd60 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f , this routine o
2dd70 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 nly constrained
2dd80 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c the memory.** al
2dd90 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 69 6e located by a sin
2dda0 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68 65 gle thread - the
2ddb0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 same thread in
2ddc0 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 74 69 which this routi
2ddd0 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 ne.** runs. Beg
2dde0 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 inning with SQLi
2ddf0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 te version 3.5.0
2de00 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 , the soft heap
2de10 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c limit is.** appl
2de20 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 ied to all threa
2de30 64 73 2e 20 54 68 65 20 76 61 6c 75 65 20 73 70 ds. The value sp
2de40 65 63 69 66 69 65 64 20 66 6f 72 20 74 68 65 20 ecified for the
2de50 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a soft heap limit.
2de60 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20 62 ** is an upper b
2de70 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 ound on the tota
2de80 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
2de90 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 ion for all thre
2dea0 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 69 ads. In.** versi
2deb0 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69 on 3.5.0 there i
2dec0 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 s no mechanism f
2ded0 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 or limiting the
2dee0 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a heap usage for.*
2def0 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72 * individual thr
2df00 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 eads..**.** Requ
2df10 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
2df20 36 33 35 31 5d 20 5b 48 31 36 33 35 32 5d 20 5b 6351] [H16352] [
2df30 48 31 36 33 35 33 5d 20 5b 48 31 36 33 35 34 5d H16353] [H16354]
2df40 20 5b 48 31 36 33 35 35 5d 20 5b 48 31 36 33 35 [H16355] [H1635
2df50 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 8].*/.SQLITE_API
2df60 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
2df70 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
2df80 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 I void sqlite3_s
2df90 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 oft_heap_limit(i
2dfa0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
2dfb0 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 3REF: Extract Me
2dfc0 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 tadata About A C
2dfd0 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 olumn Of A Table
2dfe0 20 7b 48 31 32 38 35 30 7d 20 3c 53 36 30 33 30 {H12850} <S6030
2dff0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 0>.**.** This ro
2e000 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 utine returns me
2e010 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 tadata about a s
2e020 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f pecific column o
2e030 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 f a specific.**
2e040 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 database table a
2e050 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 ccessible using
2e060 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
2e070 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 nnection] handle
2e080 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 .** passed as th
2e090 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e e first function
2e0a0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
2e0b0 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 The column is i
2e0c0 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 dentified by the
2e0d0 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 second, third a
2e0e0 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 nd fourth parame
2e0f0 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 ters to.** this
2e100 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65 function. The se
2e110 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
2e120 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d s either the nam
2e130 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
2e140 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e e.** (i.e. "main
2e150 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 ", "temp" or an
2e160 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
2e170 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 e) containing th
2e180 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 e specified.** t
2e190 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 able or NULL. If
2e1a0 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 it is NULL, the
2e1b0 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 n all attached d
2e1c0 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61 atabases are sea
2e1d0 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 rched.** for the
2e1e0 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 table using the
2e1f0 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 same algorithm
2e200 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61 used by the data
2e210 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a base engine to.*
2e220 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c * resolve unqual
2e230 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 ified table refe
2e240 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 rences..**.** Th
2e250 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 e third and four
2e260 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f th parameters to
2e270 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 this function a
2e280 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 re the table and
2e290 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 column.** name
2e2a0 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63 of the desired c
2e2b0 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 olumn, respectiv
2e2c0 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 ely. Neither of
2e2d0 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 these parameters
2e2e0 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e .** may be NULL.
2e2f0 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 64 61 74 61 20 .**.** Metadata
2e300 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 is returned by w
2e310 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 riting to the me
2e320 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 mory locations p
2e330 61 73 73 65 64 20 61 73 20 74 68 65 20 35 74 68 assed as the 5th
2e340 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 .** and subseque
2e350 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f nt parameters to
2e360 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 this function.
2e370 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 Any of these arg
2e380 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a uments may be.**
2e390 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 NULL, in which
2e3a0 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 case the corresp
2e3b0 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f onding element o
2e3c0 66 20 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d f metadata is om
2e3d0 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c itted..**.** <bl
2e3e0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 ockquote>.** <ta
2e3f0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a ble border="1">.
2e400 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 ** <tr><th> Para
2e410 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 meter <th> Outpu
2e420 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 t<br>Type <th>
2e430 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a Description.**.*
2e440 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c * <tr><td> 5th <
2e450 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 td> const char*
2e460 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a <td> Data type.*
2e470 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c * <tr><td> 6th <
2e480 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 td> const char*
2e490 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 <td> Name of def
2e4a0 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 ault collation s
2e4b0 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c equence.** <tr><
2e4c0 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 td> 7th <td> int
2e4d0 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 <td> Tr
2e4e0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 ue if column has
2e4f0 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 a NOT NULL cons
2e500 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 traint.** <tr><t
2e510 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 d> 8th <td> int
2e520 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 <td> Tru
2e530 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 e if column is p
2e540 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 art of the PRIMA
2e550 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 RY KEY.** <tr><t
2e560 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 d> 9th <td> int
2e570 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 <td> Tru
2e580 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b e if column is [
2e590 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a AUTOINCREMENT].*
2e5a0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f * </table>.** </
2e5b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
2e5c0 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 * The memory poi
2e5d0 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 nted to by the c
2e5e0 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 haracter pointer
2e5f0 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 s returned for t
2e600 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f he.** declaratio
2e610 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 n type and colla
2e620 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 tion sequence is
2e630 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 valid only unti
2e640 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 l the next.** ca
2e650 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 ll to any SQLite
2e660 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a API function..*
2e670 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 *.** If the spec
2e680 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 ified table is a
2e690 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 ctually a view,
2e6a0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
2e6b0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
2e6c0 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66 ** If the specif
2e6d0 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 ied column is "r
2e6e0 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 owid", "oid" or
2e6f0 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e "_rowid_" and an
2e700 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 .** [INTEGER PRI
2e710 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e MARY KEY] column
2e720 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 has been explic
2e730 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 itly declared, t
2e740 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a hen the output.*
2e750 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 * parameters are
2e760 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 set for the exp
2e770 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 licitly declared
2e780 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 column. If ther
2e790 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 e is no.** expli
2e7a0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b citly declared [
2e7b0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 INTEGER PRIMARY
2e7c0 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 KEY] column, the
2e7d0 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 n the output.**
2e7e0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 parameters are s
2e7f0 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a et as follows:.*
2e800 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 *.** <pre>.**
2e810 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e data type: "IN
2e820 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f TEGER".** co
2e830 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
2e840 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 : "BINARY".**
2e850 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a not null: 0.**
2e860 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 primary key
2e870 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 : 1.** auto
2e880 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 increment: 0.**
2e890 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 </pre>.**.** Thi
2e8a0 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c s function may l
2e8b0 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 oad one or more
2e8c0 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 schemas from dat
2e8d0 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 abase files. If
2e8e0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 an.** error occu
2e8f0 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 rs during this p
2e900 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 rocess, or if th
2e910 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c e requested tabl
2e920 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 e or column.** c
2e930 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 annot be found,
2e940 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
2e950 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 is returned and
2e960 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 an error message
2e970 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 left.** in the
2e980 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2e990 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 tion] (to be ret
2e9a0 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c rieved using sql
2e9b0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a ite3_errmsg())..
2e9c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69 **.** This API i
2e9d0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 s only available
2e9e0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 if the library
2e9f0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 was compiled wit
2ea00 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 h the.** [SQLITE
2ea10 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d _ENABLE_COLUMN_M
2ea20 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 ETADATA] C-prepr
2ea30 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 ocessor symbol d
2ea40 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 efined..*/.SQLIT
2ea50 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
2ea60 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
2ea70 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2ea80 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f e3_table_column_
2ea90 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 metadata(. sqli
2eaa0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
2eab0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 /* Conne
2eac0 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a ction handle */.
2ead0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 const char *zD
2eae0 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a bName, /*
2eaf0 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f Database name o
2eb00 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 r NULL */. cons
2eb10 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 t char *zTableNa
2eb20 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 me, /* Table
2eb30 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 name */. const
2eb40 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 char *zColumnNa
2eb50 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e me, /* Column
2eb60 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 name */. char
2eb70 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 const **pzDataTy
2eb80 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 pe, /* OUTPUT
2eb90 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 : Declared data
2eba0 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 type */. char c
2ebb0 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 onst **pzCollSeq
2ebc0 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a , /* OUTPUT:
2ebd0 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 Collation seque
2ebe0 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e nce name */. in
2ebf0 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 t *pNotNull,
2ec00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 /* OUT
2ec10 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 PUT: True if NOT
2ec20 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 NULL constraint
2ec30 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 exists */. int
2ec40 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 *pPrimaryKey,
2ec50 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 /* OUTP
2ec60 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 UT: True if colu
2ec70 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f mn part of PK */
2ec80 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 . int *pAutoinc
2ec90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
2eca0 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 * OUTPUT: True i
2ecb0 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f f column is auto
2ecc0 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b -increment */.);
2ecd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2ece0 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 : Load An Extens
2ecf0 69 6f 6e 20 7b 48 31 32 36 30 30 7d 20 3c 53 32 ion {H12600} <S2
2ed00 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0500>.**.** This
2ed10 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73 interface loads
2ed20 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e an SQLite exten
2ed30 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f sion library fro
2ed40 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 m the named file
2ed50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 31 7d ..**.** {H12601}
2ed60 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 The sqlite3_loa
2ed70 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e d_extension() in
2ed80 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 terface attempts
2ed90 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 20 to load an.**
2eda0 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 65 SQLite e
2edb0 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 xtension library
2edc0 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 contained in th
2edd0 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a e file zFile..**
2ede0 0a 2a 2a 20 7b 48 31 32 36 30 32 7d 20 54 68 65 .** {H12602} The
2edf0 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 entry point is
2ee00 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 zProc..**.** {H1
2ee10 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20 2603} zProc may
2ee20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63 be 0, in which c
2ee30 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 ase the name of
2ee40 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a the entry point.
2ee50 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 ** defa
2ee60 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 ults to "sqlite3
2ee70 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 _extension_init"
2ee80 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 34 7d ..**.** {H12604}
2ee90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 The sqlite3_loa
2eea0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e d_extension() in
2eeb0 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 terface shall re
2eec0 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 turn.**
2eed0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 [SQLITE_OK] on
2eee0 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c success and [SQL
2eef0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f ITE_ERROR] if so
2ef00 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f mething goes wro
2ef10 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 ng..**.** {H1260
2ef20 35 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 5} If an error o
2ef30 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d ccurs and pzErrM
2ef40 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 sg is not 0, the
2ef50 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 n the.**
2ef60 20 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f [sqlite3_load_
2ef70 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 extension()] int
2ef80 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 erface shall att
2ef90 65 6d 70 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 empt to.**
2efa0 20 20 20 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d fill *pzErrM
2efb0 73 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65 sg with error me
2efc0 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 ssage text store
2efd0 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 d in memory.**
2efe0 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 obtained
2eff0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
2f000 61 6c 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44 7d 20 alloc()]. {END}
2f010 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e The calling fun
2f020 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ction.**
2f030 20 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 should free th
2f040 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c is memory by cal
2f050 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 ling [sqlite3_fr
2f060 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ee()]..**.** {H1
2f070 32 36 30 36 7d 20 45 78 74 65 6e 73 69 6f 6e 20 2606} Extension
2f080 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 loading must be
2f090 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a enabled using.**
2f0a0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
2f0b0 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 e3_enable_load_e
2f0c0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f xtension()] prio
2f0d0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 r to calling thi
2f0e0 73 20 41 50 49 2c 0a 2a 2a 20 20 20 20 20 20 20 s API,.**
2f0f0 20 20 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 otherwise an
2f100 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 error will be re
2f110 74 75 72 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 turned..*/.SQLIT
2f120 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
2f130 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
2f140 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2f150 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f e3_load_extensio
2f160 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 n(. sqlite3 *db
2f170 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f , /* Lo
2f180 61 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e ad the extension
2f190 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62 into this datab
2f1a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a ase connection *
2f1b0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
2f1c0 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d zFile, /* Nam
2f1d0 65 20 6f 66 20 74 68 65 20 73 68 61 72 65 64 20 e of the shared
2f1e0 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 library containi
2f1f0 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a ng extension */.
2f200 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 const char *zP
2f210 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 roc, /* Entry
2f220 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64 point. Derived
2f230 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 from zFile if 0
2f240 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 */. char **pzE
2f250 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50 rrMsg /* P
2f260 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 ut error message
2f270 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a here if not 0 *
2f280 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
2f290 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 3REF: Enable Or
2f2a0 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f Disable Extensio
2f2b0 6e 20 4c 6f 61 64 69 6e 67 20 7b 48 31 32 36 32 n Loading {H1262
2f2c0 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 0} <S20500>.**.*
2f2d0 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f * So as not to o
2f2e0 70 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f 6c pen security hol
2f2f0 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c es in older appl
2f300 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61 72 ications that ar
2f310 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 20 e.** unprepared
2f320 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78 74 to deal with ext
2f330 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 ension loading,
2f340 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20 6f and as a means o
2f350 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 f disabling.** e
2f360 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 xtension loading
2f370 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e while evaluatin
2f380 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 g user-entered S
2f390 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e QL, the followin
2f3a0 67 20 41 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 g API.** is prov
2f3b0 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68 65 ided to turn the
2f3c0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 [sqlite3_load_e
2f3d0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 xtension()] mech
2f3e0 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 anism on and off
2f3f0 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 6e 73 69 6f ..**.** Extensio
2f400 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 n loading is off
2f410 20 62 79 20 64 65 66 61 75 6c 74 2e 20 53 65 65 by default. See
2f420 20 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a ticket #1863..*
2f430 2a 0a 2a 2a 20 7b 48 31 32 36 32 31 7d 20 43 61 *.** {H12621} Ca
2f440 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 ll the sqlite3_e
2f450 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e nable_load_exten
2f460 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 sion() routine w
2f470 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 ith onoff==1.**
2f480 20 20 20 20 20 20 20 20 20 74 6f 20 74 75 72 6e to turn
2f490 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 extension loadi
2f4a0 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69 ng on and call i
2f4b0 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 t with onoff==0
2f4c0 74 6f 20 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 to turn.**
2f4d0 20 20 20 20 69 74 20 62 61 63 6b 20 6f 66 66 20 it back off
2f4e0 61 67 61 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 again..**.** {H1
2f4f0 32 36 32 32 7d 20 45 78 74 65 6e 73 69 6f 6e 20 2622} Extension
2f500 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 loading is off b
2f510 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 53 51 y default..*/.SQ
2f520 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
2f530 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
2f540 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
2f550 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 lite3_enable_loa
2f560 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 d_extension(sqli
2f570 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f te3 *db, int ono
2f580 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ff);../*.** CAPI
2f590 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 3REF: Automatica
2f5a0 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 lly Load An Exte
2f5b0 6e 73 69 6f 6e 73 20 7b 48 31 32 36 34 30 7d 20 nsions {H12640}
2f5c0 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S20500>.**.** T
2f5d0 68 69 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 his API can be i
2f5e0 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 nvoked at progra
2f5f0 6d 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 m startup in ord
2f600 65 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a er to register.*
2f610 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 * one or more st
2f620 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 atically linked
2f630 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 extensions that
2f640 77 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c will be availabl
2f650 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 e.** to all new
2f660 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2f670 74 69 6f 6e 73 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a tions]. {END}.**
2f680 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
2f690 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 stores a pointe
2f6a0 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 r to the extensi
2f6b0 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 20 74 on in an array t
2f6c0 68 61 74 20 69 73 0a 2a 2a 20 6f 62 74 61 69 6e hat is.** obtain
2f6d0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
2f6e0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 49 66 20 _malloc()]. If
2f6f0 79 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 you run a memory
2f700 20 6c 65 61 6b 20 63 68 65 63 6b 65 72 0a 2a 2a leak checker.**
2f710 20 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 61 6d on your program
2f720 20 61 6e 64 20 69 74 20 72 65 70 6f 72 74 73 20 and it reports
2f730 61 20 6c 65 61 6b 20 62 65 63 61 75 73 65 20 6f a leak because o
2f740 66 20 74 68 69 73 20 61 72 72 61 79 2c 20 69 6e f this array, in
2f750 76 6f 6b 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 voke.** [sqlite3
2f760 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 _reset_auto_exte
2f770 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 nsion()] prior t
2f780 6f 20 73 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 o shutdown to fr
2f790 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a ee the memory..*
2f7a0 2a 0a 2a 2a 20 7b 48 31 32 36 34 31 7d 20 54 68 *.** {H12641} Th
2f7b0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 is function regi
2f7c0 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69 sters an extensi
2f7d0 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 on entry point t
2f7e0 68 61 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 hat is.**
2f7f0 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 automatically
2f800 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 invoked wheneve
2f810 72 20 61 20 6e 65 77 20 5b 64 61 74 61 62 61 73 r a new [databas
2f820 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a e connection].**
2f830 20 20 20 20 20 20 20 20 20 20 69 73 20 6f 70 65 is ope
2f840 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ned using [sqlit
2f850 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
2f860 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a ite3_open16()],.
2f870 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b ** or [
2f880 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
2f890 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 )]..**.** {H1264
2f8a0 32 7d 20 44 75 70 6c 69 63 61 74 65 20 65 78 74 2} Duplicate ext
2f8b0 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 ensions are dete
2f8c0 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 cted so calling
2f8d0 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 this routine.**
2f8e0 20 20 20 20 20 20 20 20 20 6d 75 6c 74 69 70 6c multipl
2f8f0 65 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 e times with the
2f900 20 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 same extension
2f910 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a is harmless..**.
2f920 2a 2a 20 7b 48 31 32 36 34 33 7d 20 54 68 69 73 ** {H12643} This
2f930 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 routine stores
2f940 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
2f950 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e extension in an
2f960 20 61 72 72 61 79 0a 2a 2a 20 20 20 20 20 20 20 array.**
2f970 20 20 20 74 68 61 74 20 69 73 20 6f 62 74 61 69 that is obtai
2f980 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
2f990 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 3_malloc()]..**.
2f9a0 2a 2a 20 7b 48 31 32 36 34 34 7d 20 41 75 74 6f ** {H12644} Auto
2f9b0 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 matic extensions
2f9c0 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20 61 6c apply across al
2f9d0 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 53 51 l threads..*/.SQ
2f9e0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
2f9f0 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
2fa00 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
2fa10 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e lite3_auto_exten
2fa20 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 sion(void (*xEnt
2fa30 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b ryPoint)(void));
2fa40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2fa50 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 : Reset Automati
2fa60 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 c Extension Load
2fa70 69 6e 67 20 7b 48 31 32 36 36 30 7d 20 3c 53 32 ing {H12660} <S2
2fa80 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0500>.**.** This
2fa90 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c function disabl
2faa0 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c es all previousl
2fab0 79 20 72 65 67 69 73 74 65 72 65 64 20 61 75 74 y registered aut
2fac0 6f 6d 61 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73 omatic.** extens
2fad0 69 6f 6e 73 2e 20 7b 45 4e 44 7d 20 20 49 74 20 ions. {END} It
2fae0 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 undoes the effec
2faf0 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a 2a t of all prior.*
2fb00 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f * [sqlite3_auto_
2fb10 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61 6c extension()] cal
2fb20 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 ls..**.** {H1266
2fb30 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 1} This function
2fb40 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 disables all pr
2fb50 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 eviously registe
2fb60 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 red.**
2fb70 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 automatic extens
2fb80 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ions..**.** {H12
2fb90 36 36 32 7d 20 54 68 69 73 20 66 75 6e 63 74 69 662} This functi
2fba0 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 75 74 6f on disables auto
2fbb0 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 matic extensions
2fbc0 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e in all threads.
2fbd0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 .*/.SQLITE_API S
2fbe0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
2fbf0 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
2fc00 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
2fc10 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f et_auto_extensio
2fc20 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a n(void);../*.***
2fc30 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c *** EXPERIMENTAL
2fc40 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 - subject to ch
2fc50 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 ange without not
2fc60 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ice ************
2fc70 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 **.**.** The int
2fc80 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 erface to the vi
2fc90 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 rtual-table mech
2fca0 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 anism is current
2fcb0 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a ly considered.**
2fcc0 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e to be experimen
2fcd0 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 tal. The interf
2fce0 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 ace might change
2fcf0 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 in incompatible
2fd00 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 ways..** If thi
2fd10 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 s is a problem f
2fd20 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 or you, do not u
2fd30 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 se the interface
2fd40 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a at this time..*
2fd50 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 *.** When the vi
2fd60 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 rtual-table mech
2fd70 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 anism stabilizes
2fd80 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 , we will declar
2fd90 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 e the.** interfa
2fda0 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 ce fixed, suppor
2fdb0 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c t it indefinitel
2fdc0 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 y, and remove th
2fdd0 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a is comment..*/..
2fde0 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 /*.** Structures
2fdf0 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72 used by the vir
2fe00 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 tual table inter
2fe10 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 face.*/.typedef
2fe20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
2fe30 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 tab sqlite3_vtab
2fe40 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 ;.typedef struct
2fe50 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 sqlite3_index_i
2fe60 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 nfo sqlite3_inde
2fe70 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 x_info;.typedef
2fe80 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
2fe90 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 tab_cursor sqlit
2fea0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a e3_vtab_cursor;.
2feb0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
2fec0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 qlite3_module sq
2fed0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f lite3_module;../
2fee0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 *.** CAPI3REF: V
2fef0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a irtual Table Obj
2ff00 65 63 74 20 7b 48 31 38 30 30 30 7d 20 3c 53 32 ect {H18000} <S2
2ff10 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0400>.** KEYWORD
2ff20 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c S: sqlite3_modul
2ff30 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 e {virtual table
2ff40 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 20 45 58 50 45 module}.** EXPE
2ff50 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
2ff60 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20 73 his structure, s
2ff70 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 20 ometimes called
2ff80 61 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 a a "virtual tab
2ff90 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 le module", .**
2ffa0 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c defines the impl
2ffb0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 ementation of a
2ffc0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d [virtual tables]
2ffd0 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 . .** This stru
2ffe0 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d cture consists m
2fff0 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 ostly of methods
30000 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e for the module.
30010 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c .**.** A virtual
30020 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73 table module is
30030 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c created by fill
30040 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 74 ing in a persist
30050 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 ent.** instance
30060 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 of this structur
30070 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20 e and passing a
30080 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 pointer to that
30090 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b instance.** to [
300a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d sqlite3_create_m
300b0 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c odule()] or [sql
300c0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 ite3_create_modu
300d0 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 le_v2()]..** The
300e0 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65 registration re
300f0 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69 mains valid unti
30100 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 65 64 l it is replaced
30110 20 62 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a by a different.
30120 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74 ** module or unt
30130 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 il the [database
30140 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f connection] clo
30150 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e ses. The conten
30160 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72 t.** of this str
30170 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20 ucture must not
30180 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20 change while it
30190 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69 is registered wi
301a0 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61 th.** any databa
301b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a se connection..*
301c0 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 /.struct sqlite3
301d0 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 _module {. int
301e0 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 iVersion;. int
301f0 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 (*xCreate)(sqlit
30200 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c e3*, void *pAux,
30210 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
30220 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 int argc, const
30230 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 char *const*argv
30240 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
30250 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a sqlite3_vtab **
30260 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b ppVTab, char**);
30270 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 . int (*xConnec
30280 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 t)(sqlite3*, voi
30290 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 d *pAux,.
302a0 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 int argc
302b0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f , const char *co
302c0 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 nst*argv,.
302d0 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 sqlite3
302e0 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 _vtab **ppVTab,
302f0 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 char**);. int (
30300 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c *xBestIndex)(sql
30310 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
30320 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f , sqlite3_index_
30330 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a info*);. int (*
30340 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c xDisconnect)(sql
30350 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
30360 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 );. int (*xDest
30370 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 roy)(sqlite3_vta
30380 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 b *pVTab);. int
30390 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 (*xOpen)(sqlite
303a0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 3_vtab *pVTab, s
303b0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
303c0 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a or **ppCursor);.
303d0 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 int (*xClose)(
303e0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
303f0 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sor*);. int (*x
30400 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f Filter)(sqlite3_
30410 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e vtab_cursor*, in
30420 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 t idxNum, const
30430 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 char *idxStr,.
30440 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e in
30450 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f t argc, sqlite3_
30460 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 value **argv);.
30470 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 int (*xNext)(sq
30480 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
30490 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f r*);. int (*xEo
304a0 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f f)(sqlite3_vtab_
304b0 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 cursor*);. int
304c0 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 (*xColumn)(sqlit
304d0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c e3_vtab_cursor*,
304e0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
304f0 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 *, int);. int (
30500 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 *xRowid)(sqlite3
30510 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 _vtab_cursor*, s
30520 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 qlite3_int64 *pR
30530 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 owid);. int (*x
30540 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f Update)(sqlite3_
30550 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c vtab *, int, sql
30560 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 ite3_value **, s
30570 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b qlite3_int64 *);
30580 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 . int (*xBegin)
30590 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
305a0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 VTab);. int (*x
305b0 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 Sync)(sqlite3_vt
305c0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e ab *pVTab);. in
305d0 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c t (*xCommit)(sql
305e0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
305f0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c );. int (*xRoll
30600 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 back)(sqlite3_vt
30610 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e ab *pVTab);. in
30620 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f t (*xFindFunctio
30630 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 n)(sqlite3_vtab
30640 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 *pVtab, int nArg
30650 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
30660 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 ame,.
30670 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 void
30680 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 (**pxFunc)(sqli
30690 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
306a0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
306b0 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 ),.
306c0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a void *
306d0 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 *ppArg);. int (
306e0 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 *xRename)(sqlite
306f0 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 3_vtab *pVtab, c
30700 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 onst char *zNew)
30710 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ;.};../*.** CAPI
30720 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 3REF: Virtual Ta
30730 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 ble Indexing Inf
30740 6f 72 6d 61 74 69 6f 6e 20 7b 48 31 38 31 30 30 ormation {H18100
30750 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 } <S20400>.** KE
30760 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f YWORDS: sqlite3_
30770 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58 index_info.** EX
30780 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
30790 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 The sqlite3_ind
307a0 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 ex_info structur
307b0 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 e and its substr
307c0 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20 uctures is used
307d0 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 to.** pass infor
307e0 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 mation into and
307f0 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c receive the repl
30800 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73 y from the [xBes
30810 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f tIndex].** metho
30820 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 d of a [virtual
30830 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 table module].
30840 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72 The fields under
30850 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 **Inputs** are
30860 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f the.** inputs to
30870 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20 xBestIndex and
30880 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 are read-only.
30890 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72 xBestIndex inser
308a0 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 ts its.** result
308b0 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 s into the **Out
308c0 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a puts** fields..*
308d0 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 *.** The aConstr
308e0 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63 aint[] array rec
308f0 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 75 73 ords WHERE claus
30900 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 e constraints of
30910 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a the form:.**.**
30920 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 <pre>column OP
30930 65 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a expr</pre>.**.**
30940 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 where OP is =,
30950 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 <, <=, >
30960 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20 20 54 68 ;, or >=. Th
30970 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 e particular ope
30980 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 rator is.** stor
30990 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e ed in aConstrain
309a0 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64 t[].op. The ind
309b0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e ex of the column
309c0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a is stored in.**
309d0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 aConstraint[].i
309e0 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 Column. aConstr
309f0 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 aint[].usable is
30a00 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 TRUE if the.**
30a10 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68 expr on the righ
30a20 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20 t-hand side can
30a30 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e be evaluated (an
30a40 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74 d thus the const
30a50 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 raint.** is usab
30a60 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66 le) and false if
30a70 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a it cannot..**.*
30a80 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 * The optimizer
30a90 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e automatically in
30aa0 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 verts terms of t
30ab0 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 he form "expr OP
30ac0 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 column".** and
30ad0 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 makes other simp
30ae0 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 lifications to t
30af0 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 he WHERE clause
30b00 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f in an attempt to
30b10 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 .** get as many
30b20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 WHERE clause ter
30b30 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d ms into the form
30b40 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 shown above as
30b50 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 possible..** The
30b60 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 aConstraint[] a
30b70 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 rray only report
30b80 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 s WHERE clause t
30b90 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72 erms in the corr
30ba0 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74 ect.** form that
30bb0 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61 refer to the pa
30bc0 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c rticular virtual
30bd0 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65 table being que
30be0 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f ried..**.** Info
30bf0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 rmation about th
30c00 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 e ORDER BY claus
30c10 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 e is stored in a
30c20 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 OrderBy[]..** Ea
30c30 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 ch term of aOrde
30c40 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f rBy records a co
30c50 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 lumn of the ORDE
30c60 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a R BY clause..**.
30c70 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 49 6e 64 ** The [xBestInd
30c80 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 ex] method must
30c90 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 fill aConstraint
30ca0 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 Usage[] with inf
30cb0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 ormation.** abou
30cc0 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 t what parameter
30cd0 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 s to pass to xFi
30ce0 6c 74 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e lter. If argvIn
30cf0 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 dex>0 then.** th
30d00 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 e right-hand sid
30d10 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 e of the corresp
30d20 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 onding aConstrai
30d30 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 nt[] is evaluate
30d40 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 d.** and becomes
30d50 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 the argvIndex-t
30d60 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e h entry in argv.
30d70 20 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 If aConstraint
30d80 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 Usage[].omit.**
30d90 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 is true, then th
30da0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 e constraint is
30db0 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 assumed to be fu
30dc0 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 lly handled by t
30dd0 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 he.** virtual ta
30de0 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 ble and is not c
30df0 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 hecked again by
30e00 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 SQLite..**.** Th
30e10 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 e idxNum and idx
30e20 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 Ptr values are r
30e30 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 ecorded and pass
30e40 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b ed into the.** [
30e50 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e xFilter] method.
30e60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 .** [sqlite3_fre
30e70 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 e()] is used to
30e80 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61 free idxPtr if a
30e90 6e 64 20 6f 6e 6c 79 20 69 66 66 0a 2a 2a 20 6e nd only iff.** n
30ea0 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 eedToFreeIdxPtr
30eb0 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 is true..**.** T
30ec0 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d he orderByConsum
30ed0 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 ed means that ou
30ee0 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74 tput from [xFilt
30ef0 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c er]/[xNext] will
30f00 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 occur in.** the
30f10 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 correct order t
30f20 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 o satisfy the OR
30f30 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f DER BY clause so
30f40 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 that no separat
30f50 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 e.** sorting ste
30f60 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a p is required..*
30f70 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61 74 *.** The estimat
30f80 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20 edCost value is
30f90 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 an estimate of t
30fa0 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 he cost of doing
30fb0 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c the.** particul
30fc0 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 ar lookup. A fu
30fd0 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62 ll scan of a tab
30fe0 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65 le with N entrie
30ff0 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a s should have.**
31000 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 a cost of N. A
31010 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f binary search o
31020 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 f a table of N e
31030 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 ntries should ha
31040 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 ve a.** cost of
31050 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f approximately lo
31060 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 g(N)..*/.struct
31070 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e sqlite3_index_in
31080 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 fo {. /* Inputs
31090 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 */. int nConst
310a0 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 raint;
310b0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e /* Number of en
310c0 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 tries in aConstr
310d0 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 aint */. struct
310e0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 sqlite3_index_c
310f0 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 onstraint {.
31100 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 int iColumn;
31110 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f /* Co
31120 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e lumn on left-han
31130 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 d side of constr
31140 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 aint */. uns
31150 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 igned char op;
31160 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 /* Constr
31170 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f aint operator */
31180 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 . unsigned c
31190 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 har usable;
311a0 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20 /* True if this
311b0 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 constraint is us
311c0 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 able */. int
311d0 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 iTermOffset;
311e0 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 /* Used i
311f0 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 nternally - xBes
31200 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 tIndex should ig
31210 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f nore */. } *aCo
31220 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 nstraint;
31230 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 /* Table of
31240 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f WHERE clause co
31250 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 nstraints */. i
31260 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 nt nOrderBy;
31270 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d /* Num
31280 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 ber of terms in
31290 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 the ORDER BY cla
312a0 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 use */. struct
312b0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 sqlite3_index_or
312c0 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 derby {. int
312d0 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 iColumn;
312e0 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e /* Column
312f0 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 number */.
31300 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 unsigned char de
31310 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 sc; /* Tru
31320 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c e for DESC. Fal
31330 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 se for ASC. */.
31340 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 } *aOrderBy;
31350 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 /* T
31360 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 he ORDER BY clau
31370 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 se */. /* Outpu
31380 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 ts */. struct s
31390 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e qlite3_index_con
313a0 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a straint_usage {.
313b0 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 int argvInde
313c0 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 x; /*
313d0 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e if >0, constrain
313e0 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 t is part of arg
313f0 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a v to xFilter */.
31400 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 unsigned cha
31410 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 r omit; /*
31420 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 Do not code a te
31430 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 st for this cons
31440 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 traint */. } *a
31450 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b ConstraintUsage;
31460 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 . int idxNum;
31470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
31480 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 Number used to
31490 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 identify the ind
314a0 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 ex */. char *id
314b0 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 xStr;
314c0 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f /* String, po
314d0 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 ssibly obtained
314e0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c from sqlite3_mal
314f0 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 loc */. int nee
31500 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 dToFreeIdxStr;
31510 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 /* Free idxS
31520 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 tr using sqlite3
31530 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20 _free() if true
31540 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 */. int orderBy
31550 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 Consumed;
31560 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 /* True if outpu
31570 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 t is already ord
31580 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 ered */. double
31590 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 estimatedCost;
315a0 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 /* Estimate
315b0 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 d cost of using
315c0 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b this index */.};
315d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
315e0 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
315f0 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 _EQ 2.#define
31600 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
31610 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 NSTRAINT_GT 4
31620 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
31630 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
31640 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 _LE 8.#define
31650 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
31660 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 NSTRAINT_LT 1
31670 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 6.#define SQLITE
31680 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e _INDEX_CONSTRAIN
31690 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 T_GE 32.#defi
316a0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f ne SQLITE_INDEX_
316b0 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 CONSTRAINT_MATCH
316c0 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 64../*.** CAPI3
316d0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 REF: Register A
316e0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d Virtual Table Im
316f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 31 plementation {H1
31700 38 32 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 8200} <S20400>.*
31710 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
31720 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
31730 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 67 e is used to reg
31740 69 73 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72 ister a new [vir
31750 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c tual table modul
31760 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 4d 6f 64 75 e] name..** Modu
31770 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 le names must be
31780 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f registered befo
31790 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61 re.** creating a
317a0 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 new [virtual ta
317b0 62 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d ble] using the m
317c0 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 odule, or before
317d0 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65 using a.** pree
317e0 78 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c xisting [virtual
317f0 20 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20 table] for the
31800 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 module..**.** Th
31810 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73 e module name is
31820 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74 registered on t
31830 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
31840 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 nection] specifi
31850 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 ed.** by the fir
31860 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 st parameter. T
31870 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d he name of the m
31880 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20 62 odule is given b
31890 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64 y the .** second
318a0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 parameter. The
318b0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
318c0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
318d0 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e .** the implemen
318e0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 76 tation of the [v
318f0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 irtual table mod
31900 75 6c 65 5d 2e 20 20 20 54 68 65 20 66 6f 75 72 ule]. The four
31910 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 th.** parameter
31920 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 is an arbitrary
31930 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e client data poin
31940 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 ter that is pass
31950 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e ed through.** in
31960 74 6f 20 74 68 65 20 5b 78 43 72 65 61 74 65 5d to the [xCreate]
31970 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 and [xConnect]
31980 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20 76 methods of the v
31990 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 irtual table mod
319a0 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65 ule.** when a ne
319b0 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 w virtual table
319c0 69 73 20 62 65 20 62 65 69 6e 67 20 63 72 65 61 is be being crea
319d0 74 65 64 20 6f 72 20 72 65 69 6e 69 74 69 61 6c ted or reinitial
319e0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ized..**.** This
319f0 20 69 6e 74 65 72 66 61 63 65 20 68 61 73 20 65 interface has e
31a00 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 xactly the same
31a10 65 66 66 65 63 74 20 61 73 20 63 61 6c 6c 69 6e effect as callin
31a20 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 g.** [sqlite3_cr
31a30 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 eate_module_v2()
31a40 5d 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 63 6c ] with a NULL cl
31a50 69 65 6e 74 20 64 61 74 61 20 64 65 73 74 72 75 ient data destru
31a60 63 74 6f 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ctor..*/.SQLITE_
31a70 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
31a80 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
31a90 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 _API SQLITE_EXPE
31aa0 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c RIMENTAL int sql
31ab0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 ite3_create_modu
31ac0 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 le(. sqlite3 *d
31ad0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 b,
31ae0 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 /* SQLite conne
31af0 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 ction to registe
31b00 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f r module with */
31b10 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
31b20 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a Name, /*
31b30 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 Name of the mod
31b40 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 ule */. const s
31b50 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 qlite3_module *p
31b60 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 , /* Methods f
31b70 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f or the module */
31b80 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 . void *pClient
31b90 44 61 74 61 20 20 20 20 20 20 20 20 20 20 2f 2a Data /*
31ba0 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 Client data for
31bb0 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 xCreate/xConnec
31bc0 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 t */.);../*.** C
31bd0 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 API3REF: Registe
31be0 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c r A Virtual Tabl
31bf0 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e Implementation
31c00 20 7b 48 31 38 32 31 30 7d 20 3c 53 32 30 34 30 {H18210} <S2040
31c10 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
31c20 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f AL.**.** This ro
31c30 75 74 69 6e 65 20 69 73 20 69 64 65 6e 74 69 63 utine is identic
31c40 61 6c 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 al to the [sqlit
31c50 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 e3_create_module
31c60 28 29 5d 20 6d 65 74 68 6f 64 2c 0a 2a 2a 20 65 ()] method,.** e
31c70 78 63 65 70 74 20 74 68 61 74 20 69 74 20 68 61 xcept that it ha
31c80 73 20 61 6e 20 65 78 74 72 61 20 70 61 72 61 6d s an extra param
31c90 65 74 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 eter to specify
31ca0 0a 2a 2a 20 61 20 64 65 73 74 72 75 63 74 6f 72 .** a destructor
31cb0 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 function for th
31cc0 65 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f e client data po
31cd0 69 6e 74 65 72 2e 20 20 53 51 4c 69 74 65 20 77 inter. SQLite w
31ce0 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 ill.** invoke th
31cf0 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e e destructor fun
31d00 63 74 69 6f 6e 20 28 69 66 20 69 74 20 69 73 20 ction (if it is
31d10 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 not NULL) when S
31d20 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 QLite.** no long
31d30 65 72 20 6e 65 65 64 73 20 74 68 65 20 70 43 6c er needs the pCl
31d40 69 65 6e 74 44 61 74 61 20 70 6f 69 6e 74 65 72 ientData pointer
31d50 2e 20 20 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 . .*/.SQLITE_AP
31d60 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
31d70 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
31d80 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 PI SQLITE_EXPERI
31d90 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 MENTAL int sqlit
31da0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 e3_create_module
31db0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v2(. sqlite3 *
31dc0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 db,
31dd0 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e /* SQLite conn
31de0 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 ection to regist
31df0 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a er module with *
31e00 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
31e10 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f zName, /
31e20 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f * Name of the mo
31e30 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 dule */. const
31e40 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a sqlite3_module *
31e50 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 p, /* Methods
31e60 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a for the module *
31e70 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e /. void *pClien
31e80 74 44 61 74 61 2c 20 20 20 20 20 20 20 20 20 2f tData, /
31e90 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f * Client data fo
31ea0 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 r xCreate/xConne
31eb0 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 ct */. void(*xD
31ec0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 estroy)(void*)
31ed0 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 /* Module des
31ee0 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e tructor function
31ef0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
31f00 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 PI3REF: Virtual
31f10 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f Table Instance O
31f20 62 6a 65 63 74 20 7b 48 31 38 30 31 30 7d 20 3c bject {H18010} <
31f30 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S20400>.** KEYWO
31f40 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 RDS: sqlite3_vta
31f50 62 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 b.** EXPERIMENTA
31f60 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 L.**.** Every [v
31f70 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 irtual table mod
31f80 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ule] implementat
31f90 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c ion uses a subcl
31fa0 61 73 73 0a 2a 2a 20 6f 66 20 74 68 65 20 66 6f ass.** of the fo
31fb0 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 llowing structur
31fc0 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 e to describe a
31fd0 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 particular insta
31fe0 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 nce.** of the [v
31ff0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20 irtual table].
32000 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77 69 Each subclass wi
32010 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 ll.** be tailore
32020 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 d to the specifi
32030 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d c needs of the m
32040 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 odule implementa
32050 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 tion..** The pur
32060 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 pose of this sup
32070 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 erclass is to de
32080 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 fine certain fie
32090 6c 64 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 lds that are.**
320a0 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f common to all mo
320b0 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 dule implementat
320c0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 ions..**.** Virt
320d0 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f ual tables metho
320e0 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 ds can set an er
320f0 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 ror message by a
32100 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 ssigning a.** st
32110 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 ring obtained fr
32120 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 om [sqlite3_mpri
32130 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 ntf()] to zErrMs
32140 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73 g. The method s
32150 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 hould.** take ca
32160 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f re that any prio
32170 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65 65 r string is free
32180 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b d by a call to [
32190 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a sqlite3_free()].
321a0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 ** prior to assi
321b0 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 gning a new stri
321c0 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 ng to zErrMsg.
321d0 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 After the error
321e0 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 message.** is de
321f0 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 livered up to th
32200 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 e client applica
32210 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 tion, the string
32220 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 will be automat
32230 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 ically.** freed
32240 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 by sqlite3_free(
32250 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 ) and the zErrMs
32260 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 g field will be
32270 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 zeroed..*/.struc
32280 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b t sqlite3_vtab {
32290 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 . const sqlite3
322a0 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 _module *pModule
322b0 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 ; /* The module
322c0 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 for this virtua
322d0 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 l table */. int
322e0 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 nRef;
322f0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
32300 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a NO LONGER USED *
32310 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 /. char *zErrMs
32320 67 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 g;
32330 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 /* Error mes
32340 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 sage from sqlite
32350 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 3_mprintf() */.
32360 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c /* Virtual tabl
32370 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
32380 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 s will typically
32390 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 add additional
323a0 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a fields */.};../*
323b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 .** CAPI3REF: Vi
323c0 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 rtual Table Curs
323d0 6f 72 20 4f 62 6a 65 63 74 20 20 7b 48 31 38 30 or Object {H180
323e0 32 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 20} <S20400>.**
323f0 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 KEYWORDS: sqlite
32400 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 3_vtab_cursor {v
32410 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 75 72 irtual table cur
32420 73 6f 72 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 sor}.** EXPERIME
32430 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 NTAL.**.** Every
32440 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 [virtual table
32450 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e module] implemen
32460 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 tation uses a su
32470 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a bclass of the.**
32480 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 following struc
32490 74 75 72 65 20 74 6f 20 64 65 73 63 72 69 62 65 ture to describe
324a0 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f cursors that po
324b0 69 6e 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 int into the.**
324c0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 [virtual table]
324d0 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 and are used.**
324e0 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 to loop through
324f0 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c the virtual tabl
32500 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 e. Cursors are
32510 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 created using th
32520 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f e.** [sqlite3_mo
32530 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 dule.xOpen | xOp
32540 65 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 en] method of th
32550 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 e module and are
32560 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 destroyed.** by
32570 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f the [sqlite3_mo
32580 64 75 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 dule.xClose | xC
32590 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 lose] method. C
325a0 75 73 73 6f 72 73 20 61 72 65 20 75 73 65 64 0a ussors are used.
325b0 2a 2a 20 62 79 20 74 68 65 20 5b 78 46 69 6c 74 ** by the [xFilt
325c0 65 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 er], [xNext], [x
325d0 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c Eof], [xColumn],
325e0 20 61 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 and [xRowid] me
325f0 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 thods.** of the
32600 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f module. Each mo
32610 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 dule implementat
32620 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a ion will define.
32630 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f ** the content o
32640 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 f a cursor struc
32650 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 ture to suit its
32660 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a own needs..**.*
32670 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 * This superclas
32680 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 s exists in orde
32690 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c r to define fiel
326a0 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 ds of the cursor
326b0 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d that.** are com
326c0 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 mon to all imple
326d0 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 mentations..*/.s
326e0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 truct sqlite3_vt
326f0 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 ab_cursor {. sq
32700 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 lite3_vtab *pVta
32710 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 b; /* Virtu
32720 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 al table of this
32730 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 cursor */. /*
32740 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d Virtual table im
32750 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 plementations wi
32760 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 ll typically add
32770 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c additional fiel
32780 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 ds */.};../*.**
32790 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 CAPI3REF: Declar
327a0 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20 e The Schema Of
327b0 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 A Virtual Table
327c0 7b 48 31 38 32 38 30 7d 20 3c 53 32 30 34 30 30 {H18280} <S20400
327d0 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
327e0 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 43 72 L.**.** The [xCr
327f0 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e eate] and [xConn
32800 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 ect] methods of
32810 61 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 a.** [virtual ta
32820 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c ble module] call
32830 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 0a this interface.
32840 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68 ** to declare th
32850 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 e format (the na
32860 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 65 mes and datatype
32870 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 s of the columns
32880 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 ) of.** the virt
32890 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20 ual tables they
328a0 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 53 51 implement..*/.SQ
328b0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
328c0 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
328d0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
328e0 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e _EXPERIMENTAL in
328f0 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 t sqlite3_declar
32900 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c e_vtab(sqlite3*,
32910 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 const char *zSQ
32920 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 L);../*.** CAPI3
32930 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 REF: Overload A
32940 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 Function For A V
32950 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 48 31 irtual Table {H1
32960 38 33 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 8300} <S20400>.*
32970 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
32980 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 *.** Virtual tab
32990 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 les can provide
329a0 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c alternative impl
329b0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 ementations of f
329c0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e unctions.** usin
329d0 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 g the [xFindFunc
329e0 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 tion] method of
329f0 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 the [virtual tab
32a00 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a le module]. .**
32a10 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 But global vers
32a20 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 ions of those fu
32a30 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 nctions.** must
32a40 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 exist in order t
32a50 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e o be overloaded.
32a60 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 .**.** This API
32a70 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f makes sure a glo
32a80 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 bal version of a
32a90 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
32aa0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e particular.** n
32ab0 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f ame and number o
32ac0 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 f parameters exi
32ad0 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 sts. If no such
32ae0 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 function exists
32af0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 .** before this
32b00 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 API is called, a
32b10 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 new function is
32b20 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 created. The i
32b30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a mplementation.**
32b40 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 of the new func
32b50 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 tion always caus
32b60 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 es an exception
32b70 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 to be thrown. S
32b80 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e o.** the new fun
32b90 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f ction is not goo
32ba0 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 d for anything b
32bb0 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f y itself. Its o
32bc0 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 nly.** purpose i
32bd0 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 s to be a placeh
32be0 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 older function t
32bf0 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c hat can be overl
32c00 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 oaded.** by a [v
32c10 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a irtual table]..*
32c20 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c /.SQLITE_API SQL
32c30 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
32c40 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
32c50 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 LITE_EXPERIMENTA
32c60 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 L int sqlite3_ov
32c70 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 erload_function(
32c80 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 sqlite3*, const
32c90 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c char *zFuncName,
32ca0 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a int nArg);../*.
32cb0 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 ** The interface
32cc0 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d to the virtual-
32cd0 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 table mechanism
32ce0 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62 defined above (b
32cf0 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 ack up.** to a c
32d00 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c omment remarkabl
32d10 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 y similar to thi
32d20 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e s one) is curren
32d30 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a tly considered.*
32d40 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 * to be experime
32d50 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 ntal. The inter
32d60 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 face might chang
32d70 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c e in incompatibl
32d80 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 e ways..** If th
32d90 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 is is a problem
32da0 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 for you, do not
32db0 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 use the interfac
32dc0 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a e at this time..
32dd0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 **.** When the v
32de0 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 irtual-table mec
32df0 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 hanism stabilize
32e00 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 s, we will decla
32e10 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 re the.** interf
32e20 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f ace fixed, suppo
32e30 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 rt it indefinite
32e40 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 ly, and remove t
32e50 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a his comment..**.
32e60 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e ****** EXPERIMEN
32e70 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f TAL - subject to
32e80 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 change without
32e90 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a notice *********
32ea0 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 *****.*/../*.**
32eb0 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64 CAPI3REF: A Hand
32ec0 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c le To An Open BL
32ed0 4f 42 20 7b 48 31 37 38 30 30 7d 20 3c 53 33 30 OB {H17800} <S30
32ee0 32 33 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 230>.** KEYWORDS
32ef0 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 : {BLOB handle}
32f00 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a {BLOB handles}.*
32f10 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 *.** An instance
32f20 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 of this object
32f30 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 represents an op
32f40 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68 en BLOB on which
32f50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f .** [sqlite3_blo
32f60 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 b_open | increme
32f70 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 ntal BLOB I/O] c
32f80 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 2e an be performed.
32f90 0a 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66 20 74 .** Objects of t
32fa0 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72 65 his type are cre
32fb0 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ated by [sqlite3
32fc0 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a _blob_open()].**
32fd0 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62 and destroyed b
32fe0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f y [sqlite3_blob_
32ff0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 close()]..** The
33000 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 [sqlite3_blob_r
33010 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ead()] and [sqli
33020 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 te3_blob_write()
33030 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ] interfaces.**
33040 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 can be used to r
33050 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 ead or write sma
33060 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f ll subsections o
33070 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 54 f the BLOB..** T
33080 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 he [sqlite3_blob
33090 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 _bytes()] interf
330a0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
330b0 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 size of the BLOB
330c0 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 in bytes..*/.ty
330d0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
330e0 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 ite3_blob sqlite
330f0 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 3_blob;../*.** C
33100 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 API3REF: Open A
33110 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 BLOB For Increme
33120 6e 74 61 6c 20 49 2f 4f 20 7b 48 31 37 38 31 30 ntal I/O {H17810
33130 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a } <S30230>.**.**
33140 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 73 This interfaces
33150 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68 opens a [BLOB h
33160 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20 andle | handle]
33170 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61 to the BLOB loca
33180 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52 ted.** in row iR
33190 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 ow, column zColu
331a0 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 mn, table zTable
331b0 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62 in database zDb
331c0 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f ;.** in other wo
331d0 72 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42 4c rds, the same BL
331e0 4f 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65 OB that would be
331f0 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a selected by:.**
33200 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 .** <pre>.**
33210 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 SELECT zColumn
33220 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 FROM zDb.zTable
33230 57 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20 WHERE [rowid] =
33240 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 20 iRow;.** </pre>
33250 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 {END}.**.** If t
33260 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 he flags paramet
33270 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 er is non-zero,
33280 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 then the BLOB is
33290 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 opened for read
332a0 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 61 63 .** and write ac
332b0 63 65 73 73 2e 20 49 66 20 69 74 20 69 73 20 7a cess. If it is z
332c0 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 ero, the BLOB is
332d0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 opened for read
332e0 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4e access..**.** N
332f0 6f 74 65 20 74 68 61 74 20 74 68 65 20 64 61 74 ote that the dat
33300 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f abase name is no
33310 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 74 t the filename t
33320 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 hat contains.**
33330 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 the database but
33340 20 72 61 74 68 65 72 20 74 68 65 20 73 79 6d 62 rather the symb
33350 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68 65 olic name of the
33360 20 64 61 74 61 62 61 73 65 20 74 68 61 74 0a 2a database that.*
33370 2a 20 69 73 20 61 73 73 69 67 6e 65 64 20 77 68 * is assigned wh
33380 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
33390 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69 is connected usi
333a0 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 ng [ATTACH]..**
333b0 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 For the main dat
333c0 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20 abase file, the
333d0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 database name is
333e0 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 46 6f 72 20 "main"..** For
333f0 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65 TEMP tables, the
33400 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 database name i
33410 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 s "temp"..**.**
33420 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c On success, [SQL
33430 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 ITE_OK] is retur
33440 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 ned and the new
33450 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 [BLOB handle] is
33460 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a written.** to *
33470 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 ppBlob. Otherwis
33480 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 e an [error code
33490 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e ] is returned an
334a0 64 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74 d *ppBlob is set
334b0 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c .** to be a null
334c0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 69 pointer..** Thi
334d0 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 s function sets
334e0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
334f0 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 nnection] error
33500 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 code and message
33510 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 .** accessible v
33520 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 ia [sqlite3_errc
33530 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ode()] and [sqli
33540 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e te3_errmsg()] an
33550 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e d related.** fun
33560 63 74 69 6f 6e 73 2e 20 20 4e 6f 74 65 20 74 68 ctions. Note th
33570 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 at the *ppBlob v
33580 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79 ariable is alway
33590 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e s initialized in
335a0 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d a.** way that m
335b0 61 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f 20 akes it safe to
335c0 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f invoke [sqlite3_
335d0 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e blob_close()] on
335e0 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 *ppBlob.** rega
335f0 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 rdless of the su
33600 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 ccess or failure
33610 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 of this routine
33620 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 ..**.** If the r
33630 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 ow that a BLOB h
33640 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 andle points to
33650 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 is modified by a
33660 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b n.** [UPDATE], [
33670 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b DELETE], or by [
33680 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 ON CONFLICT] sid
33690 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 e-effects.** the
336a0 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c n the BLOB handl
336b0 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 e is marked as "
336c0 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 expired"..** Thi
336d0 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 s is true if any
336e0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 column of the r
336f0 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 ow is changed, e
33700 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 ven a column.**
33710 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f other than the o
33720 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 ne the BLOB hand
33730 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a 2a le is open on..*
33740 2a 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 * Calls to [sqli
33750 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d te3_blob_read()]
33760 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c and [sqlite3_bl
33770 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a ob_write()] for.
33780 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f ** a expired BLO
33790 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 B handle fail wi
337a0 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64 th an return cod
337b0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f e of [SQLITE_ABO
337c0 52 54 5d 2e 0a 2a 2a 20 43 68 61 6e 67 65 73 20 RT]..** Changes
337d0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42 written into a B
337e0 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65 LOB prior to the
337f0 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61 BLOB expiring a
33800 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 61 re not.** rollba
33810 63 6b 20 62 79 20 74 68 65 20 65 78 70 69 72 61 ck by the expira
33820 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 tion of the BLOB
33830 2e 20 20 53 75 63 68 20 63 68 61 6e 67 65 73 20 . Such changes
33840 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a will eventually.
33850 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 ** commit if the
33860 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e transaction con
33870 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 tinues to comple
33880 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 73 65 20 tion..**.** Use
33890 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f the [sqlite3_blo
338a0 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 b_bytes()] inter
338b0 66 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e face to determin
338c0 65 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a e the size of.**
338d0 20 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 the opened blob
338e0 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 61 . The size of a
338f0 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 blob may not be
33900 20 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73 changed by this
33910 0a 2a 2a 20 75 6e 64 65 72 66 61 63 65 2e 20 20 .** underface.
33920 55 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d Use the [UPDATE]
33930 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 SQL command to
33940 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 change the size
33950 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a of a.** blob..**
33960 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
33970 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 _bind_zeroblob()
33980 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 ] and [sqlite3_r
33990 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 esult_zeroblob()
339a0 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ] interfaces.**
339b0 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e and the built-in
339c0 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 [zeroblob] SQL
339d0 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 function can be
339e0 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65 64 used, if desired
339f0 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61 ,.** to create a
33a00 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69 n empty, zero-fi
33a10 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69 lled blob in whi
33a20 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 ch to read or wr
33a30 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69 ite using.** thi
33a40 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a s interface..**.
33a50 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65 ** To avoid a re
33a60 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65 source leak, eve
33a70 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 ry open [BLOB ha
33a80 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65 ndle] should eve
33a90 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 ntually.** be re
33aa0 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c leased by a call
33ab0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f to [sqlite3_blo
33ac0 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a b_close()]..**.*
33ad0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
33ae0 2a 2a 20 5b 48 31 37 38 31 33 5d 20 5b 48 31 37 ** [H17813] [H17
33af0 38 31 34 5d 20 5b 48 31 37 38 31 36 5d 20 5b 48 814] [H17816] [H
33b00 31 37 38 31 39 5d 20 5b 48 31 37 38 32 31 5d 20 17819] [H17821]
33b10 5b 48 31 37 38 32 34 5d 0a 2a 2f 0a 53 51 4c 49 [H17824].*/.SQLI
33b20 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
33b30 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
33b40 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
33b50 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 te3_blob_open(.
33b60 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e sqlite3*,. con
33b70 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 st char *zDb,.
33b80 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 const char *zTab
33b90 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 le,. const char
33ba0 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c *zColumn,. sql
33bb0 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c ite3_int64 iRow,
33bc0 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 . int flags,.
33bd0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 sqlite3_blob **p
33be0 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 pBlob.);../*.**
33bf0 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 CAPI3REF: Close
33c00 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 20 7b 48 A BLOB Handle {H
33c10 31 37 38 33 30 7d 20 3c 53 33 30 32 33 30 3e 0a 17830} <S30230>.
33c20 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 73 20 61 6e 20 **.** Closes an
33c30 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c open [BLOB handl
33c40 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e e]..**.** Closin
33c50 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 g a BLOB shall c
33c60 61 75 73 65 20 74 68 65 20 63 75 72 72 65 6e 74 ause the current
33c70 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 transaction to
33c80 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 commit.** if the
33c90 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 re are no other
33ca0 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e BLOBs, no pendin
33cb0 67 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 g prepared state
33cc0 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a ments, and the.*
33cd0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
33ce0 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 ction is in [aut
33cf0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a ocommit mode]..*
33d00 2a 20 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 * If any writes
33d10 77 65 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 were made to the
33d20 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 BLOB, they migh
33d30 74 20 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 t be held in cac
33d40 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 he.** until the
33d50 63 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 close operation
33d60 69 66 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 if they will fit
33d70 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 ..**.** Closing
33d80 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66 the BLOB often f
33d90 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e 67 65 orces the change
33da0 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b s.** out to disk
33db0 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 20 49 and so if any I
33dc0 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 72 2c /O errors occur,
33dd0 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c they will likel
33de0 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74 68 y occur.** at th
33df0 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 e time when the
33e00 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e 20 BLOB is closed.
33e10 20 41 6e 79 20 65 72 72 6f 72 73 20 74 68 61 74 Any errors that
33e20 20 6f 63 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a occur during.**
33e30 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 72 65 70 closing are rep
33e40 6f 72 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a orted as a non-z
33e50 65 72 6f 20 72 65 74 75 72 6e 20 76 61 6c 75 65 ero return value
33e60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 42 4c 4f 42 ..**.** The BLOB
33e70 20 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e is closed uncon
33e80 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 ditionally. Eve
33e90 6e 20 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e n if this routin
33ea0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 e returns.** an
33eb0 65 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 error code, the
33ec0 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c BLOB is still cl
33ed0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c osed..**.** Call
33ee0 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ing this routine
33ef0 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f 69 with a null poi
33f00 6e 74 65 72 20 28 77 68 69 63 68 20 61 73 20 77 nter (which as w
33f10 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 ould be returned
33f20 0a 2a 2a 20 62 79 20 66 61 69 6c 65 64 20 63 61 .** by failed ca
33f30 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 ll to [sqlite3_b
33f40 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20 lob_open()]) is
33f50 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 a harmless no-op
33f60 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
33f70 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 33 33 ents:.** [H17833
33f80 5d 20 5b 48 31 37 38 33 36 5d 20 5b 48 31 37 38 ] [H17836] [H178
33f90 33 39 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 39].*/.SQLITE_AP
33fa0 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
33fb0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
33fc0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
33fd0 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 lob_close(sqlite
33fe0 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 3_blob *);../*.*
33ff0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 75 * CAPI3REF: Retu
34000 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41 rn The Size Of A
34010 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 48 31 37 n Open BLOB {H17
34020 38 34 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 840} <S30230>.**
34030 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20 .** Returns the
34040 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66 size in bytes of
34050 20 74 68 65 20 42 4c 4f 42 20 61 63 63 65 73 73 the BLOB access
34060 69 62 6c 65 20 76 69 61 20 74 68 65 20 0a 2a 2a ible via the .**
34070 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 70 successfully op
34080 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c ened [BLOB handl
34090 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20 61 e] in its only a
340a0 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 0a 2a 2a rgument. The.**
340b0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 62 6c 6f incremental blo
340c0 62 20 49 2f 4f 20 72 6f 75 74 69 6e 65 73 20 63 b I/O routines c
340d0 61 6e 20 6f 6e 6c 79 20 72 65 61 64 20 6f 72 20 an only read or
340e0 6f 76 65 72 77 72 69 74 69 6e 67 20 65 78 69 73 overwriting exis
340f0 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20 63 6f 6e ting.** blob con
34100 74 65 6e 74 3b 20 74 68 65 79 20 63 61 6e 6e 6f tent; they canno
34110 74 20 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a t change the siz
34120 65 20 6f 66 20 61 20 62 6c 6f 62 2e 0a 2a 2a 0a e of a blob..**.
34130 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
34140 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 only works on a
34150 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 [BLOB handle] wh
34160 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 ich has been cre
34170 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 ated.** by a pri
34180 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 or successful ca
34190 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 ll to [sqlite3_b
341a0 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 lob_open()] and
341b0 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a which has not.**
341c0 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 been closed by
341d0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c [sqlite3_blob_cl
341e0 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 ose()]. Passing
341f0 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 any other point
34200 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 er in.** to this
34210 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 routine results
34220 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e in undefined an
34230 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 d probably undes
34240 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e irable behavior.
34250 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
34260 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 34 33 5d nts:.** [H17843]
34270 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 .*/.SQLITE_API S
34280 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
34290 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
342a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 int sqlite3_blob
342b0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 _bytes(sqlite3_b
342c0 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 lob *);../*.** C
342d0 41 50 49 33 52 45 46 3a 20 52 65 61 64 20 44 61 API3REF: Read Da
342e0 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 ta From A BLOB I
342f0 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 ncrementally {H1
34300 37 38 35 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 7850} <S30230>.*
34310 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
34320 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 on is used to re
34330 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 ad data from an
34340 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c open [BLOB handl
34350 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c e] into a.** cal
34360 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 ler-supplied buf
34370 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 fer. N bytes of
34380 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 data are copied
34390 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a into buffer Z.**
343a0 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 from the open B
343b0 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 LOB, starting at
343c0 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e offset iOffset.
343d0 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 .**.** If offset
343e0 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 iOffset is less
343f0 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 than N bytes fr
34400 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 om the end of th
34410 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 e BLOB,.** [SQLI
34420 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 TE_ERROR] is ret
34430 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 urned and no dat
34440 61 20 69 73 20 72 65 61 64 2e 20 20 49 66 20 4e a is read. If N
34450 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a 2a or iOffset is.*
34460 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f * less than zero
34470 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d , [SQLITE_ERROR]
34480 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 is returned and
34490 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 no data is read
344a0 2e 0a 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f 66 ..** The size of
344b0 20 74 68 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 the blob (and h
344c0 65 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d ence the maximum
344d0 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 value of N+iOff
344e0 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 set).** can be d
344f0 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 etermined using
34500 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f the [sqlite3_blo
34510 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 b_bytes()] inter
34520 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 face..**.** An a
34530 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 ttempt to read f
34540 72 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b rom an expired [
34550 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 BLOB handle] fai
34560 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 ls with an.** er
34570 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c ror code of [SQL
34580 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a ITE_ABORT]..**.*
34590 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 * On success, SQ
345a0 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 LITE_OK is retur
345b0 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 ned..** Otherwis
345c0 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 e, an [error cod
345d0 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 e] or an [extend
345e0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 ed error code] i
345f0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
34600 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f * This routine o
34610 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b nly works on a [
34620 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 BLOB handle] whi
34630 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 ch has been crea
34640 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f ted.** by a prio
34650 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c r successful cal
34660 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c l to [sqlite3_bl
34670 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 ob_open()] and w
34680 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 hich has not.**
34690 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b been closed by [
346a0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f sqlite3_blob_clo
346b0 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 se()]. Passing
346c0 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 any other pointe
346d0 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 r in.** to this
346e0 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 routine results
346f0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 in undefined and
34700 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 probably undesi
34710 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a rable behavior..
34720 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
34730 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 [sqlite3_blob_wr
34740 69 74 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 ite()]..**.** Re
34750 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
34760 48 31 37 38 35 33 5d 20 5b 48 31 37 38 35 36 5d H17853] [H17856]
34770 20 5b 48 31 37 38 35 39 5d 20 5b 48 31 37 38 36 [H17859] [H1786
34780 32 5d 20 5b 48 31 37 38 36 33 5d 20 5b 48 31 37 2] [H17863] [H17
34790 38 36 35 5d 20 5b 48 31 37 38 36 38 5d 0a 2a 2f 865] [H17868].*/
347a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
347b0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
347c0 49 20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 I SQLITE_API int
347d0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 sqlite3_blob_re
347e0 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 ad(sqlite3_blob
347f0 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 *, void *Z, int
34800 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b N, int iOffset);
34810 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
34820 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 : Write Data Int
34830 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 o A BLOB Increme
34840 6e 74 61 6c 6c 79 20 7b 48 31 37 38 37 30 7d 20 ntally {H17870}
34850 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S30230>.**.** T
34860 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 his function is
34870 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 used to write da
34880 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 ta into an open
34890 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 [BLOB handle] fr
348a0 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 om a.** caller-s
348b0 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 upplied buffer.
348c0 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 N bytes of data
348d0 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 are copied from
348e0 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 the buffer Z.**
348f0 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c into the open BL
34900 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 OB, starting at
34910 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a offset iOffset..
34920 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 42 4c **.** If the [BL
34930 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 OB handle] passe
34940 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 d as the first a
34950 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20 rgument was not
34960 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72 opened for.** wr
34970 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73 iting (the flags
34980 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
34990 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e qlite3_blob_open
349a0 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a ()] was zero),.*
349b0 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * this function
349c0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
349d0 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a READONLY]..**.**
349e0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d This function m
349f0 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 ay only modify t
34a00 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 he contents of t
34a10 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a he BLOB; it is.*
34a20 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 * not possible t
34a30 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73 o increase the s
34a40 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 73 ize of a BLOB us
34a50 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a ing this API..**
34a60 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 If offset iOffs
34a70 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 et is less than
34a80 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 N bytes from the
34a90 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 end of the BLOB
34aa0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 ,.** [SQLITE_ERR
34ab0 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 OR] is returned
34ac0 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 and no data is w
34ad0 72 69 74 74 65 6e 2e 20 20 49 66 20 4e 20 69 73 ritten. If N is
34ae0 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 .** less than ze
34af0 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ro [SQLITE_ERROR
34b00 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e ] is returned an
34b10 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 d no data is wri
34b20 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69 7a tten..** The siz
34b30 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 28 61 e of the BLOB (a
34b40 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78 nd hence the max
34b50 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b imum value of N+
34b60 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 iOffset).** can
34b70 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 be determined us
34b80 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ing the [sqlite3
34b90 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 _blob_bytes()] i
34ba0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
34bb0 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77 72 An attempt to wr
34bc0 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72 65 ite to an expire
34bd0 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 d [BLOB handle]
34be0 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a fails with an.**
34bf0 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b error code of [
34c00 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20 SQLITE_ABORT].
34c10 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 42 4c Writes to the BL
34c20 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72 65 64 OB that occurred
34c30 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b .** before the [
34c40 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 70 BLOB handle] exp
34c50 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c ired are not rol
34c60 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 0a led back by the.
34c70 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 ** expiration of
34c80 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f the handle, tho
34c90 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 ugh of course th
34ca0 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67 68 ose changes migh
34cb0 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 6f t.** have been o
34cc0 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 verwritten by th
34cd0 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 e statement that
34ce0 20 65 78 70 69 72 65 64 20 74 68 65 20 42 4c 4f expired the BLO
34cf0 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 B handle.** or b
34d00 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e 64 y other independ
34d10 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a ent statements..
34d20 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 **.** On success
34d30 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 , SQLITE_OK is r
34d40 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 eturned..** Othe
34d50 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f rwise, an [erro
34d60 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 r code] or an [e
34d70 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
34d80 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
34d90 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
34da0 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f ine only works o
34db0 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 n a [BLOB handle
34dc0 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e ] which has been
34dd0 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 created.** by a
34de0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 prior successfu
34df0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
34e00 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 e3_blob_open()]
34e10 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f and which has no
34e20 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 t.** been closed
34e30 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f by [sqlite3_blo
34e40 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 b_close()]. Pas
34e50 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 sing any other p
34e60 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 ointer in.** to
34e70 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 this routine res
34e80 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 ults in undefine
34e90 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 d and probably u
34ea0 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 ndesirable behav
34eb0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ior..**.** See a
34ec0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c lso: [sqlite3_bl
34ed0 6f 62 5f 72 65 61 64 28 29 5d 2e 0a 2a 2a 0a 2a ob_read()]..**.*
34ee0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
34ef0 2a 2a 20 5b 48 31 37 38 37 33 5d 20 5b 48 31 37 ** [H17873] [H17
34f00 38 37 34 5d 20 5b 48 31 37 38 37 35 5d 20 5b 48 874] [H17875] [H
34f10 31 37 38 37 36 5d 20 5b 48 31 37 38 37 37 5d 20 17876] [H17877]
34f20 5b 48 31 37 38 37 39 5d 20 5b 48 31 37 38 38 32 [H17879] [H17882
34f30 5d 20 5b 48 31 37 38 38 35 5d 0a 2a 2a 20 5b 48 ] [H17885].** [H
34f40 31 37 38 38 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 17888].*/.SQLITE
34f50 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
34f60 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
34f70 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
34f80 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c 3_blob_write(sql
34f90 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e ite3_blob *, con
34fa0 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 st void *z, int
34fb0 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b n, int iOffset);
34fc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
34fd0 3a 20 56 69 72 74 75 61 6c 20 46 69 6c 65 20 53 : Virtual File S
34fe0 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 20 7b 48 ystem Objects {H
34ff0 31 31 32 30 30 7d 20 3c 53 32 30 31 30 30 3e 0a 11200} <S20100>.
35000 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 **.** A virtual
35010 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29 filesystem (VFS)
35020 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f is an [sqlite3_
35030 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 vfs] object.** t
35040 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 73 20 hat SQLite uses
35050 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 to interact.** w
35060 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69 ith the underlyi
35070 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 ng operating sys
35080 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74 tem. Most SQLit
35090 65 20 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69 e builds come wi
350a0 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64 th a.** single d
350b0 65 66 61 75 6c 74 20 56 46 53 20 74 68 61 74 20 efault VFS that
350c0 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 is appropriate f
350d0 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 or the host comp
350e0 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53 uter..** New VFS
350f0 65 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 es can be regist
35100 65 72 65 64 20 61 6e 64 20 65 78 69 73 74 69 6e ered and existin
35110 67 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 75 g VFSes can be u
35120 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 nregistered..**
35130 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e The following in
35140 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f terfaces are pro
35150 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 vided..**.** The
35160 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e sqlite3_vfs_fin
35170 64 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 d() interface re
35180 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
35190 74 6f 20 61 20 56 46 53 20 67 69 76 65 6e 20 69 to a VFS given i
351a0 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 4e 61 6d 65 ts name..** Name
351b0 73 20 61 72 65 20 63 61 73 65 20 73 65 6e 73 69 s are case sensi
351c0 74 69 76 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 tive..** Names a
351d0 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 re zero-terminat
351e0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 ed UTF-8 strings
351f0 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 ..** If there is
35200 20 6e 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c no match, a NUL
35210 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 L pointer is ret
35220 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 7a 56 66 urned..** If zVf
35230 73 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 sName is NULL th
35240 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 en the default V
35250 46 53 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a FS is returned..
35260 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 **.** New VFSes
35270 61 72 65 20 72 65 67 69 73 74 65 72 65 64 20 77 are registered w
35280 69 74 68 20 73 71 6c 69 74 65 33 5f 76 66 73 5f ith sqlite3_vfs_
35290 72 65 67 69 73 74 65 72 28 29 2e 0a 2a 2a 20 45 register()..** E
352a0 61 63 68 20 6e 65 77 20 56 46 53 20 62 65 63 6f ach new VFS beco
352b0 6d 65 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 mes the default
352c0 56 46 53 20 69 66 20 74 68 65 20 6d 61 6b 65 44 VFS if the makeD
352d0 66 6c 74 20 66 6c 61 67 20 69 73 20 73 65 74 2e flt flag is set.
352e0 0a 2a 2a 20 54 68 65 20 73 61 6d 65 20 56 46 53 .** The same VFS
352f0 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 can be register
35300 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 ed multiple time
35310 73 20 77 69 74 68 6f 75 74 20 69 6e 6a 75 72 79 s without injury
35320 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65 20 61 6e 20 ..** To make an
35330 65 78 69 73 74 69 6e 67 20 56 46 53 20 69 6e 74 existing VFS int
35340 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 o the default VF
35350 53 2c 20 72 65 67 69 73 74 65 72 20 69 74 20 61 S, register it a
35360 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 gain.** with the
35370 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 makeDflt flag s
35380 65 74 2e 20 20 49 66 20 74 77 6f 20 64 69 66 66 et. If two diff
35390 65 72 65 6e 74 20 56 46 53 65 73 20 77 69 74 68 erent VFSes with
353a0 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d the.** same nam
353b0 65 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 e are registered
353c0 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 , the behavior i
353d0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 49 66 s undefined. If
353e0 20 61 0a 2a 2a 20 56 46 53 20 69 73 20 72 65 67 a.** VFS is reg
353f0 69 73 74 65 72 65 64 20 77 69 74 68 20 61 20 6e istered with a n
35400 61 6d 65 20 74 68 61 74 20 69 73 20 4e 55 4c 4c ame that is NULL
35410 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 or an empty str
35420 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ing,.** then the
35430 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
35440 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 55 6e efined..**.** Un
35450 72 65 67 69 73 74 65 72 20 61 20 56 46 53 20 77 register a VFS w
35460 69 74 68 20 74 68 65 20 73 71 6c 69 74 65 33 5f ith the sqlite3_
35470 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 vfs_unregister()
35480 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 interface..** I
35490 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 f the default VF
354a0 53 20 69 73 20 75 6e 72 65 67 69 73 74 65 72 65 S is unregistere
354b0 64 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69 d, another VFS i
354c0 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 s chosen as.** t
354d0 68 65 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65 he default. The
354e0 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20 choice for the
354f0 6e 65 77 20 56 46 53 20 69 73 20 61 72 62 69 74 new VFS is arbit
35500 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 rary..**.** Requ
35510 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
35520 31 32 30 33 5d 20 5b 48 31 31 32 30 36 5d 20 5b 1203] [H11206] [
35530 48 31 31 32 30 39 5d 20 5b 48 31 31 32 31 32 5d H11209] [H11212]
35540 20 5b 48 31 31 32 31 35 5d 20 5b 48 31 31 32 31 [H11215] [H1121
35550 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 8].*/.SQLITE_API
35560 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
35570 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
35580 49 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 I sqlite3_vfs *s
35590 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 qlite3_vfs_find(
355a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 const char *zVfs
355b0 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 Name);.SQLITE_AP
355c0 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c I SQLITE_API SQL
355d0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
355e0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 PI int sqlite3_v
355f0 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69 fs_register(sqli
35600 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 te3_vfs*, int ma
35610 6b 65 44 66 6c 74 29 3b 0a 53 51 4c 49 54 45 5f keDflt);.SQLITE_
35620 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
35630 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
35640 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
35650 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 _vfs_unregister(
35660 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a sqlite3_vfs*);..
35670 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
35680 4d 75 74 65 78 65 73 20 7b 48 31 37 30 30 30 7d Mutexes {H17000}
35690 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20000>.**.**
356a0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
356b0 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 uses these routi
356c0 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a nes for thread.*
356d0 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f * synchronizatio
356e0 6e 2e 20 54 68 6f 75 67 68 20 74 68 65 79 20 61 n. Though they a
356f0 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 re intended for
35700 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 internal.** use
35710 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 by SQLite, code
35720 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e that links again
35730 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 st SQLite is.**
35740 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65 permitted to use
35750 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f any of these ro
35760 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 utines..**.** Th
35770 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 e SQLite source
35780 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 code contains mu
35790 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 ltiple implement
357a0 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 ations.** of the
357b0 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 se mutex routine
357c0 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61 s. An appropria
357d0 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f te implementatio
357e0 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64 n.** is selected
357f0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 automatically a
35800 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 t compile-time.
35810 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a The following.*
35820 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
35830 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 s are available
35840 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f in the SQLite co
35850 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a re:.**.** <ul>.*
35860 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f * <li> SQLITE_
35870 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 MUTEX_OS2.** <li
35880 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 > SQLITE_MUTEX
35890 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e _PTHREAD.** <li>
358a0 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f SQLITE_MUTEX_
358b0 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 W32.** <li> SQ
358c0 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a LITE_MUTEX_NOOP.
358d0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 ** </ul>.**.** T
358e0 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f he SQLITE_MUTEX_
358f0 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 NOOP implementat
35900 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20 ion is a set of
35910 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74 routines.** that
35920 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f does no real lo
35930 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70 cking and is app
35940 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 ropriate for use
35950 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d in.** a single-
35960 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 threaded applica
35970 74 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49 54 tion. The SQLIT
35980 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 E_MUTEX_OS2,.**
35990 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 SQLITE_MUTEX_PTH
359a0 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45 READ, and SQLITE
359b0 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 _MUTEX_W32 imple
359c0 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 mentations.** ar
359d0 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f e appropriate fo
359e0 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55 r use on OS/2, U
359f0 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73 nix, and Windows
35a00 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c 69 74 ..**.** If SQLit
35a10 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
35a20 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55 th the SQLITE_MU
35a30 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 70 72 TEX_APPDEF prepr
35a40 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f ocessor.** macro
35a50 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 20 22 defined (with "
35a60 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 -DSQLITE_MUTEX_A
35a70 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e 20 PPDEF=1"), then
35a80 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c no mutex.** impl
35a90 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e ementation is in
35aa0 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65 20 cluded with the
35ab0 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68 69 73 library. In this
35ac0 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 70 70 case the.** app
35ad0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 lication must su
35ae0 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d 75 pply a custom mu
35af0 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 tex implementati
35b00 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 on using the.**
35b10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
35b20 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 20 UTEX] option of
35b30 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 the sqlite3_conf
35b40 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a ig() function.**
35b50 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20 before calling
35b60 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
35b70 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 68 65 ze() or any othe
35b80 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33 r public sqlite3
35b90 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 _.** function th
35ba0 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 at calls sqlite3
35bb0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a _initialize()..*
35bc0 2a 0a 2a 2a 20 7b 48 31 37 30 31 31 7d 20 54 68 *.** {H17011} Th
35bd0 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f e sqlite3_mutex_
35be0 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 alloc() routine
35bf0 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a allocates a new.
35c00 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74 ** mutex and ret
35c10 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
35c20 6f 20 69 74 2e 20 7b 48 31 37 30 31 32 7d 20 49 o it. {H17012} I
35c30 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c f it returns NUL
35c40 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73 20 L.** that means
35c50 74 68 61 74 20 61 20 6d 75 74 65 78 20 63 6f 75 that a mutex cou
35c60 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 ld not be alloca
35c70 74 65 64 2e 20 7b 48 31 37 30 31 33 7d 20 53 51 ted. {H17013} SQ
35c80 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 Lite.** will unw
35c90 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e ind its stack an
35ca0 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f d return an erro
35cb0 72 2e 20 7b 48 31 37 30 31 34 7d 20 54 68 65 20 r. {H17014} The
35cc0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 argument.** to s
35cd0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
35ce0 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 74 oc() is one of t
35cf0 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e hese integer con
35d00 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 stants:.**.** <u
35d10 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 l>.** <li> SQLI
35d20 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a TE_MUTEX_FAST.**
35d30 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
35d40 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a TEX_RECURSIVE.**
35d50 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
35d60 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 TEX_STATIC_MASTE
35d70 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 R.** <li> SQLIT
35d80 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d E_MUTEX_STATIC_M
35d90 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 EM.** <li> SQLI
35da0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
35db0 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 MEM2.** <li> SQ
35dc0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
35dd0 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20 C_PRNG.** <li>
35de0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
35df0 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20 TIC_LRU.** <li>
35e00 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
35e10 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75 ATIC_LRU2.** </u
35e20 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 35 l>.**.** {H17015
35e30 7d 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 } The first two
35e40 63 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20 constants cause
35e50 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
35e60 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a loc() to create.
35e70 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 ** a new mutex.
35e80 20 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 The new mutex i
35e90 73 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e s recursive when
35ea0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 SQLITE_MUTEX_RE
35eb0 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 CURSIVE.** is us
35ec0 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 ed but not neces
35ed0 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 sarily so when S
35ee0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 QLITE_MUTEX_FAST
35ef0 20 69 73 20 75 73 65 64 2e 20 7b 45 4e 44 7d 0a is used. {END}.
35f00 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70 ** The mutex imp
35f10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 lementation does
35f20 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b not need to mak
35f30 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a e a distinction.
35f40 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 ** between SQLIT
35f50 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 E_MUTEX_RECURSIV
35f60 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 E and SQLITE_MUT
35f70 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f EX_FAST if it do
35f80 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 es.** not want t
35f90 6f 2e 20 20 7b 48 31 37 30 31 36 7d 20 42 75 74 o. {H17016} But
35fa0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c SQLite will onl
35fb0 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75 y request a recu
35fc0 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a rsive mutex in.*
35fd0 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74 * cases where it
35fe0 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e really needs on
35ff0 65 2e 20 20 7b 45 4e 44 7d 20 49 66 20 61 20 66 e. {END} If a f
36000 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73 aster non-recurs
36010 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 ive mutex.** imp
36020 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 lementation is a
36030 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20 vailable on the
36040 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74 host platform, t
36050 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 74 he mutex subsyst
36060 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75 em.** might retu
36070 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 20 rn such a mutex
36080 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53 in response to S
36090 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 QLITE_MUTEX_FAST
360a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 37 7d ..**.** {H17017}
360b0 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77 The other allow
360c0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f ed parameters to
360d0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 sqlite3_mutex_a
360e0 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74 75 lloc() each retu
360f0 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 rn.** a pointer
36100 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65 to a static pree
36110 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 7b xisting mutex. {
36120 45 4e 44 7d 20 20 46 6f 75 72 20 73 74 61 74 69 END} Four stati
36130 63 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a c mutexes are.**
36140 20 75 73 65 64 20 62 79 20 74 68 65 20 63 75 72 used by the cur
36150 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 rent version of
36160 53 51 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20 SQLite. Future
36170 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
36180 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64 te.** may add ad
36190 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 ditional static
361a0 6d 75 74 65 78 65 73 2e 20 20 53 74 61 74 69 63 mutexes. Static
361b0 20 6d 75 74 65 78 65 73 20 61 72 65 20 66 6f 72 mutexes are for
361c0 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 internal.** use
361d0 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e by SQLite only.
361e0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 Applications t
361f0 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d hat use SQLite m
36200 75 74 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a utexes should.**
36210 20 75 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79 use only the dy
36220 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65 namic mutexes re
36230 74 75 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45 turned by SQLITE
36240 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a _MUTEX_FAST or.*
36250 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 * SQLITE_MUTEX_R
36260 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 ECURSIVE..**.**
36270 7b 48 31 37 30 31 38 7d 20 4e 6f 74 65 20 74 68 {H17018} Note th
36280 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65 at if one of the
36290 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70 dynamic mutex p
362a0 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54 arameters (SQLIT
362b0 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 E_MUTEX_FAST.**
362c0 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f or SQLITE_MUTEX_
362d0 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75 73 RECURSIVE) is us
362e0 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ed then sqlite3_
362f0 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a mutex_alloc().**
36300 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 65 returns a diffe
36310 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76 rent mutex on ev
36320 65 72 79 20 63 61 6c 6c 2e 20 20 7b 48 31 37 30 ery call. {H170
36330 33 34 7d 20 42 75 74 20 66 6f 72 20 74 68 65 20 34} But for the
36340 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 static.** mutex
36350 74 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20 types, the same
36360 6d 75 74 65 78 20 69 73 20 72 65 74 75 72 6e 65 mutex is returne
36370 64 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20 d on every call
36380 74 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20 that has.** the
36390 73 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72 same type number
363a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 39 7d ..**.** {H17019}
363b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 The sqlite3_mut
363c0 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e ex_free() routin
363d0 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20 e deallocates a
363e0 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c previously.** al
363f0 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20 located dynamic
36400 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 30 7d 20 mutex. {H17020}
36410 53 51 4c 69 74 65 20 69 73 20 63 61 72 65 66 75 SQLite is carefu
36420 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 l to deallocate
36430 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63 every.** dynamic
36440 20 6d 75 74 65 78 20 74 68 61 74 20 69 74 20 61 mutex that it a
36450 6c 6c 6f 63 61 74 65 73 2e 20 7b 41 31 37 30 32 llocates. {A1702
36460 31 7d 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d 1} The dynamic m
36470 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20 utexes must not
36480 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65 be in.** use whe
36490 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 6c 6c n they are deall
364a0 6f 63 61 74 65 64 2e 20 7b 41 31 37 30 32 32 7d ocated. {A17022}
364b0 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64 Attempting to d
364c0 65 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 74 eallocate a stat
364d0 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 75 ic.** mutex resu
364e0 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 lts in undefined
364f0 20 62 65 68 61 76 69 6f 72 2e 20 7b 48 31 37 30 behavior. {H170
36500 32 33 7d 20 53 51 4c 69 74 65 20 6e 65 76 65 72 23} SQLite never
36510 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 deallocates.**
36520 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 20 a static mutex.
36530 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 {END}.**.** The
36540 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e sqlite3_mutex_en
36550 74 65 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ter() and sqlite
36560 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f 3_mutex_try() ro
36570 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a utines attempt.*
36580 2a 20 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 * to enter a mut
36590 65 78 2e 20 7b 48 31 37 30 32 34 7d 20 49 66 20 ex. {H17024} If
365a0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 69 another thread i
365b0 73 20 61 6c 72 65 61 64 79 20 77 69 74 68 69 6e s already within
365c0 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 the mutex,.** s
365d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 qlite3_mutex_ent
365e0 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 er() will block
365f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 and sqlite3_mute
36600 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72 65 74 x_try() will ret
36610 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 urn.** SQLITE_BU
36620 53 59 2e 20 7b 48 31 37 30 32 35 7d 20 20 54 68 SY. {H17025} Th
36630 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f e sqlite3_mutex_
36640 74 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 try() interface
36650 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
36660 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 OK].** upon succ
36670 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 7b essful entry. {
36680 48 31 37 30 32 36 7d 20 4d 75 74 65 78 65 73 20 H17026} Mutexes
36690 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a created using.**
366a0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 SQLITE_MUTEX_RE
366b0 43 55 52 53 49 56 45 20 63 61 6e 20 62 65 20 65 CURSIVE can be e
366c0 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 ntered multiple
366d0 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d times by the sam
366e0 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20 7b 48 31 e thread..** {H1
366f0 37 30 32 37 7d 20 49 6e 20 73 75 63 68 20 63 61 7027} In such ca
36700 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 ses the,.** mute
36710 78 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 x must be exited
36720 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 an equal number
36730 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 of times before
36740 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a another thread.
36750 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 20 20 7b ** can enter. {
36760 41 31 37 30 32 38 7d 20 49 66 20 74 68 65 20 73 A17028} If the s
36770 61 6d 65 20 74 68 72 65 61 64 20 74 72 69 65 73 ame thread tries
36780 20 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 to enter any ot
36790 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d her.** kind of m
367a0 75 74 65 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f utex more than o
367b0 6e 63 65 2c 20 74 68 65 20 62 65 68 61 76 69 6f nce, the behavio
367c0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a r is undefined..
367d0 2a 2a 20 7b 48 31 37 30 32 39 7d 20 53 51 4c 69 ** {H17029} SQLi
367e0 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78 te will never ex
367f0 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65 hibit.** such be
36800 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77 havior in its ow
36810 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73 n use of mutexes
36820 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73 79 73 ..**.** Some sys
36830 74 65 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 6c tems (for exampl
36840 65 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 20 64 e, Windows 95) d
36850 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68 o not support th
36860 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 e operation.** i
36870 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 71 mplemented by sq
36880 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 lite3_mutex_try(
36890 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73 ). On those sys
368a0 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75 tems, sqlite3_mu
368b0 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 6c tex_try().** wil
368c0 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 l always return
368d0 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 7b 48 SQLITE_BUSY. {H
368e0 31 37 30 33 30 7d 20 54 68 65 20 53 51 4c 69 74 17030} The SQLit
368f0 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72 e core only ever
36900 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 uses.** sqlite3
36910 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 61 73 20 _mutex_try() as
36920 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 an optimization
36930 73 6f 20 74 68 69 73 20 69 73 20 61 63 63 65 70 so this is accep
36940 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a table behavior..
36950 2a 2a 0a 2a 2a 20 7b 48 31 37 30 33 31 7d 20 54 **.** {H17031} T
36960 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 he sqlite3_mutex
36970 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65 _leave() routine
36980 20 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 74 exits a mutex t
36990 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 hat was.** previ
369a0 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79 ously entered by
369b0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
369c0 2e 20 20 7b 41 31 37 30 33 32 7d 20 54 68 65 20 . {A17032} The
369d0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 behavior.** is u
369e0 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20 ndefined if the
369f0 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72 mutex is not cur
36a00 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62 rently entered b
36a10 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 y the.** calling
36a20 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f thread or is no
36a30 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f t currently allo
36a40 63 61 74 65 64 2e 20 20 7b 48 31 37 30 33 33 7d cated. {H17033}
36a50 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 SQLite will.**
36a60 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65 72 2e never do either.
36a70 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 {END}.**.** If
36a80 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 the argument to
36a90 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e sqlite3_mutex_en
36aa0 74 65 72 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d ter(), sqlite3_m
36ab0 75 74 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a utex_try(), or.*
36ac0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f * sqlite3_mutex_
36ad0 6c 65 61 76 65 28 29 20 69 73 20 61 20 4e 55 4c leave() is a NUL
36ae0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 L pointer, then
36af0 61 6c 6c 20 74 68 72 65 65 20 72 6f 75 74 69 6e all three routin
36b00 65 73 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 20 es.** behave as
36b10 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 no-ops..**.** Se
36b20 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
36b30 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 _mutex_held()] a
36b40 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 nd [sqlite3_mute
36b50 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f x_notheld()]..*/
36b60 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
36b70 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
36b80 49 20 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c I SQLITE_API sql
36b90 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 ite3_mutex *sqli
36ba0 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 te3_mutex_alloc(
36bb0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
36bc0 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
36bd0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
36be0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d I void sqlite3_m
36bf0 75 74 65 78 5f 66 72 65 65 28 73 71 6c 69 74 65 utex_free(sqlite
36c00 33 5f 6d 75 74 65 78 2a 29 3b 0a 53 51 4c 49 54 3_mutex*);.SQLIT
36c10 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
36c20 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
36c30 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
36c40 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 te3_mutex_enter(
36c50 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b sqlite3_mutex*);
36c60 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
36c70 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 TE_API SQLITE_AP
36c80 49 20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 I SQLITE_API int
36c90 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 sqlite3_mutex_t
36ca0 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ry(sqlite3_mutex
36cb0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 *);.SQLITE_API S
36cc0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
36cd0 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
36ce0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 void sqlite3_mut
36cf0 65 78 5f 6c 65 61 76 65 28 73 71 6c 69 74 65 33 ex_leave(sqlite3
36d00 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a _mutex*);../*.**
36d10 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 CAPI3REF: Mutex
36d20 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 Methods Object
36d30 7b 48 31 37 31 32 30 7d 20 3c 53 32 30 31 33 30 {H17120} <S20130
36d40 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
36d50 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 L.**.** An insta
36d60 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 nce of this stru
36d70 63 74 75 72 65 20 64 65 66 69 6e 65 73 20 74 68 cture defines th
36d80 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72 6f 75 74 e low-level rout
36d90 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 ines.** used to
36da0 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20 75 73 65 allocate and use
36db0 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 mutexes..**.**
36dc0 55 73 75 61 6c 6c 79 2c 20 74 68 65 20 64 65 66 Usually, the def
36dd0 61 75 6c 74 20 6d 75 74 65 78 20 69 6d 70 6c 65 ault mutex imple
36de0 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72 6f 76 69 mentations provi
36df0 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 72 ded by SQLite ar
36e00 65 0a 2a 2a 20 73 75 66 66 69 63 69 65 6e 74 2c e.** sufficient,
36e10 20 68 6f 77 65 76 65 72 20 74 68 65 20 75 73 65 however the use
36e20 72 20 68 61 73 20 74 68 65 20 6f 70 74 69 6f 6e r has the option
36e30 20 6f 66 20 73 75 62 73 74 69 74 75 74 69 6e 67 of substituting
36e40 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20 69 6d 70 a custom.** imp
36e50 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 lementation for
36e60 73 70 65 63 69 61 6c 69 7a 65 64 20 64 65 70 6c specialized depl
36e70 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79 73 74 65 oyments or syste
36e80 6d 73 20 66 6f 72 20 77 68 69 63 68 20 53 51 4c ms for which SQL
36e90 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 ite.** does not
36ea0 70 72 6f 76 69 64 65 20 61 20 73 75 69 74 61 62 provide a suitab
36eb0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
36ec0 6e 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 2c n. In this case,
36ed0 20 74 68 65 20 75 73 65 72 0a 2a 2a 20 63 72 65 the user.** cre
36ee0 61 74 65 73 20 61 6e 64 20 70 6f 70 75 6c 61 74 ates and populat
36ef0 65 73 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f es an instance o
36f00 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 f this structure
36f10 20 74 6f 20 70 61 73 73 0a 2a 2a 20 74 6f 20 73 to pass.** to s
36f20 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
36f30 61 6c 6f 6e 67 20 77 69 74 68 20 74 68 65 20 5b along with the [
36f40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
36f50 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 TEX] option..**
36f60 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 61 6e Additionally, an
36f70 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
36f80 73 20 73 74 72 75 63 74 75 72 65 20 63 61 6e 20 s structure can
36f90 62 65 20 75 73 65 64 20 61 73 20 61 6e 0a 2a 2a be used as an.**
36fa0 20 6f 75 74 70 75 74 20 76 61 72 69 61 62 6c 65 output variable
36fb0 20 77 68 65 6e 20 71 75 65 72 79 69 6e 67 20 74 when querying t
36fc0 68 65 20 73 79 73 74 65 6d 20 66 6f 72 20 74 68 he system for th
36fd0 65 20 63 75 72 72 65 6e 74 20 6d 75 74 65 78 0a e current mutex.
36fe0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
36ff0 6e 2c 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 n, using the [SQ
37000 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
37010 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a UTEX] option..**
37020 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 49 6e .** The xMutexIn
37030 69 74 20 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 it method define
37040 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74 d by this struct
37050 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 ure is invoked a
37060 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 73 s.** part of sys
37070 74 65 6d 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 tem initializati
37080 6f 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 on by the sqlite
37090 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 66 3_initialize() f
370a0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 7b 48 31 37 unction..** {H17
370b0 30 30 31 7d 20 54 68 65 20 78 4d 75 74 65 78 49 001} The xMutexI
370c0 6e 69 74 20 72 6f 75 74 69 6e 65 20 73 68 61 6c nit routine shal
370d0 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 79 20 53 l be called by S
370e0 51 4c 69 74 65 20 6f 6e 63 65 20 66 6f 72 20 65 QLite once for e
370f0 61 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 65 ach.** effective
37100 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
37110 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e 3_initialize()].
37120 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 .**.** The xMute
37130 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 69 xEnd method defi
37140 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75 ned by this stru
37150 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 cture is invoked
37160 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 as.** part of s
37170 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 62 ystem shutdown b
37180 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 68 y the sqlite3_sh
37190 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 6f utdown() functio
371a0 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d n. The.** implem
371b0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 73 entation of this
371c0 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70 65 63 method is expec
371d0 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 61 ted to release a
371e0 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a ll outstanding.*
371f0 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62 74 61 * resources obta
37200 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75 74 65 ined by the mute
37210 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 6d x methods implem
37220 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 69 entation, especi
37230 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f 62 ally.** those ob
37240 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 78 4d tained by the xM
37250 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 2e utexInit method.
37260 20 7b 48 31 37 30 30 33 7d 20 54 68 65 20 78 4d {H17003} The xM
37270 75 74 65 78 45 6e 64 28 29 0a 2a 2a 20 69 6e 74 utexEnd().** int
37280 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62 65 20 erface shall be
37290 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 invoked once for
372a0 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 each call to [s
372b0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
372c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 )]..**.** The re
372d0 6d 61 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 maining seven me
372e0 74 68 6f 64 73 20 64 65 66 69 6e 65 64 20 62 79 thods defined by
372f0 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 this structure
37300 28 78 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a (xMutexAlloc,.**
37310 20 78 4d 75 74 65 78 46 72 65 65 2c 20 78 4d 75 xMutexFree, xMu
37320 74 65 78 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 texEnter, xMutex
37330 54 72 79 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 Try, xMutexLeave
37340 2c 20 78 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 , xMutexHeld and
37350 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c .** xMutexNothel
37360 64 29 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 d) implement the
37370 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 following inter
37380 66 61 63 65 73 20 28 72 65 73 70 65 63 74 69 76 faces (respectiv
37390 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ely):.**.** <ul>
373a0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c .** <li> [sql
373b0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 ite3_mutex_alloc
373c0 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c ()] </li>.** <
373d0 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 li> [sqlite3_mu
373e0 74 65 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 tex_free()] </li
373f0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 >.** <li> [sq
37400 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 lite3_mutex_ente
37410 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 r()] </li>.**
37420 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
37430 75 74 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 utex_try()] </li
37440 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 >.** <li> [sq
37450 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 lite3_mutex_leav
37460 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 e()] </li>.**
37470 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
37480 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c utex_held()] </l
37490 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 i>.** <li> [s
374a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 qlite3_mutex_not
374b0 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a held()] </li>.**
374c0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 </ul>.**.** The
374d0 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 only difference
374e0 20 69 73 20 74 68 61 74 20 74 68 65 20 70 75 62 is that the pub
374f0 6c 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58 20 lic sqlite3_XXX
37500 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72 functions enumer
37510 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69 ated.** above si
37520 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e lently ignore an
37530 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68 y invocations th
37540 61 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 70 at pass a NULL p
37550 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a ointer instead.*
37560 2a 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 * of a valid mut
37570 65 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 69 ex handle. The i
37580 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f mplementations o
37590 66 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64 65 f the methods de
375a0 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 fined.** by this
375b0 20 73 74 72 75 63 74 75 72 65 20 61 72 65 20 6e structure are n
375c0 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 68 ot required to h
375d0 61 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65 2c andle this case,
375e0 20 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20 the results.**
375f0 6f 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55 4c of passing a NUL
37600 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 L pointer instea
37610 64 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 d of a valid mut
37620 65 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75 6e ex handle are un
37630 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e defined.** (i.e.
37640 20 69 74 20 69 73 20 61 63 63 65 70 74 61 62 6c it is acceptabl
37650 65 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 e to provide an
37660 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 implementation t
37670 68 61 74 20 73 65 67 66 61 75 6c 74 73 20 69 66 hat segfaults if
37680 0a 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65 64 .** it is passed
37690 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29 a NULL pointer)
376a0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
376b0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 uct sqlite3_mute
376c0 78 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 x_methods sqlite
376d0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 3b 3_mutex_methods;
376e0 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
376f0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 7b 0a mutex_methods {.
37700 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 49 6e int (*xMutexIn
37710 69 74 29 28 76 6f 69 64 29 3b 0a 20 20 69 6e 74 it)(void);. int
37720 20 28 2a 78 4d 75 74 65 78 45 6e 64 29 28 76 6f (*xMutexEnd)(vo
37730 69 64 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 6d id);. sqlite3_m
37740 75 74 65 78 20 2a 28 2a 78 4d 75 74 65 78 41 6c utex *(*xMutexAl
37750 6c 6f 63 29 28 69 6e 74 29 3b 0a 20 20 76 6f 69 loc)(int);. voi
37760 64 20 28 2a 78 4d 75 74 65 78 46 72 65 65 29 28 d (*xMutexFree)(
37770 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 sqlite3_mutex *)
37780 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 ;. void (*xMute
37790 78 45 6e 74 65 72 29 28 73 71 6c 69 74 65 33 5f xEnter)(sqlite3_
377a0 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 mutex *);. int
377b0 28 2a 78 4d 75 74 65 78 54 72 79 29 28 73 71 6c (*xMutexTry)(sql
377c0 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 ite3_mutex *);.
377d0 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 4c 65 void (*xMutexLe
377e0 61 76 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 ave)(sqlite3_mut
377f0 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 ex *);. int (*x
37800 4d 75 74 65 78 48 65 6c 64 29 28 73 71 6c 69 74 MutexHeld)(sqlit
37810 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 e3_mutex *);. i
37820 6e 74 20 28 2a 78 4d 75 74 65 78 4e 6f 74 68 65 nt (*xMutexNothe
37830 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 ld)(sqlite3_mute
37840 78 20 2a 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 x *);.};../*.**
37850 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 CAPI3REF: Mutex
37860 56 65 72 69 66 69 63 61 74 69 6f 6e 20 52 6f 75 Verification Rou
37870 74 69 6e 65 73 20 7b 48 31 37 30 38 30 7d 20 3c tines {H17080} <
37880 53 32 30 31 33 30 3e 20 3c 53 33 30 38 30 30 3e S20130> <S30800>
37890 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
378a0 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 e3_mutex_held()
378b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 and sqlite3_mute
378c0 78 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 x_notheld() rout
378d0 69 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 ines.** are inte
378e0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 nded for use ins
378f0 69 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 ide assert() sta
37900 74 65 6d 65 6e 74 73 2e 20 7b 48 31 37 30 38 31 tements. {H17081
37910 7d 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 } The SQLite cor
37920 65 0a 2a 2a 20 6e 65 76 65 72 20 75 73 65 73 20 e.** never uses
37930 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 65 these routines e
37940 78 63 65 70 74 20 69 6e 73 69 64 65 20 61 6e 20 xcept inside an
37950 61 73 73 65 72 74 28 29 20 61 6e 64 20 61 70 70 assert() and app
37960 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 lications.** are
37970 20 61 64 76 69 73 65 64 20 74 6f 20 66 6f 6c 6c advised to foll
37980 6f 77 20 74 68 65 20 6c 65 61 64 20 6f 66 20 74 ow the lead of t
37990 68 65 20 63 6f 72 65 2e 20 20 7b 48 31 37 30 38 he core. {H1708
379a0 32 7d 20 54 68 65 20 63 6f 72 65 20 6f 6e 6c 79 2} The core only
379b0 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20 69 6d 70 .** provides imp
379c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 lementations for
379d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
379e0 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 when it is compi
379f0 6c 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 led.** with the
37a00 53 51 4c 49 54 45 5f 44 45 42 55 47 20 66 6c 61 SQLITE_DEBUG fla
37a10 67 2e 20 20 7b 41 31 37 30 38 37 7d 20 45 78 74 g. {A17087} Ext
37a20 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c ernal mutex impl
37a30 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 ementations.** a
37a40 72 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 re only required
37a50 20 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 to provide thes
37a60 65 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 e routines if SQ
37a70 4c 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a LITE_DEBUG is.**
37a80 20 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 defined and if
37a90 4e 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 NDEBUG is not de
37aa0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 fined..**.** {H1
37ab0 37 30 38 33 7d 20 54 68 65 73 65 20 72 6f 75 74 7083} These rout
37ac0 69 6e 65 73 20 73 68 6f 75 6c 64 20 72 65 74 75 ines should retu
37ad0 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 6d rn true if the m
37ae0 75 74 65 78 20 69 6e 20 74 68 65 69 72 20 61 72 utex in their ar
37af0 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 68 65 6c gument.** is hel
37b00 64 20 6f 72 20 6e 6f 74 20 68 65 6c 64 2c 20 72 d or not held, r
37b10 65 73 70 65 63 74 69 76 65 6c 79 2c 20 62 79 20 espectively, by
37b20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 the calling thre
37b30 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 58 31 37 30 38 ad..**.** {X1708
37b40 34 7d 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 4} The implement
37b50 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 ation is not req
37b60 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 uired to provide
37b70 64 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 d versions of th
37b80 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ese.** routines
37b90 74 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f that actually wo
37ba0 72 6b 2e 20 49 66 20 74 68 65 20 69 6d 70 6c 65 rk. If the imple
37bb0 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e mentation does n
37bc0 6f 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 ot provide worki
37bd0 6e 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f ng.** versions o
37be0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
37bf0 2c 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c , it should at l
37c00 65 61 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 east provide stu
37c10 62 73 20 74 68 61 74 20 61 6c 77 61 79 73 0a 2a bs that always.*
37c20 2a 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f * return true so
37c30 20 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e that one does n
37c40 6f 74 20 67 65 74 20 73 70 75 72 69 6f 75 73 20 ot get spurious
37c50 61 73 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 assertion failur
37c60 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 es..**.** {H1708
37c70 35 7d 20 49 66 20 74 68 65 20 61 72 67 75 6d 65 5} If the argume
37c80 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 nt to sqlite3_mu
37c90 74 65 78 5f 68 65 6c 64 28 29 20 69 73 20 61 20 tex_held() is a
37ca0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
37cb0 6e 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 n.** the routine
37cc0 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 31 should return 1
37cd0 2e 20 20 7b 45 4e 44 7d 20 54 68 69 73 20 73 65 . {END} This se
37ce0 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75 ems counter-intu
37cf0 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63 itive since.** c
37d00 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65 78 learly the mutex
37d10 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20 cannot be held
37d20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 if it does not e
37d30 78 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a 2a xist. But the.*
37d40 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68 65 * the reason the
37d50 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74 20 mutex does not
37d60 65 78 69 73 74 20 69 73 20 62 65 63 61 75 73 65 exist is because
37d70 20 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e 6f the build is no
37d80 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65 78 t.** using mutex
37d90 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20 6e es. And we do n
37da0 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73 73 65 ot want the asse
37db0 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 rt() containing
37dc0 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 the.** call to s
37dd0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c qlite3_mutex_hel
37de0 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20 d() to fail, so
37df0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 a non-zero retur
37e00 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70 72 n is.** the appr
37e10 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20 74 6f opriate thing to
37e20 20 64 6f 2e 20 20 7b 48 31 37 30 38 36 7d 20 54 do. {H17086} T
37e30 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 he sqlite3_mutex
37e40 5f 6e 6f 74 68 65 6c 64 28 29 0a 2a 2a 20 69 6e _notheld().** in
37e50 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 61 terface should a
37e60 6c 73 6f 20 72 65 74 75 72 6e 20 31 20 77 68 65 lso return 1 whe
37e70 6e 20 67 69 76 65 6e 20 61 20 4e 55 4c 4c 20 70 n given a NULL p
37e80 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 ointer..*/.SQLIT
37e90 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
37ea0 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
37eb0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
37ec0 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 e3_mutex_held(sq
37ed0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 53 lite3_mutex*);.S
37ee0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
37ef0 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
37f00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
37f10 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 qlite3_mutex_not
37f20 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 held(sqlite3_mut
37f30 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ex*);../*.** CAP
37f40 49 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70 I3REF: Mutex Typ
37f50 65 73 20 7b 48 31 37 30 30 31 7d 20 3c 48 31 37 es {H17001} <H17
37f60 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 000>.**.** The [
37f70 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
37f80 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65 loc()] interface
37f90 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
37fa0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 argument.** whic
37fb0 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 h is one of thes
37fc0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
37fd0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 nts..**.** The s
37fe0 65 74 20 6f 66 20 73 74 61 74 69 63 20 6d 75 74 et of static mut
37ff0 65 78 65 73 20 6d 61 79 20 63 68 61 6e 67 65 20 exes may change
38000 66 72 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65 20 from one SQLite
38010 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 0a 2a release to the.*
38020 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 * next. Applica
38030 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 72 tions that overr
38040 69 64 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e ide the built-in
38050 20 6d 75 74 65 78 20 6c 6f 67 69 63 20 6d 75 73 mutex logic mus
38060 74 20 62 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 t be.** prepared
38070 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65 20 to accommodate
38080 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 additional stati
38090 63 20 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23 64 c mutexes..*/.#d
380a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 efine SQLITE_MUT
380b0 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 20 20 EX_FAST
380c0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
380d0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 LITE_MUTEX_RECUR
380e0 53 49 56 45 20 20 20 20 20 20 20 20 31 0a 23 64 SIVE 1.#d
380f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 efine SQLITE_MUT
38100 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 EX_STATIC_MASTER
38110 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
38120 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
38130 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20 2f C_MEM 3 /
38140 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
38150 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
38160 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
38170 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20 2f C_MEM2 4 /
38180 2a 20 4e 4f 54 20 55 53 45 44 20 2a 2f 0a 23 64 * NOT USED */.#d
38190 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 efine SQLITE_MUT
381a0 45 58 5f 53 54 41 54 49 43 5f 4f 50 45 4e 20 20 EX_STATIC_OPEN
381b0 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 4 /* sqlite
381c0 33 42 74 72 65 65 4f 70 65 6e 28 29 20 2a 2f 0a 3BtreeOpen() */.
381d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
381e0 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 UTEX_STATIC_PRNG
381f0 20 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 5 /* sqli
38200 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a te3_random() */.
38210 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
38220 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20 UTEX_STATIC_LRU
38230 20 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20 6 /* lru
38240 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64 65 page list */.#de
38250 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 fine SQLITE_MUTE
38260 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 20 20 20 X_STATIC_LRU2
38270 20 20 20 37 20 20 2f 2a 20 6c 72 75 20 70 61 67 7 /* lru pag
38280 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a e list */../*.**
38290 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 CAPI3REF: Retri
382a0 65 76 65 20 74 68 65 20 6d 75 74 65 78 20 66 6f eve the mutex fo
382b0 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e r a database con
382c0 6e 65 63 74 69 6f 6e 20 7b 48 31 37 30 30 32 7d nection {H17002}
382d0 20 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 <H17000>.**.**
382e0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 This interface r
382f0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
38300 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
38310 74 65 78 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 tex] object that
38320 20 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73 20 .** serializes
38330 61 63 63 65 73 73 20 74 6f 20 74 68 65 20 5b 64 access to the [d
38340 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
38350 6f 6e 5d 20 67 69 76 65 6e 20 69 6e 20 74 68 65 on] given in the
38360 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 65 argument.** whe
38370 6e 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 n the [threading
38380 20 6d 6f 64 65 5d 20 69 73 20 53 65 72 69 61 6c mode] is Serial
38390 69 7a 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 ized..** If the
383a0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
383b0 20 69 73 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 is Single-threa
383c0 64 20 6f 72 20 4d 75 6c 74 69 2d 74 68 72 65 61 d or Multi-threa
383d0 64 20 74 68 65 6e 20 74 68 69 73 0a 2a 2a 20 72 d then this.** r
383e0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 outine returns a
383f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
38400 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c /.SQLITE_API SQL
38410 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
38420 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 73 71 PI SQLITE_API sq
38430 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c lite3_mutex *sql
38440 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 28 73 71 ite3_db_mutex(sq
38450 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
38460 43 41 50 49 33 52 45 46 3a 20 4c 6f 77 2d 4c 65 CAPI3REF: Low-Le
38470 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f 66 20 44 vel Control Of D
38480 61 74 61 62 61 73 65 20 46 69 6c 65 73 20 7b 48 atabase Files {H
38490 31 31 33 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a 11300} <S30800>.
384a0 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 31 7d 20 54 **.** {H11301} T
384b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 he [sqlite3_file
384c0 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 _control()] inte
384d0 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64 69 rface makes a di
384e0 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 65 rect call to the
384f0 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c .** xFileControl
38500 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65 20 method for the
38510 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
38520 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f ods] object asso
38530 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 61 ciated.** with a
38540 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 particular data
38550 62 61 73 65 20 69 64 65 6e 74 69 66 69 65 64 20 base identified
38560 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 by the second ar
38570 67 75 6d 65 6e 74 2e 20 7b 48 31 31 33 30 32 7d gument. {H11302}
38580 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 The.** name of
38590 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
385a0 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 the name assigne
385b0 64 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 d to the databas
385c0 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61 20 68 e by the.** <a h
385d0 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61 63 68 ref="lang_attach
385e0 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c 2f 61 .html">ATTACH</a
385f0 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 68 > SQL command th
38600 61 74 20 6f 70 65 6e 65 64 20 74 68 65 0a 2a 2a at opened the.**
38610 20 64 61 74 61 62 61 73 65 2e 20 7b 48 31 31 33 database. {H113
38620 30 33 7d 20 54 6f 20 63 6f 6e 74 72 6f 6c 20 74 03} To control t
38630 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 he main database
38640 20 66 69 6c 65 2c 20 75 73 65 20 74 68 65 20 6e file, use the n
38650 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a 20 6f 72 ame "main".** or
38660 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
38670 20 7b 48 31 31 33 30 34 7d 20 54 68 65 20 74 68 {H11304} The th
38680 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 ird and fourth p
38690 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 arameters to thi
386a0 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 72 65 s routine.** are
386b0 20 70 61 73 73 65 64 20 64 69 72 65 63 74 6c 79 passed directly
386c0 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 through to the
386d0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 second and third
386e0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 0a 2a parameters of.*
386f0 2a 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 * the xFileContr
38700 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 7b 48 31 31 ol method. {H11
38710 33 30 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20 305} The return
38720 76 61 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69 value of the xFi
38730 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 leControl.** met
38740 68 6f 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 hod becomes the
38750 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
38760 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a this routine..**
38770 0a 2a 2a 20 7b 48 31 31 33 30 36 7d 20 49 66 20 .** {H11306} If
38780 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
38790 65 74 65 72 20 28 7a 44 62 4e 61 6d 65 29 20 64 eter (zDbName) d
387a0 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 74 68 oes not match th
387b0 65 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a e name of any.**
387c0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 66 open database f
387d0 69 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 ile, then SQLITE
387e0 5f 45 52 52 4f 52 20 69 73 20 72 65 74 75 72 6e _ERROR is return
387f0 65 64 2e 20 7b 48 31 31 33 30 37 7d 20 54 68 69 ed. {H11307} Thi
38800 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 s error.** code
38810 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72 65 is not remembere
38820 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62 d and will not b
38830 65 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b 73 e recalled by [s
38840 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
38850 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 ].** or [sqlite3
38860 5f 65 72 72 6d 73 67 28 29 5d 2e 20 7b 41 31 31 _errmsg()]. {A11
38870 33 30 38 7d 20 54 68 65 20 75 6e 64 65 72 6c 79 308} The underly
38880 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c ing xFileControl
38890 20 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a 2a 2a method might.**
388a0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 53 51 4c also return SQL
388b0 49 54 45 5f 45 52 52 4f 52 2e 20 20 7b 41 31 31 ITE_ERROR. {A11
388c0 33 30 39 7d 20 54 68 65 72 65 20 69 73 20 6e 6f 309} There is no
388d0 20 77 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75 way to distingu
388e0 69 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61 ish between.** a
388f0 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e n incorrect zDbN
38900 61 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54 ame and an SQLIT
38910 45 5f 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66 E_ERROR return f
38920 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69 rom the underlyi
38930 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 ng.** xFileContr
38940 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b 45 4e 44 7d ol method. {END}
38950 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
38960 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c [SQLITE_FCNTL_L
38970 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 53 51 4c OCKSTATE].*/.SQL
38980 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 ITE_API SQLITE_A
38990 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
389a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
389b0 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
389c0 6c 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 l(sqlite3*, cons
389d0 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c t char *zDbName,
389e0 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b int op, void*);
389f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
38a00 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66 : Testing Interf
38a10 61 63 65 20 7b 48 31 31 34 30 30 7d 20 3c 53 33 ace {H11400} <S3
38a20 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0800>.**.** The
38a30 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e sqlite3_test_con
38a40 74 72 6f 6c 28 29 20 69 6e 74 65 72 66 61 63 65 trol() interface
38a50 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 is used to read
38a60 20 6f 75 74 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a out internal.**
38a70 20 73 74 61 74 65 20 6f 66 20 53 51 4c 69 74 65 state of SQLite
38a80 20 61 6e 64 20 74 6f 20 69 6e 6a 65 63 74 20 66 and to inject f
38a90 61 75 6c 74 73 20 69 6e 74 6f 20 53 51 4c 69 74 aults into SQLit
38aa0 65 20 66 6f 72 20 74 65 73 74 69 6e 67 0a 2a 2a e for testing.**
38ab0 20 70 75 72 70 6f 73 65 73 2e 20 20 54 68 65 20 purposes. The
38ac0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
38ad0 69 73 20 61 6e 20 6f 70 65 72 61 74 69 6f 6e 20 is an operation
38ae0 63 6f 64 65 20 74 68 61 74 20 64 65 74 65 72 6d code that determ
38af0 69 6e 65 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 ines.** the numb
38b00 65 72 2c 20 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 er, meaning, and
38b10 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 61 6c operation of al
38b20 6c 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 l subsequent par
38b30 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 ameters..**.** T
38b40 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
38b50 20 6e 6f 74 20 66 6f 72 20 75 73 65 20 62 79 20 not for use by
38b60 61 70 70 6c 69 63 61 74 69 6f 6e 73 2e 20 20 49 applications. I
38b70 74 20 65 78 69 73 74 73 20 73 6f 6c 65 6c 79 0a t exists solely.
38b80 2a 2a 20 66 6f 72 20 76 65 72 69 66 79 69 6e 67 ** for verifying
38b90 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 70 65 the correct ope
38ba0 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 ration of the SQ
38bb0 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 44 Lite library. D
38bc0 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 epending.** on h
38bd0 6f 77 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 ow the SQLite li
38be0 62 72 61 72 79 20 69 73 20 63 6f 6d 70 69 6c 65 brary is compile
38bf0 64 2c 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 d, this interfac
38c00 65 20 6d 69 67 68 74 20 6e 6f 74 20 65 78 69 73 e might not exis
38c10 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 t..**.** The det
38c20 61 69 6c 73 20 6f 66 20 74 68 65 20 6f 70 65 72 ails of the oper
38c30 61 74 69 6f 6e 20 63 6f 64 65 73 2c 20 74 68 65 ation codes, the
38c40 69 72 20 6d 65 61 6e 69 6e 67 73 2c 20 74 68 65 ir meanings, the
38c50 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 parameters.** t
38c60 68 65 79 20 74 61 6b 65 2c 20 61 6e 64 20 77 68 hey take, and wh
38c70 61 74 20 74 68 65 79 20 64 6f 20 61 72 65 20 61 at they do are a
38c80 6c 6c 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 ll subject to ch
38c90 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 ange without not
38ca0 69 63 65 2e 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d ice..** Unlike m
38cb0 6f 73 74 20 6f 66 20 74 68 65 20 53 51 4c 69 74 ost of the SQLit
38cc0 65 20 41 50 49 2c 20 74 68 69 73 20 66 75 6e 63 e API, this func
38cd0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 75 61 72 tion is not guar
38ce0 61 6e 74 65 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 anteed to.** ope
38cf0 72 61 74 65 20 63 6f 6e 73 69 73 74 65 6e 74 6c rate consistentl
38d00 79 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 y from one relea
38d10 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a se to the next..
38d20 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 */.SQLITE_API SQ
38d30 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
38d40 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 69 API SQLITE_API i
38d50 6e 74 20 73 71 6c 69 74 65 33 5f 74 65 73 74 5f nt sqlite3_test_
38d60 63 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f 70 2c 20 control(int op,
38d70 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ...);../*.** CAP
38d80 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 49 I3REF: Testing I
38d90 6e 74 65 72 66 61 63 65 20 4f 70 65 72 61 74 69 nterface Operati
38da0 6f 6e 20 43 6f 64 65 73 20 7b 48 31 31 34 31 30 on Codes {H11410
38db0 7d 20 3c 48 31 31 34 30 30 3e 0a 2a 2a 0a 2a 2a } <H11400>.**.**
38dc0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
38dd0 20 61 72 65 20 74 68 65 20 76 61 6c 69 64 20 6f are the valid o
38de0 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 70 61 peration code pa
38df0 72 61 6d 65 74 65 72 73 20 75 73 65 64 0a 2a 2a rameters used.**
38e00 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 as the first ar
38e10 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 gument to [sqlit
38e20 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 e3_test_control(
38e30 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 )]..**.** These
38e40 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 74 parameters and t
38e50 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 20 61 72 heir meanings ar
38e60 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 e subject to cha
38e70 6e 67 65 0a 2a 2a 20 77 69 74 68 6f 75 74 20 6e nge.** without n
38e80 6f 74 69 63 65 2e 20 20 54 68 65 73 65 20 76 61 otice. These va
38e90 6c 75 65 73 20 61 72 65 20 66 6f 72 20 74 65 73 lues are for tes
38ea0 74 69 6e 67 20 70 75 72 70 6f 73 65 73 20 6f 6e ting purposes on
38eb0 6c 79 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 ly..** Applicati
38ec0 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 ons should not u
38ed0 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 se any of these
38ee0 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 74 68 parameters or th
38ef0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 65 e.** [sqlite3_te
38f00 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e st_control()] in
38f10 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 terface..*/.#def
38f20 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 ine SQLITE_TESTC
38f30 54 52 4c 5f 50 52 4e 47 5f 53 41 56 45 20 20 20 TRL_PRNG_SAVE
38f40 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 5.#
38f50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 define SQLITE_TE
38f60 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 54 STCTRL_PRNG_REST
38f70 4f 52 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ORE
38f80 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 6.#define SQLITE
38f90 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 _TESTCTRL_PRNG_R
38fa0 45 53 45 54 20 20 20 20 20 20 20 20 20 20 20 20 ESET
38fb0 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 7.#define SQL
38fc0 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 49 54 ITE_TESTCTRL_BIT
38fd0 56 45 43 5f 54 45 53 54 20 20 20 20 20 20 20 20 VEC_TEST
38fe0 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 8.#define
38ff0 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f SQLITE_TESTCTRL_
39000 46 41 55 4c 54 5f 49 4e 53 54 41 4c 4c 20 20 20 FAULT_INSTALL
39010 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 9.#defi
39020 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 ne SQLITE_TESTCT
39030 52 4c 5f 42 45 4e 49 47 4e 5f 4d 41 4c 4c 4f 43 RL_BENIGN_MALLOC
39040 5f 48 4f 4f 4b 53 20 20 20 20 20 31 30 0a 23 64 _HOOKS 10.#d
39050 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 efine SQLITE_TES
39060 54 43 54 52 4c 5f 50 45 4e 44 49 4e 47 5f 42 59 TCTRL_PENDING_BY
39070 54 45 20 20 20 20 20 20 20 20 20 20 20 20 31 31 TE 11
39080 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
39090 54 45 53 54 43 54 52 4c 5f 41 53 53 45 52 54 20 TESTCTRL_ASSERT
390a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
390b0 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 12.#define SQLI
390c0 54 45 5f 54 45 53 54 43 54 52 4c 5f 41 4c 57 41 TE_TESTCTRL_ALWA
390d0 59 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20 YS
390e0 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 13.#define S
390f0 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 52 QLITE_TESTCTRL_R
39100 45 53 45 52 56 45 20 20 20 20 20 20 20 20 20 20 ESERVE
39110 20 20 20 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a 14../*.**
39120 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 69 74 CAPI3REF: SQLit
39130 65 20 52 75 6e 74 69 6d 65 20 53 74 61 74 75 73 e Runtime Status
39140 20 7b 48 31 37 32 30 30 7d 20 3c 53 36 30 32 30 {H17200} <S6020
39150 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
39160 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e AL.**.** This in
39170 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
39180 74 6f 20 72 65 74 72 69 65 76 65 20 72 75 6e 74 to retrieve runt
39190 69 6d 65 20 73 74 61 74 75 73 20 69 6e 66 6f 72 ime status infor
391a0 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 mation.** about
391b0 74 68 65 20 70 72 65 66 6f 72 6d 61 6e 63 65 20 the preformance
391c0 6f 66 20 53 51 4c 69 74 65 2c 20 61 6e 64 20 6f of SQLite, and o
391d0 70 74 69 6f 6e 61 6c 6c 79 20 74 6f 20 72 65 73 ptionally to res
391e0 65 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 68 69 et various.** hi
391f0 67 68 77 61 74 65 72 20 6d 61 72 6b 73 2e 20 20 ghwater marks.
39200 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
39210 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 nt is an integer
39220 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 code for.** the
39230 20 73 70 65 63 69 66 69 63 20 70 61 72 61 6d 65 specific parame
39240 74 65 72 20 74 6f 20 6d 65 61 73 75 72 65 2e 20 ter to measure.
39250 20 52 65 63 6f 67 6e 69 7a 65 64 20 69 6e 74 65 Recognized inte
39260 67 65 72 20 63 6f 64 65 73 0a 2a 2a 20 61 72 65 ger codes.** are
39270 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 5b 53 51 of the form [SQ
39280 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f LITE_STATUS_MEMO
39290 52 59 5f 55 53 45 44 20 7c 20 53 51 4c 49 54 45 RY_USED | SQLITE
392a0 5f 53 54 41 54 55 53 5f 2e 2e 2e 5d 2e 0a 2a 2a _STATUS_...]..**
392b0 20 54 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c The current val
392c0 75 65 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 ue of the parame
392d0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 ter is returned
392e0 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e 0a into *pCurrent..
392f0 2a 2a 20 54 68 65 20 68 69 67 68 65 73 74 20 72 ** The highest r
39300 65 63 6f 72 64 65 64 20 76 61 6c 75 65 20 69 73 ecorded value is
39310 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 48 returned in *pH
39320 69 67 68 77 61 74 65 72 2e 20 20 49 66 20 74 68 ighwater. If th
39330 65 0a 2a 2a 20 72 65 73 65 74 46 6c 61 67 20 69 e.** resetFlag i
39340 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 s true, then the
39350 20 68 69 67 68 65 73 74 20 72 65 63 6f 72 64 20 highest record
39360 76 61 6c 75 65 20 69 73 20 72 65 73 65 74 20 61 value is reset a
39370 66 74 65 72 0a 2a 2a 20 2a 70 48 69 67 68 77 61 fter.** *pHighwa
39380 74 65 72 20 69 73 20 77 72 69 74 74 65 6e 2e 20 ter is written.
39390 53 6f 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 Some parameters
393a0 64 6f 20 6e 6f 74 20 72 65 63 6f 72 64 20 74 68 do not record th
393b0 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 76 61 6c e highest.** val
393c0 75 65 2e 20 20 46 6f 72 20 74 68 6f 73 65 20 70 ue. For those p
393d0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6e 6f 74 arameters.** not
393e0 68 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 20 hing is written
393f0 69 6e 74 6f 20 2a 70 48 69 67 68 77 61 74 65 72 into *pHighwater
39400 20 61 6e 64 20 74 68 65 20 72 65 73 65 74 46 6c and the resetFl
39410 61 67 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a ag is ignored..*
39420 2a 20 4f 74 68 65 72 20 70 61 72 61 6d 65 74 65 * Other paramete
39430 72 73 20 72 65 63 6f 72 64 20 6f 6e 6c 79 20 74 rs record only t
39440 68 65 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 he highwater mar
39450 6b 20 61 6e 64 20 6e 6f 74 20 74 68 65 20 63 75 k and not the cu
39460 72 72 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 rrent.** value.
39470 20 46 6f 72 20 74 68 65 73 65 20 6c 61 74 74 65 For these latte
39480 72 20 70 61 72 61 6d 65 74 65 72 73 20 6e 6f 74 r parameters not
39490 68 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 20 hing is written
394a0 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e 0a into *pCurrent..
394b0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
394c0 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 ne returns SQLIT
394d0 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 20 E_OK on success
394e0 61 6e 64 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a and a non-zero.*
394f0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f * [error code] o
39500 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a n failure..**.**
39510 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 This routine is
39520 20 74 68 72 65 61 64 73 61 66 65 20 62 75 74 20 threadsafe but
39530 69 73 20 6e 6f 74 20 61 74 6f 6d 69 63 2e 20 20 is not atomic.
39540 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e This routine can
39550 0a 2a 2a 20 63 61 6c 6c 65 64 20 77 68 69 6c 65 .** called while
39560 20 6f 74 68 65 72 20 74 68 72 65 61 64 73 20 61 other threads a
39570 72 65 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 73 re running the s
39580 61 6d 65 20 6f 72 20 64 69 66 66 65 72 65 6e 74 ame or different
39590 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 SQLite.** inter
395a0 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 20 faces. However
395b0 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 the values retur
395c0 6e 65 64 20 69 6e 20 2a 70 43 75 72 72 65 6e 74 ned in *pCurrent
395d0 20 61 6e 64 0a 2a 2a 20 2a 70 48 69 67 68 77 61 and.** *pHighwa
395e0 74 65 72 20 72 65 66 6c 65 63 74 20 74 68 65 20 ter reflect the
395f0 73 74 61 74 75 73 20 6f 66 20 53 51 4c 69 74 65 status of SQLite
39600 20 61 74 20 64 69 66 66 65 72 65 6e 74 20 70 6f at different po
39610 69 6e 74 73 20 69 6e 20 74 69 6d 65 0a 2a 2a 20 ints in time.**
39620 61 6e 64 20 69 74 20 69 73 20 70 6f 73 73 69 62 and it is possib
39630 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 le that another
39640 74 68 72 65 61 64 20 6d 69 67 68 74 20 63 68 61 thread might cha
39650 6e 67 65 20 74 68 65 20 70 61 72 61 6d 65 74 65 nge the paramete
39660 72 0a 2a 2a 20 69 6e 20 62 65 74 77 65 65 6e 20 r.** in between
39670 74 68 65 20 74 69 6d 65 73 20 77 68 65 6e 20 2a the times when *
39680 70 43 75 72 72 65 6e 74 20 61 6e 64 20 2a 70 48 pCurrent and *pH
39690 69 67 68 77 61 74 65 72 20 61 72 65 20 77 72 69 ighwater are wri
396a0 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 tten..**.** See
396b0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 also: [sqlite3_d
396c0 62 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2f 0a 53 b_status()].*/.S
396d0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
396e0 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
396f0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
39700 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 E_EXPERIMENTAL i
39710 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 61 74 75 nt sqlite3_statu
39720 73 28 69 6e 74 20 6f 70 2c 20 69 6e 74 20 2a 70 s(int op, int *p
39730 43 75 72 72 65 6e 74 2c 20 69 6e 74 20 2a 70 48 Current, int *pH
39740 69 67 68 77 61 74 65 72 2c 20 69 6e 74 20 72 65 ighwater, int re
39750 73 65 74 46 6c 61 67 29 3b 0a 0a 0a 2f 2a 0a 2a setFlag);.../*.*
39760 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 74 * CAPI3REF: Stat
39770 75 73 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48 us Parameters {H
39780 31 37 32 35 30 7d 20 3c 48 31 37 32 30 30 3e 0a 17250} <H17200>.
39790 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
397a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 **.** These inte
397b0 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 ger constants de
397c0 73 69 67 6e 61 74 65 20 76 61 72 69 6f 75 73 20 signate various
397d0 72 75 6e 2d 74 69 6d 65 20 73 74 61 74 75 73 20 run-time status
397e0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 parameters.** th
397f0 61 74 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e at can be return
39800 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 ed by [sqlite3_s
39810 74 61 74 75 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 tatus()]..**.**
39820 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 <dl>.** <dt>SQLI
39830 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 TE_STATUS_MEMORY
39840 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 _USED</dt>.** <d
39850 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 d>This parameter
39860 20 69 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 is the current
39870 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 amount of memory
39880 20 63 68 65 63 6b 65 64 20 6f 75 74 0a 2a 2a 20 checked out.**
39890 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d using [sqlite3_m
398a0 61 6c 6c 6f 63 28 29 5d 2c 20 65 69 74 68 65 72 alloc()], either
398b0 20 64 69 72 65 63 74 6c 79 20 6f 72 20 69 6e 64 directly or ind
398c0 69 72 65 63 74 6c 79 2e 20 20 54 68 65 0a 2a 2a irectly. The.**
398d0 20 66 69 67 75 72 65 20 69 6e 63 6c 75 64 65 73 figure includes
398e0 20 63 61 6c 6c 73 20 6d 61 64 65 20 74 6f 20 5b calls made to [
398f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
39900 5d 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 ] by the applica
39910 74 69 6f 6e 0a 2a 2a 20 61 6e 64 20 69 6e 74 65 tion.** and inte
39920 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 75 73 61 67 rnal memory usag
39930 65 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 e by the SQLite
39940 6c 69 62 72 61 72 79 2e 20 20 53 63 72 61 74 63 library. Scratc
39950 68 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 74 h memory.** cont
39960 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51 4c 49 54 rolled by [SQLIT
39970 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
39980 5d 20 61 6e 64 20 61 75 78 69 6c 69 61 72 79 20 ] and auxiliary
39990 70 61 67 65 2d 63 61 63 68 65 0a 2a 2a 20 6d 65 page-cache.** me
399a0 6d 6f 72 79 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 mory controlled
399b0 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 by [SQLITE_CONFI
399c0 47 5f 50 41 47 45 43 41 43 48 45 5d 20 69 73 20 G_PAGECACHE] is
399d0 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 0a not included in.
399e0 2a 2a 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 ** this paramete
399f0 72 2e 20 20 54 68 65 20 61 6d 6f 75 6e 74 20 72 r. The amount r
39a00 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 73 eturned is the s
39a10 75 6d 20 6f 66 20 74 68 65 20 61 6c 6c 6f 63 61 um of the alloca
39a20 74 69 6f 6e 0a 2a 2a 20 73 69 7a 65 73 20 61 73 tion.** sizes as
39a30 20 72 65 70 6f 72 74 65 64 20 62 79 20 74 68 65 reported by the
39a40 20 78 53 69 7a 65 20 6d 65 74 68 6f 64 20 69 6e xSize method in
39a50 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
39a60 74 68 6f 64 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a thods].</dd>.**.
39a70 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 ** <dt>SQLITE_ST
39a80 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f 53 49 5a 45 ATUS_MALLOC_SIZE
39a90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
39aa0 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f s parameter reco
39ab0 72 64 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 rds the largest
39ac0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
39ad0 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e n request.** han
39ae0 64 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ded to [sqlite3_
39af0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 malloc()] or [sq
39b00 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
39b10 20 28 6f 72 20 74 68 65 69 72 0a 2a 2a 20 69 6e (or their.** in
39b20 74 65 72 6e 61 6c 20 65 71 75 69 76 61 6c 65 6e ternal equivalen
39b30 74 73 29 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 ts). Only the v
39b40 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e alue returned in
39b50 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 the.** *pHighwa
39b60 74 65 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f ter parameter to
39b70 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 [sqlite3_status
39b80 28 29 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65 ()] is of intere
39b90 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c st. .** The val
39ba0 75 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 ue written into
39bb0 74 68 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61 the *pCurrent pa
39bc0 72 61 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66 rameter is undef
39bd0 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ined.</dd>.**.**
39be0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 <dt>SQLITE_STAT
39bf0 55 53 5f 50 41 47 45 43 41 43 48 45 5f 55 53 45 US_PAGECACHE_USE
39c00 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
39c10 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 is parameter ret
39c20 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
39c30 6f 66 20 70 61 67 65 73 20 75 73 65 64 20 6f 75 of pages used ou
39c40 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 61 67 t of the.** [pag
39c50 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c ecache memory al
39c60 6c 6f 63 61 74 6f 72 5d 20 74 68 61 74 20 77 61 locator] that wa
39c70 73 20 63 6f 6e 66 69 67 75 72 65 64 20 75 73 69 s configured usi
39c80 6e 67 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 ng .** [SQLITE_C
39c90 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d ONFIG_PAGECACHE]
39ca0 2e 20 20 54 68 65 0a 2a 2a 20 76 61 6c 75 65 20 . The.** value
39cb0 72 65 74 75 72 6e 65 64 20 69 73 20 69 6e 20 70 returned is in p
39cc0 61 67 65 73 2c 20 6e 6f 74 20 69 6e 20 62 79 74 ages, not in byt
39cd0 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c es.</dd>.**.** <
39ce0 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 dt>SQLITE_STATUS
39cf0 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 45 52 46 _PAGECACHE_OVERF
39d00 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e LOW</dt>.** <dd>
39d10 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 This parameter r
39d20 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
39d30 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 70 61 r of bytes of pa
39d40 67 65 20 63 61 63 68 65 0a 2a 2a 20 61 6c 6c 6f ge cache.** allo
39d50 63 61 74 69 6f 6e 20 77 68 69 63 68 20 63 6f 75 cation which cou
39d60 6c 64 20 6e 6f 74 20 62 65 20 73 74 61 74 69 73 ld not be statis
39d70 66 69 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c fied by the [SQL
39d80 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
39d90 41 43 48 45 5d 0a 2a 2a 20 62 75 66 66 65 72 20 ACHE].** buffer
39da0 61 6e 64 20 77 68 65 72 65 20 66 6f 72 63 65 64 and where forced
39db0 20 74 6f 20 6f 76 65 72 66 6c 6f 77 20 74 6f 20 to overflow to
39dc0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
39dd0 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 72 65 74 75 )]. The.** retu
39de0 72 6e 65 64 20 76 61 6c 75 65 20 69 6e 63 6c 75 rned value inclu
39df0 64 65 73 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 des allocations
39e00 74 68 61 74 20 6f 76 65 72 66 6c 6f 77 65 64 20 that overflowed
39e10 62 65 63 61 75 73 65 20 74 68 65 79 0a 2a 2a 20 because they.**
39e20 77 68 65 72 65 20 74 6f 6f 20 6c 61 72 67 65 20 where too large
39e30 28 74 68 65 79 20 77 65 72 65 20 6c 61 72 67 65 (they were large
39e40 72 20 74 68 61 6e 20 74 68 65 20 22 73 7a 22 20 r than the "sz"
39e50 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
39e60 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
39e70 41 47 45 43 41 43 48 45 5d 29 20 61 6e 64 20 61 AGECACHE]) and a
39e80 6c 6c 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20 llocations that
39e90 6f 76 65 72 66 6c 6f 77 65 64 20 62 65 63 61 75 overflowed becau
39ea0 73 65 0a 2a 2a 20 6e 6f 20 73 70 61 63 65 20 77 se.** no space w
39eb0 61 73 20 6c 65 66 74 20 69 6e 20 74 68 65 20 70 as left in the p
39ec0 61 67 65 20 63 61 63 68 65 2e 3c 2f 64 64 3e 0a age cache.</dd>.
39ed0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
39ee0 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 _STATUS_PAGECACH
39ef0 45 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c E_SIZE</dt>.** <
39f00 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 dd>This paramete
39f10 72 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 r records the la
39f20 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 6c 6c rgest memory all
39f30 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 0a ocation request.
39f40 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b 70 61 ** handed to [pa
39f50 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 gecache memory a
39f60 6c 6c 6f 63 61 74 6f 72 5d 2e 20 20 4f 6e 6c 79 llocator]. Only
39f70 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
39f80 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 ned in the.** *p
39f90 48 69 67 68 77 61 74 65 72 20 70 61 72 61 6d 65 Highwater parame
39fa0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
39fb0 73 74 61 74 75 73 28 29 5d 20 69 73 20 6f 66 20 status()] is of
39fc0 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a 20 54 interest. .** T
39fd0 68 65 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e he value written
39fe0 20 69 6e 74 6f 20 74 68 65 20 2a 70 43 75 72 72 into the *pCurr
39ff0 65 6e 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 ent parameter is
3a000 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e undefined.</dd>
3a010 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
3a020 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 48 E_STATUS_SCRATCH
3a030 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 _USED</dt>.** <d
3a040 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 d>This parameter
3a050 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
3a060 62 65 72 20 6f 66 20 61 6c 6c 6f 63 61 74 69 6f ber of allocatio
3a070 6e 73 20 75 73 65 64 20 6f 75 74 20 6f 66 20 74 ns used out of t
3a080 68 65 0a 2a 2a 20 5b 73 63 72 61 74 63 68 20 6d he.** [scratch m
3a090 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d emory allocator]
3a0a0 20 63 6f 6e 66 69 67 75 72 65 64 20 75 73 69 6e configured usin
3a0b0 67 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e g.** [SQLITE_CON
3a0c0 46 49 47 5f 53 43 52 41 54 43 48 5d 2e 20 20 54 FIG_SCRATCH]. T
3a0d0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
3a0e0 64 20 69 73 20 69 6e 20 61 6c 6c 6f 63 61 74 69 d is in allocati
3a0f0 6f 6e 73 2c 20 6e 6f 74 0a 2a 2a 20 69 6e 20 62 ons, not.** in b
3a100 79 74 65 73 2e 20 20 53 69 6e 63 65 20 61 20 73 ytes. Since a s
3a110 69 6e 67 6c 65 20 74 68 72 65 61 64 20 6d 61 79 ingle thread may
3a120 20 6f 6e 6c 79 20 68 61 76 65 20 6f 6e 65 20 73 only have one s
3a130 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f cratch allocatio
3a140 6e 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 n.** outstanding
3a150 20 61 74 20 74 69 6d 65 2c 20 74 68 69 73 20 70 at time, this p
3a160 61 72 61 6d 65 74 65 72 20 61 6c 73 6f 20 72 65 arameter also re
3a170 70 6f 72 74 73 20 74 68 65 20 6e 75 6d 62 65 72 ports the number
3a180 20 6f 66 20 74 68 72 65 61 64 73 0a 2a 2a 20 75 of threads.** u
3a190 73 69 6e 67 20 73 63 72 61 74 63 68 20 6d 65 6d sing scratch mem
3a1a0 6f 72 79 20 61 74 20 74 68 65 20 73 61 6d 65 20 ory at the same
3a1b0 74 69 6d 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a time.</dd>.**.**
3a1c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 <dt>SQLITE_STAT
3a1d0 55 53 5f 53 43 52 41 54 43 48 5f 4f 56 45 52 46 US_SCRATCH_OVERF
3a1e0 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e LOW</dt>.** <dd>
3a1f0 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 This parameter r
3a200 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
3a210 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 73 63 r of bytes of sc
3a220 72 61 74 63 68 20 6d 65 6d 6f 72 79 0a 2a 2a 20 ratch memory.**
3a230 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 68 69 63 68 allocation which
3a240 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 73 74 could not be st
3a250 61 74 69 73 66 69 65 64 20 62 79 20 74 68 65 20 atisfied by the
3a260 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
3a270 43 52 41 54 43 48 5d 0a 2a 2a 20 62 75 66 66 65 CRATCH].** buffe
3a280 72 20 61 6e 64 20 77 68 65 72 65 20 66 6f 72 63 r and where forc
3a290 65 64 20 74 6f 20 6f 76 65 72 66 6c 6f 77 20 74 ed to overflow t
3a2a0 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f o [sqlite3_mallo
3a2b0 63 28 29 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 c()]. The value
3a2c0 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e s.** returned in
3a2d0 63 6c 75 64 65 20 6f 76 65 72 66 6c 6f 77 73 20 clude overflows
3a2e0 62 65 63 61 75 73 65 20 74 68 65 20 72 65 71 75 because the requ
3a2f0 65 73 74 65 64 20 61 6c 6c 6f 63 61 74 69 6f 6e ested allocation
3a300 20 77 61 73 20 74 6f 6f 0a 2a 2a 20 6c 61 72 67 was too.** larg
3a310 65 72 20 28 74 68 61 74 20 69 73 2c 20 62 65 63 er (that is, bec
3a320 61 75 73 65 20 74 68 65 20 72 65 71 75 65 73 74 ause the request
3a330 65 64 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 ed allocation wa
3a340 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 s larger than th
3a350 65 0a 2a 2a 20 22 73 7a 22 20 70 61 72 61 6d 65 e.** "sz" parame
3a360 74 65 72 20 74 6f 20 5b 53 51 4c 49 54 45 5f 43 ter to [SQLITE_C
3a370 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 29 20 ONFIG_SCRATCH])
3a380 61 6e 64 20 62 65 63 61 75 73 65 20 6e 6f 20 73 and because no s
3a390 63 72 61 74 63 68 20 62 75 66 66 65 72 0a 2a 2a cratch buffer.**
3a3a0 20 73 6c 6f 74 73 20 77 65 72 65 20 61 76 61 69 slots were avai
3a3b0 6c 61 62 6c 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a lable..** </dd>.
3a3c0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
3a3d0 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f _STATUS_SCRATCH_
3a3e0 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 SIZE</dt>.** <dd
3a3f0 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 >This parameter
3a400 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 72 67 records the larg
3a410 65 73 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 est memory alloc
3a420 61 74 69 6f 6e 20 72 65 71 75 65 73 74 0a 2a 2a ation request.**
3a430 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 63 72 61 handed to [scra
3a440 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 tch memory alloc
3a450 61 74 6f 72 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 ator]. Only the
3a460 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
3a470 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68 in the.** *pHigh
3a480 77 61 74 65 72 20 70 61 72 61 6d 65 74 65 72 20 water parameter
3a490 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 to [sqlite3_stat
3a4a0 75 73 28 29 5d 20 69 73 20 6f 66 20 69 6e 74 65 us()] is of inte
3a4b0 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76 rest. .** The v
3a4c0 61 6c 75 65 20 77 72 69 74 74 65 6e 20 69 6e 74 alue written int
3a4d0 6f 20 74 68 65 20 2a 70 43 75 72 72 65 6e 74 20 o the *pCurrent
3a4e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 6e 64 parameter is und
3a4f0 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a efined.</dd>.**.
3a500 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 ** <dt>SQLITE_ST
3a510 41 54 55 53 5f 50 41 52 53 45 52 5f 53 54 41 43 ATUS_PARSER_STAC
3a520 4b 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 K</dt>.** <dd>Th
3a530 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 63 is parameter rec
3a540 6f 72 64 73 20 74 68 65 20 64 65 65 70 65 73 74 ords the deepest
3a550 20 70 61 72 73 65 72 20 73 74 61 63 6b 2e 20 20 parser stack.
3a560 49 74 20 69 73 20 6f 6e 6c 79 0a 2a 2a 20 6d 65 It is only.** me
3a570 61 6e 69 6e 67 66 75 6c 20 69 66 20 53 51 4c 69 aningful if SQLi
3a580 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
3a590 69 74 68 20 5b 59 59 54 52 41 43 4b 4d 41 58 53 ith [YYTRACKMAXS
3a5a0 54 41 43 4b 44 45 50 54 48 5d 2e 3c 2f 64 64 3e TACKDEPTH].</dd>
3a5b0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </dl>.**.**
3a5c0 4e 65 77 20 73 74 61 74 75 73 20 70 61 72 61 6d New status param
3a5d0 65 74 65 72 73 20 6d 61 79 20 62 65 20 61 64 64 eters may be add
3a5e0 65 64 20 66 72 6f 6d 20 74 69 6d 65 20 74 6f 20 ed from time to
3a5f0 74 69 6d 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 time..*/.#define
3a600 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d SQLITE_STATUS_M
3a610 45 4d 4f 52 59 5f 55 53 45 44 20 20 20 20 20 20 EMORY_USED
3a620 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
3a630 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 LITE_STATUS_PAGE
3a640 43 41 43 48 45 5f 55 53 45 44 20 20 20 20 20 20 CACHE_USED
3a650 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
3a660 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 43 E_STATUS_PAGECAC
3a670 48 45 5f 4f 56 45 52 46 4c 4f 57 20 20 20 32 0a HE_OVERFLOW 2.
3a680 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
3a690 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f 55 53 TATUS_SCRATCH_US
3a6a0 45 44 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 ED 3.#de
3a6b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 fine SQLITE_STAT
3a6c0 55 53 5f 53 43 52 41 54 43 48 5f 4f 56 45 52 46 US_SCRATCH_OVERF
3a6d0 4c 4f 57 20 20 20 20 20 34 0a 23 64 65 66 69 6e LOW 4.#defin
3a6e0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f e SQLITE_STATUS_
3a6f0 4d 41 4c 4c 4f 43 5f 53 49 5a 45 20 20 20 20 20 MALLOC_SIZE
3a700 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 5.#define S
3a710 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 52 QLITE_STATUS_PAR
3a720 53 45 52 5f 53 54 41 43 4b 20 20 20 20 20 20 20 SER_STACK
3a730 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 6.#define SQLI
3a740 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 TE_STATUS_PAGECA
3a750 43 48 45 5f 53 49 5a 45 20 20 20 20 20 20 20 37 CHE_SIZE 7
3a760 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3a770 53 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f 53 STATUS_SCRATCH_S
3a780 49 5a 45 20 20 20 20 20 20 20 20 20 38 0a 0a 2f IZE 8../
3a790 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
3a7a0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
3a7b0 6f 6e 20 53 74 61 74 75 73 20 7b 48 31 37 35 30 on Status {H1750
3a7c0 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 0} <S60200>.** E
3a7d0 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
3a7e0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
3a7f0 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 74 72 is used to retr
3a800 69 65 76 65 20 72 75 6e 74 69 6d 65 20 73 74 61 ieve runtime sta
3a810 74 75 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 tus information
3a820 0a 2a 2a 20 61 62 6f 75 74 20 61 20 73 69 6e 67 .** about a sing
3a830 6c 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e le [database con
3a840 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 nection]. The f
3a850 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
3a860 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
3a870 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 62 6a 65 connection obje
3a880 63 74 20 74 6f 20 62 65 20 69 6e 74 65 72 72 6f ct to be interro
3a890 67 61 74 65 64 2e 20 20 54 68 65 20 73 65 63 6f gated. The seco
3a8a0 6e 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 nd argument.** i
3a8b0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 s the parameter
3a8c0 74 6f 20 69 6e 74 65 72 72 6f 67 61 74 65 2e 20 to interrogate.
3a8d0 20 43 75 72 72 65 6e 74 6c 79 2c 20 74 68 65 20 Currently, the
3a8e0 6f 6e 6c 79 20 61 6c 6c 6f 77 65 64 20 76 61 6c only allowed val
3a8f0 75 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 65 ue.** for the se
3a900 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
3a910 73 20 5b 53 51 4c 49 54 45 5f 44 42 53 54 41 54 s [SQLITE_DBSTAT
3a920 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45 US_LOOKASIDE_USE
3a930 44 5d 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 D]..** Additiona
3a940 6c 20 6f 70 74 69 6f 6e 73 20 77 69 6c 6c 20 6c l options will l
3a950 69 6b 65 6c 79 20 61 70 70 65 61 72 20 69 6e 20 ikely appear in
3a960 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
3a970 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
3a980 20 54 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c The current val
3a990 75 65 20 6f 66 20 74 68 65 20 72 65 71 75 65 73 ue of the reques
3a9a0 74 65 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ted parameter is
3a9b0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 written into *p
3a9c0 43 75 72 0a 2a 2a 20 61 6e 64 20 74 68 65 20 68 Cur.** and the h
3a9d0 69 67 68 65 73 74 20 69 6e 73 74 61 6e 74 61 6e ighest instantan
3a9e0 65 6f 75 73 20 76 61 6c 75 65 20 69 73 20 77 72 eous value is wr
3a9f0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48 69 77 itten into *pHiw
3aa00 74 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 72 tr. If.** the r
3aa10 65 73 65 74 46 6c 67 20 69 73 20 74 72 75 65 2c esetFlg is true,
3aa20 20 74 68 65 6e 20 74 68 65 20 68 69 67 68 65 73 then the highes
3aa30 74 20 69 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 t instantaneous
3aa40 76 61 6c 75 65 20 69 73 0a 2a 2a 20 72 65 73 65 value is.** rese
3aa50 74 20 62 61 63 6b 20 64 6f 77 6e 20 74 6f 20 74 t back down to t
3aa60 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 he current value
3aa70 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
3aa80 3a 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 : [sqlite3_statu
3aa90 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 s()] and [sqlite
3aaa0 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 29 5d 3_stmt_status()]
3aab0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
3aac0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
3aad0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
3aae0 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 SQLITE_EXPERIME
3aaf0 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 NTAL int sqlite3
3ab00 5f 64 62 5f 73 74 61 74 75 73 28 73 71 6c 69 74 _db_status(sqlit
3ab10 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 69 6e 74 e3*, int op, int
3ab20 20 2a 70 43 75 72 2c 20 69 6e 74 20 2a 70 48 69 *pCur, int *pHi
3ab30 77 74 72 2c 20 69 6e 74 20 72 65 73 65 74 46 6c wtr, int resetFl
3ab40 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 g);../*.** CAPI3
3ab50 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 REF: Status Para
3ab60 6d 65 74 65 72 73 20 66 6f 72 20 64 61 74 61 62 meters for datab
3ab70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
3ab80 7b 48 31 37 35 32 30 7d 20 3c 48 31 37 35 30 30 {H17520} <H17500
3ab90 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
3aba0 4c 0a 2a 2a 0a 2a 2a 20 53 74 61 74 75 73 20 76 L.**.** Status v
3abb0 65 72 62 73 20 66 6f 72 20 5b 73 71 6c 69 74 65 erbs for [sqlite
3abc0 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 2e 0a 3_db_status()]..
3abd0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 **.** <dl>.** <d
3abe0 74 3e 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 t>SQLITE_DBSTATU
3abf0 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 S_LOOKASIDE_USED
3ac00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
3ac10 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 s parameter retu
3ac20 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
3ac30 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f f lookaside memo
3ac40 72 79 20 73 6c 6f 74 73 20 63 75 72 72 65 6e 74 ry slots current
3ac50 6c 79 0a 2a 2a 20 63 68 65 63 6b 65 64 20 6f 75 ly.** checked ou
3ac60 74 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e t.</dd>.** </dl>
3ac70 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
3ac80 54 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b TE_DBSTATUS_LOOK
3ac90 41 53 49 44 45 5f 55 53 45 44 20 20 20 20 20 30 ASIDE_USED 0
3aca0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
3acb0 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 F: Prepared Stat
3acc0 65 6d 65 6e 74 20 53 74 61 74 75 73 20 7b 48 31 ement Status {H1
3acd0 37 35 35 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 7550} <S60200>.*
3ace0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
3acf0 2a 0a 2a 2a 20 45 61 63 68 20 70 72 65 70 61 72 *.** Each prepar
3ad00 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 69 ed statement mai
3ad10 6e 74 61 69 6e 73 20 76 61 72 69 6f 75 73 0a 2a ntains various.*
3ad20 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 * [SQLITE_STMTST
3ad30 41 54 55 53 5f 53 4f 52 54 20 7c 20 63 6f 75 6e ATUS_SORT | coun
3ad40 74 65 72 73 5d 20 74 68 61 74 20 6d 65 61 73 75 ters] that measu
3ad50 72 65 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a re the number.**
3ad60 20 6f 66 20 74 69 6d 65 73 20 69 74 20 68 61 73 of times it has
3ad70 20 70 65 72 66 6f 72 6d 65 64 20 73 70 65 63 69 performed speci
3ad80 66 69 63 20 6f 70 65 72 61 74 69 6f 6e 73 2e 20 fic operations.
3ad90 20 54 68 65 73 65 20 63 6f 75 6e 74 65 72 73 20 These counters
3ada0 63 61 6e 0a 2a 2a 20 62 65 20 75 73 65 64 20 74 can.** be used t
3adb0 6f 20 6d 6f 6e 69 74 6f 72 20 74 68 65 20 70 65 o monitor the pe
3adc0 72 66 6f 72 6d 61 6e 63 65 20 63 68 61 72 61 63 rformance charac
3add0 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 teristics of the
3ade0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 prepared.** sta
3adf0 74 65 6d 65 6e 74 73 2e 20 20 46 6f 72 20 65 78 tements. For ex
3ae00 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 6e 75 ample, if the nu
3ae10 6d 62 65 72 20 6f 66 20 74 61 62 6c 65 20 73 74 mber of table st
3ae20 65 70 73 20 67 72 65 61 74 6c 79 20 65 78 63 65 eps greatly exce
3ae30 65 64 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 eds.** the numbe
3ae40 72 20 6f 66 20 74 61 62 6c 65 20 73 65 61 72 63 r of table searc
3ae50 68 65 73 20 6f 72 20 72 65 73 75 6c 74 20 72 6f hes or result ro
3ae60 77 73 2c 20 74 68 61 74 20 77 6f 75 6c 64 20 74 ws, that would t
3ae70 65 6e 64 20 74 6f 20 69 6e 64 69 63 61 74 65 0a end to indicate.
3ae80 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 65 70 ** that the prep
3ae90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 ared statement i
3aea0 73 20 75 73 69 6e 67 20 61 20 66 75 6c 6c 20 74 s using a full t
3aeb0 61 62 6c 65 20 73 63 61 6e 20 72 61 74 68 65 72 able scan rather
3aec0 20 74 68 61 6e 0a 2a 2a 20 61 6e 20 69 6e 64 65 than.** an inde
3aed0 78 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 x. .**.** This
3aee0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 interface is use
3aef0 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 6e d to retrieve an
3af00 64 20 72 65 73 65 74 20 63 6f 75 6e 74 65 72 20 d reset counter
3af10 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 61 values from.** a
3af20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
3af30 6d 65 6e 74 5d 2e 20 20 54 68 65 20 66 69 72 73 ment]. The firs
3af40 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 t argument is th
3af50 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
3af60 6d 65 6e 74 0a 2a 2a 20 6f 62 6a 65 63 74 20 74 ment.** object t
3af70 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65 o be interrogate
3af80 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 d. The second a
3af90 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e rgument.** is an
3afa0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f integer code fo
3afb0 72 20 61 20 73 70 65 63 69 66 69 63 20 5b 53 51 r a specific [SQ
3afc0 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f LITE_STMTSTATUS_
3afd0 53 4f 52 54 20 7c 20 63 6f 75 6e 74 65 72 5d 0a SORT | counter].
3afe0 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 6f ** to be interro
3aff0 67 61 74 65 64 2e 20 0a 2a 2a 20 54 68 65 20 63 gated. .** The c
3b000 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 urrent value of
3b010 74 68 65 20 72 65 71 75 65 73 74 65 64 20 63 6f the requested co
3b020 75 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 unter is returne
3b030 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 d..** If the res
3b040 65 74 46 6c 67 20 69 73 20 74 72 75 65 2c 20 74 etFlg is true, t
3b050 68 65 6e 20 74 68 65 20 63 6f 75 6e 74 65 72 20 hen the counter
3b060 69 73 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f is reset to zero
3b070 20 61 66 74 65 72 20 74 68 69 73 0a 2a 2a 20 69 after this.** i
3b080 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 72 65 nterface call re
3b090 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 turns..**.** See
3b0a0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
3b0b0 73 74 61 74 75 73 28 29 5d 20 61 6e 64 20 5b 73 status()] and [s
3b0c0 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 qlite3_db_status
3b0d0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ()]..*/.SQLITE_A
3b0e0 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
3b0f0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
3b100 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 API SQLITE_EXPER
3b110 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 IMENTAL int sqli
3b120 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 te3_stmt_status(
3b130 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
3b140 6e 74 20 6f 70 2c 69 6e 74 20 72 65 73 65 74 46 nt op,int resetF
3b150 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 lg);../*.** CAPI
3b160 33 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 3REF: Status Par
3b170 61 6d 65 74 65 72 73 20 66 6f 72 20 70 72 65 70 ameters for prep
3b180 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 ared statements
3b190 7b 48 31 37 35 37 30 7d 20 3c 48 31 37 35 35 30 {H17570} <H17550
3b1a0 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
3b1b0 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 72 L.**.** These pr
3b1c0 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f eprocessor macro
3b1d0 73 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 s define integer
3b1e0 20 63 6f 64 65 73 20 74 68 61 74 20 6e 61 6d 65 codes that name
3b1f0 20 63 6f 75 6e 74 65 72 0a 2a 2a 20 76 61 6c 75 counter.** valu
3b200 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 es associated wi
3b210 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f th the [sqlite3_
3b220 73 74 6d 74 5f 73 74 61 74 75 73 28 29 5d 20 69 stmt_status()] i
3b230 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65 nterface..** The
3b240 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 meanings of the
3b250 20 76 61 72 69 6f 75 73 20 63 6f 75 6e 74 65 72 various counter
3b260 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 s are as follows
3b270 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 :.**.** <dl>.**
3b280 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 4d 54 53 <dt>SQLITE_STMTS
3b290 54 41 54 55 53 5f 46 55 4c 4c 53 43 41 4e 5f 53 TATUS_FULLSCAN_S
3b2a0 54 45 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TEP</dt>.** <dd>
3b2b0 54 68 69 73 20 69 73 20 74 68 65 20 6e 75 6d 62 This is the numb
3b2c0 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 er of times that
3b2d0 20 53 51 4c 69 74 65 20 68 61 73 20 73 74 65 70 SQLite has step
3b2e0 70 65 64 20 66 6f 72 77 61 72 64 20 69 6e 0a 2a ped forward in.*
3b2f0 2a 20 61 20 74 61 62 6c 65 20 61 73 20 70 61 72 * a table as par
3b300 74 20 6f 66 20 61 20 66 75 6c 6c 20 74 61 62 6c t of a full tabl
3b310 65 20 73 63 61 6e 2e 20 20 4c 61 72 67 65 20 6e e scan. Large n
3b320 75 6d 62 65 72 73 20 66 6f 72 20 74 68 69 73 20 umbers for this
3b330 63 6f 75 6e 74 65 72 0a 2a 2a 20 6d 61 79 20 69 counter.** may i
3b340 6e 64 69 63 61 74 65 20 6f 70 70 6f 72 74 75 6e ndicate opportun
3b350 69 74 69 65 73 20 66 6f 72 20 70 65 72 66 6f 72 ities for perfor
3b360 6d 61 6e 63 65 20 69 6d 70 72 6f 76 65 6d 65 6e mance improvemen
3b370 74 20 74 68 72 6f 75 67 68 20 0a 2a 2a 20 63 61 t through .** ca
3b380 72 65 66 75 6c 20 75 73 65 20 6f 66 20 69 6e 64 reful use of ind
3b390 69 63 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ices.</dd>.**.**
3b3a0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 4d 54 <dt>SQLITE_STMT
3b3b0 53 54 41 54 55 53 5f 53 4f 52 54 3c 2f 64 74 3e STATUS_SORT</dt>
3b3c0 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 69 73 20 .** <dd>This is
3b3d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 73 6f the number of so
3b3e0 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 74 68 rt operations th
3b3f0 61 74 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 at have occurred
3b400 2e 0a 2a 2a 20 41 20 6e 6f 6e 2d 7a 65 72 6f 20 ..** A non-zero
3b410 76 61 6c 75 65 20 69 6e 20 74 68 69 73 20 63 6f value in this co
3b420 75 6e 74 65 72 20 6d 61 79 20 69 6e 64 69 63 61 unter may indica
3b430 74 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 te an opportunit
3b440 79 20 74 6f 0a 2a 2a 20 69 6d 70 72 6f 76 65 6d y to.** improvem
3b450 65 6e 74 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 ent performance
3b460 74 68 72 6f 75 67 68 20 63 61 72 65 66 75 6c 20 through careful
3b470 75 73 65 20 6f 66 20 69 6e 64 69 63 65 73 2e 3c use of indices.<
3b480 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e /dd>.**.** </dl>
3b490 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
3b4a0 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 46 55 TE_STMTSTATUS_FU
3b4b0 4c 4c 53 43 41 4e 5f 53 54 45 50 20 20 20 20 20 LLSCAN_STEP
3b4c0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
3b4d0 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 _STMTSTATUS_SORT
3b4e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 2.
3b4f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
3b500 20 43 75 73 74 6f 6d 20 50 61 67 65 20 43 61 63 Custom Page Cac
3b510 68 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 50 he Object.** EXP
3b520 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
3b530 54 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63 The sqlite3_pcac
3b540 68 65 20 74 79 70 65 20 69 73 20 6f 70 61 71 75 he type is opaqu
3b550 65 2e 20 20 49 74 20 69 73 20 69 6d 70 6c 65 6d e. It is implem
3b560 65 6e 74 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 ented by.** the
3b570 70 6c 75 67 67 61 62 6c 65 20 6d 6f 64 75 6c 65 pluggable module
3b580 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f . The SQLite co
3b590 72 65 20 68 61 73 20 6e 6f 20 6b 6e 6f 77 6c 65 re has no knowle
3b5a0 64 67 65 20 6f 66 0a 2a 2a 20 69 74 73 20 73 69 dge of.** its si
3b5b0 7a 65 20 6f 72 20 69 6e 74 65 72 6e 61 6c 20 73 ze or internal s
3b5c0 74 72 75 63 74 75 72 65 20 61 6e 64 20 6e 65 76 tructure and nev
3b5d0 65 72 20 64 65 61 6c 73 20 77 69 74 68 20 74 68 er deals with th
3b5e0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 e.** sqlite3_pca
3b5f0 63 68 65 20 6f 62 6a 65 63 74 20 65 78 63 65 70 che object excep
3b600 74 20 62 79 20 68 6f 6c 64 69 6e 67 20 61 6e 64 t by holding and
3b610 20 70 61 73 73 69 6e 67 20 70 6f 69 6e 74 65 72 passing pointer
3b620 73 0a 2a 2a 20 74 6f 20 74 68 65 20 6f 62 6a 65 s.** to the obje
3b630 63 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 5b 73 ct..**.** See [s
3b640 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
3b650 74 68 6f 64 73 5d 20 66 6f 72 20 61 64 64 69 74 thods] for addit
3b660 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
3b670 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 n..*/.typedef st
3b680 72 75 63 74 20 73 71 6c 69 74 65 33 5f 70 63 61 ruct sqlite3_pca
3b690 63 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63 che sqlite3_pcac
3b6a0 68 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 he;../*.** CAPI3
3b6b0 52 45 46 3a 20 41 70 70 6c 69 63 61 74 69 6f 6e REF: Application
3b6c0 20 44 65 66 69 6e 65 64 20 50 61 67 65 20 43 61 Defined Page Ca
3b6d0 63 68 65 2e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 che..** EXPERIME
3b6e0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b NTAL.**.** The [
3b6f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 sqlite3_config](
3b700 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
3b710 43 41 43 48 45 5d 2c 20 2e 2e 2e 29 20 69 6e 74 CACHE], ...) int
3b720 65 72 66 61 63 65 20 63 61 6e 0a 2a 2a 20 72 65 erface can.** re
3b730 67 69 73 74 65 72 20 61 6e 20 61 6c 74 65 72 6e gister an altern
3b740 61 74 69 76 65 20 70 61 67 65 20 63 61 63 68 65 ative page cache
3b750 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
3b760 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 6e by passing in an
3b770 20 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 .** instance of
3b780 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61 the sqlite3_pca
3b790 63 68 65 5f 6d 65 74 68 6f 64 73 20 73 74 72 75 che_methods stru
3b7a0 63 74 75 72 65 2e 20 54 68 65 20 6d 61 6a 6f 72 cture. The major
3b7b0 69 74 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 68 ity of the .** h
3b7c0 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 65 64 20 eap memory used
3b7d0 62 79 20 73 71 6c 69 74 65 20 69 73 20 75 73 65 by sqlite is use
3b7e0 64 20 62 79 20 74 68 65 20 70 61 67 65 20 63 61 d by the page ca
3b7f0 63 68 65 20 74 6f 20 63 61 63 68 65 20 64 61 74 che to cache dat
3b800 61 20 72 65 61 64 20 0a 2a 2a 20 66 72 6f 6d 2c a read .** from,
3b810 20 6f 72 20 72 65 61 64 79 20 74 6f 20 62 65 20 or ready to be
3b820 77 72 69 74 74 65 6e 20 74 6f 2c 20 74 68 65 20 written to, the
3b830 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 42 database file. B
3b840 79 20 69 6d 70 6c 65 6d 65 6e 74 69 6e 67 20 61 y implementing a
3b850 20 0a 2a 2a 20 63 75 73 74 6f 6d 20 70 61 67 65 .** custom page
3b860 20 63 61 63 68 65 20 75 73 69 6e 67 20 74 68 69 cache using thi
3b870 73 20 41 50 49 2c 20 61 6e 20 61 70 70 6c 69 63 s API, an applic
3b880 61 74 69 6f 6e 20 63 61 6e 20 63 6f 6e 74 72 6f ation can contro
3b890 6c 20 6d 6f 72 65 20 0a 2a 2a 20 70 72 65 63 69 l more .** preci
3b8a0 73 65 6c 79 20 74 68 65 20 61 6d 6f 75 6e 74 20 sely the amount
3b8b0 6f 66 20 6d 65 6d 6f 72 79 20 63 6f 6e 73 75 6d of memory consum
3b8c0 65 64 20 62 79 20 73 71 6c 69 74 65 2c 20 74 68 ed by sqlite, th
3b8d0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 0a e way in which .
3b8e0 2a 2a 20 73 61 69 64 20 6d 65 6d 6f 72 79 20 69 ** said memory i
3b8f0 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 64 20 s allocated and
3b900 72 65 6c 65 61 73 65 64 2c 20 61 6e 64 20 74 68 released, and th
3b910 65 20 70 6f 6c 69 63 69 65 73 20 75 73 65 64 20 e policies used
3b920 74 6f 20 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 to .** determine
3b930 20 65 78 61 63 74 6c 79 20 77 68 69 63 68 20 70 exactly which p
3b940 61 72 74 73 20 6f 66 20 61 20 64 61 74 61 62 61 arts of a databa
3b950 73 65 20 66 69 6c 65 20 61 72 65 20 63 61 63 68 se file are cach
3b960 65 64 20 61 6e 64 20 66 6f 72 20 0a 2a 2a 20 68 ed and for .** h
3b970 6f 77 20 6c 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 ow long..**.** T
3b980 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 he contents of t
3b990 68 65 20 73 74 72 75 63 74 75 72 65 20 61 72 65 he structure are
3b9a0 20 63 6f 70 69 65 64 20 74 6f 20 61 6e 20 69 6e copied to an in
3b9b0 74 65 72 6e 61 6c 20 62 75 66 66 65 72 20 62 79 ternal buffer by
3b9c0 20 73 71 6c 69 74 65 0a 2a 2a 20 77 69 74 68 69 sqlite.** withi
3b9d0 6e 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 5b 73 n the call to [s
3b9e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 2e 0a qlite3_config]..
3b9f0 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 28 **.** The xInit(
3ba00 29 20 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c ) method is call
3ba10 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 ed once for each
3ba20 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
3ba30 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 0a 3_initialize()].
3ba40 2a 2a 20 28 75 73 75 61 6c 6c 79 20 6f 6e 6c 79 ** (usually only
3ba50 20 6f 6e 63 65 20 64 75 72 69 6e 67 20 74 68 65 once during the
3ba60 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 lifetime of the
3ba70 20 70 72 6f 63 65 73 73 29 2e 20 49 74 20 69 73 process). It is
3ba80 20 70 61 73 73 65 64 0a 2a 2a 20 61 20 63 6f 70 passed.** a cop
3ba90 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 y of the sqlite3
3baa0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2e _pcache_methods.
3bab0 70 41 72 67 20 76 61 6c 75 65 2e 20 49 74 20 63 pArg value. It c
3bac0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 73 65 an be used to se
3bad0 74 0a 2a 2a 20 75 70 20 67 6c 6f 62 61 6c 20 73 t.** up global s
3bae0 74 72 75 63 74 75 72 65 73 20 61 6e 64 20 6d 75 tructures and mu
3baf0 74 65 78 65 73 20 72 65 71 75 69 72 65 64 20 62 texes required b
3bb00 79 20 74 68 65 20 63 75 73 74 6f 6d 20 70 61 67 y the custom pag
3bb10 65 20 63 61 63 68 65 20 0a 2a 2a 20 69 6d 70 6c e cache .** impl
3bb20 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 54 68 65 20 ementation. The
3bb30 78 53 68 75 74 64 6f 77 6e 28 29 20 6d 65 74 68 xShutdown() meth
3bb40 6f 64 20 69 73 20 63 61 6c 6c 65 64 20 66 72 6f od is called fro
3bb50 6d 20 77 69 74 68 69 6e 20 0a 2a 2a 20 5b 73 71 m within .** [sq
3bb60 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
3bb70 5d 2c 20 69 66 20 74 68 65 20 61 70 70 6c 69 63 ], if the applic
3bb80 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 74 68 ation invokes th
3bb90 69 73 20 41 50 49 2e 20 49 74 20 63 61 6e 20 62 is API. It can b
3bba0 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 63 6c 65 e used.** to cle
3bbb0 61 6e 20 75 70 20 61 6e 79 20 6f 75 74 73 74 61 an up any outsta
3bbc0 6e 64 69 6e 67 20 72 65 73 6f 75 72 63 65 73 20 nding resources
3bbd0 62 65 66 6f 72 65 20 70 72 6f 63 65 73 73 20 73 before process s
3bbe0 68 75 74 64 6f 77 6e 2c 20 69 66 20 72 65 71 75 hutdown, if requ
3bbf0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ired..**.** The
3bc00 78 43 72 65 61 74 65 28 29 20 6d 65 74 68 6f 64 xCreate() method
3bc10 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 is used to cons
3bc20 74 72 75 63 74 20 61 20 6e 65 77 20 63 61 63 68 truct a new cach
3bc30 65 20 69 6e 73 74 61 6e 63 65 2e 20 54 68 65 0a e instance. The.
3bc40 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 ** first paramet
3bc50 65 72 2c 20 73 7a 50 61 67 65 2c 20 69 73 20 74 er, szPage, is t
3bc60 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 he size in bytes
3bc70 20 6f 66 20 74 68 65 20 70 61 67 65 73 20 74 68 of the pages th
3bc80 61 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c at must.** be al
3bc90 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65 20 63 located by the c
3bca0 61 63 68 65 2e 20 73 7a 50 61 67 65 20 77 69 6c ache. szPage wil
3bcb0 6c 20 6e 6f 74 20 62 65 20 61 20 70 6f 77 65 72 l not be a power
3bcc0 20 6f 66 20 74 77 6f 2e 20 54 68 65 0a 2a 2a 20 of two. The.**
3bcd0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c second argument,
3bce0 20 62 50 75 72 67 65 61 62 6c 65 2c 20 69 73 20 bPurgeable, is
3bcf0 74 72 75 65 20 69 66 20 74 68 65 20 63 61 63 68 true if the cach
3bd00 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 e being created
3bd10 77 69 6c 6c 0a 2a 2a 20 62 65 20 75 73 65 64 20 will.** be used
3bd20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 to cache databas
3bd30 65 20 70 61 67 65 73 20 72 65 61 64 20 66 72 6f e pages read fro
3bd40 6d 20 61 20 66 69 6c 65 20 73 74 6f 72 65 64 20 m a file stored
3bd50 6f 6e 20 64 69 73 6b 2c 20 6f 72 0a 2a 2a 20 66 on disk, or.** f
3bd60 61 6c 73 65 20 69 66 20 69 74 20 69 73 20 75 73 alse if it is us
3bd70 65 64 20 66 6f 72 20 61 6e 20 69 6e 2d 6d 65 6d ed for an in-mem
3bd80 6f 72 79 20 64 61 74 61 62 61 73 65 2e 20 54 68 ory database. Th
3bd90 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e e cache implemen
3bda0 74 61 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 6e tation.** does n
3bdb0 6f 74 20 68 61 76 65 20 74 6f 20 64 6f 20 61 6e ot have to do an
3bdc0 79 74 68 69 6e 67 20 73 70 65 63 69 61 6c 20 62 ything special b
3bdd0 61 73 65 64 20 6f 6e 20 74 68 65 20 76 61 6c 75 ased on the valu
3bde0 65 20 6f 66 20 62 50 75 72 67 65 61 62 6c 65 2c e of bPurgeable,
3bdf0 0a 2a 2a 20 69 74 20 69 73 20 70 75 72 65 6c 79 .** it is purely
3be00 20 61 64 76 69 73 6f 72 79 2e 20 0a 2a 2a 0a 2a advisory. .**.*
3be10 2a 20 54 68 65 20 78 43 61 63 68 65 73 69 7a 65 * The xCachesize
3be20 28 29 20 6d 65 74 68 6f 64 20 6d 61 79 20 62 65 () method may be
3be30 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 74 called at any t
3be40 69 6d 65 20 62 79 20 53 51 4c 69 74 65 20 74 6f ime by SQLite to
3be50 20 73 65 74 20 74 68 65 0a 2a 2a 20 73 75 67 67 set the.** sugg
3be60 65 73 74 65 64 20 6d 61 78 69 6d 75 6d 20 63 61 ested maximum ca
3be70 63 68 65 2d 73 69 7a 65 20 28 6e 75 6d 62 65 72 che-size (number
3be80 20 6f 66 20 70 61 67 65 73 20 73 74 6f 72 65 64 of pages stored
3be90 20 62 79 29 20 74 68 65 20 63 61 63 68 65 0a 2a by) the cache.*
3bea0 2a 20 69 6e 73 74 61 6e 63 65 20 70 61 73 73 65 * instance passe
3beb0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 d as the first a
3bec0 72 67 75 6d 65 6e 74 2e 20 54 68 69 73 20 69 73 rgument. This is
3bed0 20 74 68 65 20 76 61 6c 75 65 20 63 6f 6e 66 69 the value confi
3bee0 67 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 gured using.** t
3bef0 68 65 20 53 51 4c 69 74 65 20 22 5b 50 52 41 47 he SQLite "[PRAG
3bf00 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 22 20 MA cache_size]"
3bf10 63 6f 6d 6d 61 6e 64 2e 20 41 73 20 77 69 74 68 command. As with
3bf20 20 74 68 65 20 62 50 75 72 67 65 61 62 6c 65 20 the bPurgeable
3bf30 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 74 68 parameter,.** th
3bf40 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
3bf50 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64 is not required
3bf60 20 74 6f 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 to do anything
3bf70 73 70 65 63 69 61 6c 20 77 69 74 68 20 74 68 69 special with thi
3bf80 73 0a 2a 2a 20 76 61 6c 75 65 2c 20 69 74 20 69 s.** value, it i
3bf90 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e s advisory only.
3bfa0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 50 61 67 65 .**.** The xPage
3bfb0 63 6f 75 6e 74 28 29 20 6d 65 74 68 6f 64 20 73 count() method s
3bfc0 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 hould return the
3bfd0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 number of pages
3bfe0 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 73 74 currently.** st
3bff0 6f 72 65 64 20 69 6e 20 74 68 65 20 63 61 63 68 ored in the cach
3c000 65 20 73 75 70 70 6c 69 65 64 20 61 73 20 61 6e e supplied as an
3c010 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a argument..** .*
3c020 2a 20 54 68 65 20 78 46 65 74 63 68 28 29 20 6d * The xFetch() m
3c030 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 74 6f ethod is used to
3c040 20 66 65 74 63 68 20 61 20 70 61 67 65 20 61 6e fetch a page an
3c050 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 d return a point
3c060 65 72 20 74 6f 20 69 74 2e 20 0a 2a 2a 20 41 20 er to it. .** A
3c070 27 70 61 67 65 27 2c 20 69 6e 20 74 68 69 73 20 'page', in this
3c080 63 6f 6e 74 65 78 74 2c 20 69 73 20 61 20 62 75 context, is a bu
3c090 66 66 65 72 20 6f 66 20 73 7a 50 61 67 65 20 62 ffer of szPage b
3c0a0 79 74 65 73 20 61 6c 69 67 6e 65 64 20 61 74 20 ytes aligned at
3c0b0 61 6e 0a 2a 2a 20 38 2d 62 79 74 65 20 62 6f 75 an.** 8-byte bou
3c0c0 6e 64 61 72 79 2e 20 54 68 65 20 70 61 67 65 20 ndary. The page
3c0d0 74 6f 20 62 65 20 66 65 74 63 68 65 64 20 69 73 to be fetched is
3c0e0 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 determined by t
3c0f0 68 65 20 6b 65 79 2e 20 54 68 65 0a 2a 2a 20 6d he key. The.** m
3c100 69 6d 69 6d 75 6d 20 6b 65 79 20 76 61 6c 75 65 imimum key value
3c110 20 69 73 20 31 2e 20 41 66 74 65 72 20 69 74 20 is 1. After it
3c120 68 61 73 20 62 65 65 6e 20 72 65 74 72 69 65 76 has been retriev
3c130 65 64 20 75 73 69 6e 67 20 78 46 65 74 63 68 2c ed using xFetch,
3c140 20 74 68 65 20 70 61 67 65 20 0a 2a 2a 20 69 73 the page .** is
3c150 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 considered to b
3c160 65 20 70 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 e pinned..**.**
3c170 49 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 If the requested
3c180 20 70 61 67 65 20 69 73 20 61 6c 72 65 61 64 79 page is already
3c190 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 in the page cac
3c1a0 68 65 2c 20 74 68 65 6e 20 61 20 70 6f 69 6e 74 he, then a point
3c1b0 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 61 63 er to.** the cac
3c1c0 68 65 64 20 62 75 66 66 65 72 20 73 68 6f 75 6c hed buffer shoul
3c1d0 64 20 62 65 20 72 65 74 75 72 6e 65 64 20 77 69 d be returned wi
3c1e0 74 68 20 69 74 73 20 63 6f 6e 74 65 6e 74 73 20 th its contents
3c1f0 69 6e 74 61 63 74 2e 20 49 66 20 74 68 65 0a 2a intact. If the.*
3c200 2a 20 70 61 67 65 20 69 73 20 6e 6f 74 20 61 6c * page is not al
3c210 72 65 61 64 79 20 69 6e 20 74 68 65 20 63 61 63 ready in the cac
3c220 68 65 2c 20 74 68 65 6e 20 74 68 65 20 65 78 70 he, then the exp
3c230 65 63 74 65 64 20 62 65 68 61 76 69 6f 75 72 20 ected behaviour
3c240 6f 66 20 74 68 65 0a 2a 2a 20 63 61 63 68 65 20 of the.** cache
3c250 69 73 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 is determined by
3c260 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 the value of th
3c270 65 20 63 72 65 61 74 65 46 6c 61 67 20 70 61 72 e createFlag par
3c280 61 6d 65 74 65 72 20 70 61 73 73 65 64 0a 2a 2a ameter passed.**
3c290 20 74 6f 20 78 46 65 74 63 68 2c 20 61 63 63 6f to xFetch, acco
3c2a0 72 64 69 6e 67 20 74 6f 20 74 68 65 20 66 6f 6c rding to the fol
3c2b0 6c 6f 77 69 6e 67 20 74 61 62 6c 65 3a 0a 2a 2a lowing table:.**
3c2c0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 .** <table borde
3c2d0 72 3d 31 20 77 69 64 74 68 3d 38 35 25 20 61 6c r=1 width=85% al
3c2e0 69 67 6e 3d 63 65 6e 74 65 72 3e 0a 2a 2a 20 20 ign=center>.**
3c2f0 20 3c 74 72 3e 3c 74 68 3e 63 72 65 61 74 65 46 <tr><th>createF
3c300 6c 61 67 3c 74 68 3e 45 78 70 65 63 74 65 64 20 lag<th>Expected
3c310 42 65 68 61 76 69 6f 75 72 0a 2a 2a 20 20 20 3c Behaviour.** <
3c320 74 72 3e 3c 74 64 3e 30 3c 74 64 3e 4e 55 4c 4c tr><td>0<td>NULL
3c330 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 should be retur
3c340 6e 65 64 2e 20 4e 6f 20 6e 65 77 20 63 61 63 68 ned. No new cach
3c350 65 20 65 6e 74 72 79 20 69 73 20 63 72 65 61 74 e entry is creat
3c360 65 64 2e 0a 2a 2a 20 20 20 3c 74 72 3e 3c 74 64 ed..** <tr><td
3c370 3e 31 3c 74 64 3e 49 66 20 63 72 65 61 74 65 46 >1<td>If createF
3c380 6c 61 67 20 69 73 20 73 65 74 20 74 6f 20 31 2c lag is set to 1,
3c390 20 74 68 69 73 20 69 6e 64 69 63 61 74 65 73 20 this indicates
3c3a0 74 68 61 74 20 0a 2a 2a 20 20 20 20 20 20 20 20 that .**
3c3b0 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 69 SQLite i
3c3c0 73 20 68 6f 6c 64 69 6e 67 20 70 69 6e 6e 65 64 s holding pinned
3c3d0 20 70 61 67 65 73 20 74 68 61 74 20 63 61 6e 20 pages that can
3c3e0 62 65 20 75 6e 70 69 6e 6e 65 64 0a 2a 2a 20 20 be unpinned.**
3c3f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 62 79 by
3c400 20 77 72 69 74 69 6e 67 20 74 68 65 69 72 20 63 writing their c
3c410 6f 6e 74 65 6e 74 73 20 74 6f 20 74 68 65 20 64 ontents to the d
3c420 61 74 61 62 61 73 65 20 66 69 6c 65 20 28 61 0a atabase file (a.
3c430 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 **
3c440 20 20 72 65 6c 61 74 69 76 65 6c 79 20 65 78 70 relatively exp
3c450 65 6e 73 69 76 65 20 6f 70 65 72 61 74 69 6f 6e ensive operation
3c460 29 2e 20 49 6e 20 74 68 69 73 20 73 69 74 75 61 ). In this situa
3c470 74 69 6f 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 tion the.**
3c480 20 20 20 20 20 20 20 20 20 20 20 63 61 63 68 65 cache
3c490 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
3c4a0 68 61 73 20 74 77 6f 20 63 68 6f 69 63 65 73 3a has two choices:
3c4b0 20 69 74 20 63 61 6e 20 72 65 74 75 72 6e 20 4e it can return N
3c4c0 55 4c 4c 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ULL,.**
3c4d0 20 20 20 20 20 20 20 69 6e 20 77 68 69 63 68 20 in which
3c4e0 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c case SQLite will
3c4f0 20 61 74 74 65 6d 70 74 20 74 6f 20 75 6e 70 69 attempt to unpi
3c500 6e 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 0a 2a n one or more .*
3c510 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *
3c520 20 70 61 67 65 73 20 62 65 66 6f 72 65 20 72 65 pages before re
3c530 2d 72 65 71 75 65 73 74 69 6e 67 20 74 68 65 20 -requesting the
3c540 73 61 6d 65 20 70 61 67 65 2c 20 6f 72 20 69 74 same page, or it
3c550 20 63 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 can.**
3c560 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 20 allocate
3c570 61 20 6e 65 77 20 70 61 67 65 20 61 6e 64 20 72 a new page and r
3c580 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 eturn a pointer
3c590 74 6f 20 69 74 2e 20 49 66 20 61 20 6e 65 77 0a to it. If a new.
3c5a0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 **
3c5b0 20 20 70 61 67 65 20 69 73 20 61 6c 6c 6f 63 61 page is alloca
3c5c0 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 69 ted, then the fi
3c5d0 72 73 74 20 73 69 7a 65 6f 66 28 76 6f 69 64 2a rst sizeof(void*
3c5e0 29 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 ) bytes of.**
3c5f0 20 20 20 20 20 20 20 20 20 20 20 20 20 69 74 20 it
3c600 28 61 74 20 6c 65 61 73 74 29 20 6d 75 73 74 20 (at least) must
3c610 62 65 20 7a 65 72 6f 65 64 20 62 65 66 6f 72 65 be zeroed before
3c620 20 69 74 20 69 73 20 72 65 74 75 72 6e 65 64 2e it is returned.
3c630 0a 2a 2a 20 20 20 3c 74 72 3e 3c 74 64 3e 32 3c .** <tr><td>2<
3c640 74 64 3e 49 66 20 63 72 65 61 74 65 46 6c 61 67 td>If createFlag
3c650 20 69 73 20 73 65 74 20 74 6f 20 32 2c 20 74 68 is set to 2, th
3c660 65 6e 20 53 51 4c 69 74 65 20 69 73 20 6e 6f 74 en SQLite is not
3c670 20 68 6f 6c 64 69 6e 67 20 61 6e 79 0a 2a 2a 20 holding any.**
3c680 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 70 p
3c690 69 6e 6e 65 64 20 70 61 67 65 73 20 61 73 73 6f inned pages asso
3c6a0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
3c6b0 73 70 65 63 69 66 69 63 20 63 61 63 68 65 20 70 specific cache p
3c6c0 61 73 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 assed.**
3c6d0 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20 66 as the f
3c6e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
3c6f0 20 78 46 65 74 63 68 28 29 20 74 68 61 74 20 63 xFetch() that c
3c700 61 6e 20 62 65 20 75 6e 70 69 6e 6e 65 64 2e 20 an be unpinned.
3c710 54 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 The.**
3c720 20 20 20 20 20 20 63 61 63 68 65 20 69 6d 70 6c cache impl
3c730 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c ementation shoul
3c740 64 20 61 74 74 65 6d 70 74 20 74 6f 20 61 6c 6c d attempt to all
3c750 6f 63 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20 ocate a new.**
3c760 20 20 20 20 20 20 20 20 20 20 20 20 20 20 63 61 ca
3c770 63 68 65 20 65 6e 74 72 79 20 61 6e 64 20 72 65 che entry and re
3c780 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 turn a pointer t
3c790 6f 20 69 74 2e 20 41 67 61 69 6e 2c 20 74 68 65 o it. Again, the
3c7a0 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 first.**
3c7b0 20 20 20 20 20 20 20 20 20 73 69 7a 65 6f 66 28 sizeof(
3c7c0 76 6f 69 64 2a 29 20 62 79 74 65 73 20 6f 66 20 void*) bytes of
3c7d0 74 68 65 20 70 61 67 65 20 73 68 6f 75 6c 64 20 the page should
3c7e0 62 65 20 7a 65 72 6f 65 64 20 62 65 66 6f 72 65 be zeroed before
3c7f0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 .**
3c800 20 20 20 20 69 74 20 69 73 20 72 65 74 75 72 6e it is return
3c810 65 64 2e 20 49 66 20 74 68 65 20 78 46 65 74 63 ed. If the xFetc
3c820 68 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 h() method retur
3c830 6e 73 20 4e 55 4c 4c 20 77 68 65 6e 20 0a 2a 2a ns NULL when .**
3c840 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3c850 63 72 65 61 74 65 46 6c 61 67 3d 3d 32 2c 20 53 createFlag==2, S
3c860 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 QLite assumes th
3c870 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f at a memory allo
3c880 63 61 74 69 6f 6e 20 0a 2a 2a 20 20 20 20 20 20 cation .**
3c890 20 20 20 20 20 20 20 20 20 20 66 61 69 6c 65 64 failed
3c8a0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 53 51 4c and returns SQL
3c8b0 49 54 45 5f 4e 4f 4d 45 4d 20 74 6f 20 74 68 65 ITE_NOMEM to the
3c8c0 20 75 73 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c user..** </tabl
3c8d0 65 3e 0a 2a 2a 0a 2a 2a 20 78 55 6e 70 69 6e 28 e>.**.** xUnpin(
3c8e0 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 53 ) is called by S
3c8f0 51 4c 69 74 65 20 77 69 74 68 20 61 20 70 6f 69 QLite with a poi
3c900 6e 74 65 72 20 74 6f 20 61 20 63 75 72 72 65 6e nter to a curren
3c910 74 6c 79 20 70 69 6e 6e 65 64 20 70 61 67 65 0a tly pinned page.
3c920 2a 2a 20 61 73 20 69 74 73 20 73 65 63 6f 6e 64 ** as its second
3c930 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 74 68 argument. If th
3c940 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
3c950 72 2c 20 64 69 73 63 61 72 64 2c 20 69 73 20 6e r, discard, is n
3c960 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e on-zero,.** then
3c970 20 74 68 65 20 70 61 67 65 20 73 68 6f 75 6c 64 the page should
3c980 20 62 65 20 65 76 69 63 74 65 64 20 66 72 6f 6d be evicted from
3c990 20 74 68 65 20 63 61 63 68 65 2e 20 49 6e 20 74 the cache. In t
3c9a0 68 69 73 20 63 61 73 65 20 53 51 4c 69 74 65 20 his case SQLite
3c9b0 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 .** assumes that
3c9c0 20 74 68 65 20 6e 65 78 74 20 74 69 6d 65 20 74 the next time t
3c9d0 68 65 20 70 61 67 65 20 69 73 20 72 65 74 72 69 he page is retri
3c9e0 65 76 65 64 20 66 72 6f 6d 20 74 68 65 20 63 61 eved from the ca
3c9f0 63 68 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 che using.** the
3ca00 20 78 46 65 74 63 68 28 29 20 6d 65 74 68 6f 64 xFetch() method
3ca10 2c 20 69 74 20 77 69 6c 6c 20 62 65 20 7a 65 72 , it will be zer
3ca20 6f 65 64 2e 20 49 66 20 74 68 65 20 64 69 73 63 oed. If the disc
3ca30 61 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ard parameter is
3ca40 0a 2a 2a 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 .** zero, then t
3ca50 68 65 20 70 61 67 65 20 69 73 20 63 6f 6e 73 69 he page is consi
3ca60 64 65 72 65 64 20 74 6f 20 62 65 20 75 6e 70 69 dered to be unpi
3ca70 6e 6e 65 64 2e 20 54 68 65 20 63 61 63 68 65 20 nned. The cache
3ca80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a implementation.*
3ca90 2a 20 6d 61 79 20 63 68 6f 6f 73 65 20 74 6f 20 * may choose to
3caa0 72 65 63 6c 61 69 6d 20 28 66 72 65 65 20 6f 72 reclaim (free or
3cab0 20 72 65 63 79 63 6c 65 29 20 75 6e 70 69 6e 6e recycle) unpinn
3cac0 65 64 20 70 61 67 65 73 20 61 74 20 61 6e 79 20 ed pages at any
3cad0 74 69 6d 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 time..** SQLite
3cae0 61 73 73 75 6d 65 73 20 74 68 61 74 20 6e 65 78 assumes that nex
3caf0 74 20 74 69 6d 65 20 74 68 65 20 70 61 67 65 20 t time the page
3cb00 69 73 20 72 65 74 72 69 65 76 65 64 20 66 72 6f is retrieved fro
3cb10 6d 20 74 68 65 20 63 61 63 68 65 0a 2a 2a 20 69 m the cache.** i
3cb20 74 20 77 69 6c 6c 20 65 69 74 68 65 72 20 62 65 t will either be
3cb30 20 7a 65 72 6f 65 64 2c 20 6f 72 20 63 6f 6e 74 zeroed, or cont
3cb40 61 69 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 ain the same dat
3cb50 61 20 74 68 61 74 20 69 74 20 64 69 64 20 77 68 a that it did wh
3cb60 65 6e 20 69 74 0a 2a 2a 20 77 61 73 20 75 6e 70 en it.** was unp
3cb70 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 inned..**.** The
3cb80 20 63 61 63 68 65 20 69 73 20 6e 6f 74 20 72 65 cache is not re
3cb90 71 75 69 72 65 64 20 74 6f 20 70 65 72 66 6f 72 quired to perfor
3cba0 6d 20 61 6e 79 20 72 65 66 65 72 65 6e 63 65 20 m any reference
3cbb0 63 6f 75 6e 74 69 6e 67 2e 20 41 20 73 69 6e 67 counting. A sing
3cbc0 6c 65 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 le .** call to x
3cbd0 55 6e 70 69 6e 28 29 20 75 6e 70 69 6e 73 20 74 Unpin() unpins t
3cbe0 68 65 20 70 61 67 65 20 72 65 67 61 72 64 6c 65 he page regardle
3cbf0 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 ss of the number
3cc00 20 6f 66 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 of prior calls
3cc10 0a 2a 2a 20 74 6f 20 78 46 65 74 63 68 28 29 2e .** to xFetch().
3cc20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 65 6b 65 .**.** The xReke
3cc30 79 28 29 20 6d 65 74 68 6f 64 20 69 73 20 75 73 y() method is us
3cc40 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 ed to change the
3cc50 20 6b 65 79 20 76 61 6c 75 65 20 61 73 73 6f 63 key value assoc
3cc60 69 61 74 65 64 20 77 69 74 68 20 74 68 65 0a 2a iated with the.*
3cc70 2a 20 70 61 67 65 20 70 61 73 73 65 64 20 61 73 * page passed as
3cc80 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
3cc90 6d 65 6e 74 20 66 72 6f 6d 20 6f 6c 64 4b 65 79 ment from oldKey
3cca0 20 74 6f 20 6e 65 77 4b 65 79 2e 20 49 66 20 74 to newKey. If t
3ccb0 68 65 20 63 61 63 68 65 0a 2a 2a 20 70 72 65 76 he cache.** prev
3ccc0 69 6f 75 73 6c 79 20 63 6f 6e 74 61 69 6e 73 20 iously contains
3ccd0 61 6e 20 65 6e 74 72 79 20 61 73 73 6f 63 69 61 an entry associa
3cce0 74 65 64 20 77 69 74 68 20 6e 65 77 4b 65 79 2c ted with newKey,
3ccf0 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a it should be.**
3cd00 20 64 69 73 63 61 72 64 65 64 2e 20 41 6e 79 20 discarded. Any
3cd10 70 72 69 6f 72 20 63 61 63 68 65 20 65 6e 74 72 prior cache entr
3cd20 79 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 y associated wit
3cd30 68 20 6e 65 77 4b 65 79 20 69 73 20 67 75 61 72 h newKey is guar
3cd40 61 6e 74 65 65 64 20 6e 6f 74 0a 2a 2a 20 74 6f anteed not.** to
3cd50 20 62 65 20 70 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a be pinned..**.*
3cd60 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 63 61 * When SQLite ca
3cd70 6c 6c 73 20 74 68 65 20 78 54 72 75 6e 63 61 74 lls the xTruncat
3cd80 65 28 29 20 6d 65 74 68 6f 64 2c 20 74 68 65 20 e() method, the
3cd90 63 61 63 68 65 20 6d 75 73 74 20 64 69 73 63 61 cache must disca
3cda0 72 64 20 61 6c 6c 0a 2a 2a 20 65 78 69 73 74 69 rd all.** existi
3cdb0 6e 67 20 63 61 63 68 65 20 65 6e 74 72 69 65 73 ng cache entries
3cdc0 20 77 69 74 68 20 70 61 67 65 20 6e 75 6d 62 65 with page numbe
3cdd0 72 73 20 28 6b 65 79 73 29 20 67 72 65 61 74 65 rs (keys) greate
3cde0 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 0a r than or equal.
3cdf0 2a 2a 20 74 6f 20 74 68 65 20 76 61 6c 75 65 20 ** to the value
3ce00 6f 66 20 74 68 65 20 69 4c 69 6d 69 74 20 70 61 of the iLimit pa
3ce10 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 rameter passed t
3ce20 6f 20 78 54 72 75 6e 63 61 74 65 28 29 2e 20 49 o xTruncate(). I
3ce30 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 f any.** of thes
3ce40 65 20 70 61 67 65 73 20 61 72 65 20 70 69 6e 6e e pages are pinn
3ce50 65 64 2c 20 74 68 65 79 20 61 72 65 20 69 6d 70 ed, they are imp
3ce60 6c 69 63 69 74 6c 79 20 75 6e 70 69 6e 6e 65 64 licitly unpinned
3ce70 2c 20 6d 65 61 6e 69 6e 67 20 74 68 61 74 0a 2a , meaning that.*
3ce80 2a 20 74 68 65 79 20 63 61 6e 20 62 65 20 73 61 * they can be sa
3ce90 66 65 6c 79 20 64 69 73 63 61 72 64 65 64 2e 0a fely discarded..
3cea0 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 73 74 72 **.** The xDestr
3ceb0 6f 79 28 29 20 6d 65 74 68 6f 64 20 69 73 20 75 oy() method is u
3cec0 73 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 sed to delete a
3ced0 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 cache allocated
3cee0 62 79 20 78 43 72 65 61 74 65 28 29 2e 0a 2a 2a by xCreate()..**
3cef0 20 41 6c 6c 20 72 65 73 6f 75 72 63 65 73 20 61 All resources a
3cf00 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
3cf10 68 65 20 73 70 65 63 69 66 69 65 64 20 63 61 63 he specified cac
3cf20 68 65 20 73 68 6f 75 6c 64 20 62 65 20 66 72 65 he should be fre
3cf30 65 64 2e 20 41 66 74 65 72 0a 2a 2a 20 63 61 6c ed. After.** cal
3cf40 6c 69 6e 67 20 74 68 65 20 78 44 65 73 74 72 6f ling the xDestro
3cf50 79 28 29 20 6d 65 74 68 6f 64 2c 20 53 51 4c 69 y() method, SQLi
3cf60 74 65 20 63 6f 6e 73 69 64 65 72 73 20 74 68 65 te considers the
3cf70 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 [sqlite3_pcache
3cf80 2a 5d 0a 2a 2a 20 68 61 6e 64 6c 65 20 69 6e 76 *].** handle inv
3cf90 61 6c 69 64 2c 20 61 6e 64 20 77 69 6c 6c 20 6e alid, and will n
3cfa0 6f 74 20 75 73 65 20 69 74 20 77 69 74 68 20 61 ot use it with a
3cfb0 6e 79 20 6f 74 68 65 72 20 73 71 6c 69 74 65 33 ny other sqlite3
3cfc0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 0a _pcache_methods.
3cfd0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f ** functions..*/
3cfe0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
3cff0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d sqlite3_pcache_m
3d000 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 70 ethods sqlite3_p
3d010 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3b 0a 73 cache_methods;.s
3d020 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 70 63 truct sqlite3_pc
3d030 61 63 68 65 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 ache_methods {.
3d040 20 76 6f 69 64 20 2a 70 41 72 67 3b 0a 20 20 69 void *pArg;. i
3d050 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 nt (*xInit)(void
3d060 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 *);. void (*xSh
3d070 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 0a utdown)(void*);.
3d080 20 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 sqlite3_pcache
3d090 20 2a 28 2a 78 43 72 65 61 74 65 29 28 69 6e 74 *(*xCreate)(int
3d0a0 20 73 7a 50 61 67 65 2c 20 69 6e 74 20 62 50 75 szPage, int bPu
3d0b0 72 67 65 61 62 6c 65 29 3b 0a 20 20 76 6f 69 64 rgeable);. void
3d0c0 20 28 2a 78 43 61 63 68 65 73 69 7a 65 29 28 73 (*xCachesize)(s
3d0d0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 qlite3_pcache*,
3d0e0 69 6e 74 20 6e 43 61 63 68 65 73 69 7a 65 29 3b int nCachesize);
3d0f0 0a 20 20 69 6e 74 20 28 2a 78 50 61 67 65 63 6f . int (*xPageco
3d100 75 6e 74 29 28 73 71 6c 69 74 65 33 5f 70 63 61 unt)(sqlite3_pca
3d110 63 68 65 2a 29 3b 0a 20 20 76 6f 69 64 20 2a 28 che*);. void *(
3d120 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 *xFetch)(sqlite3
3d130 5f 70 63 61 63 68 65 2a 2c 20 75 6e 73 69 67 6e _pcache*, unsign
3d140 65 64 20 6b 65 79 2c 20 69 6e 74 20 63 72 65 61 ed key, int crea
3d150 74 65 46 6c 61 67 29 3b 0a 20 20 76 6f 69 64 20 teFlag);. void
3d160 28 2a 78 55 6e 70 69 6e 29 28 73 71 6c 69 74 65 (*xUnpin)(sqlite
3d170 33 5f 70 63 61 63 68 65 2a 2c 20 76 6f 69 64 2a 3_pcache*, void*
3d180 2c 20 69 6e 74 20 64 69 73 63 61 72 64 29 3b 0a , int discard);.
3d190 20 20 76 6f 69 64 20 28 2a 78 52 65 6b 65 79 29 void (*xRekey)
3d1a0 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a (sqlite3_pcache*
3d1b0 2c 20 76 6f 69 64 2a 2c 20 75 6e 73 69 67 6e 65 , void*, unsigne
3d1c0 64 20 6f 6c 64 4b 65 79 2c 20 75 6e 73 69 67 6e d oldKey, unsign
3d1d0 65 64 20 6e 65 77 4b 65 79 29 3b 0a 20 20 76 6f ed newKey);. vo
3d1e0 69 64 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 id (*xTruncate)(
3d1f0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a 2c sqlite3_pcache*,
3d200 20 75 6e 73 69 67 6e 65 64 20 69 4c 69 6d 69 74 unsigned iLimit
3d210 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 65 73 );. void (*xDes
3d220 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 70 63 troy)(sqlite3_pc
3d230 61 63 68 65 2a 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a ache*);.};../*.*
3d240 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 6c 69 * CAPI3REF: Onli
3d250 6e 65 20 42 61 63 6b 75 70 20 4f 62 6a 65 63 74 ne Backup Object
3d260 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
3d270 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
3d280 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 e3_backup object
3d290 20 72 65 63 6f 72 64 73 20 73 74 61 74 65 20 69 records state i
3d2a0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 nformation about
3d2b0 20 61 6e 20 6f 6e 67 6f 69 6e 67 0a 2a 2a 20 6f an ongoing.** o
3d2c0 6e 6c 69 6e 65 20 62 61 63 6b 75 70 20 6f 70 65 nline backup ope
3d2d0 72 61 74 69 6f 6e 2e 20 20 54 68 65 20 73 71 6c ration. The sql
3d2e0 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 ite3_backup obje
3d2f0 63 74 20 69 73 20 63 72 65 61 74 65 64 20 62 79 ct is created by
3d300 0a 2a 2a 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 .** a call to [s
3d310 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e qlite3_backup_in
3d320 69 74 28 29 5d 20 61 6e 64 20 69 73 20 64 65 73 it()] and is des
3d330 74 72 6f 79 65 64 20 62 79 20 61 20 63 61 6c 6c troyed by a call
3d340 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
3d350 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 5d backup_finish()]
3d360 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f ..**.** See Also
3d370 3a 20 5b 55 73 69 6e 67 20 74 68 65 20 53 51 4c : [Using the SQL
3d380 69 74 65 20 4f 6e 6c 69 6e 65 20 42 61 63 6b 75 ite Online Backu
3d390 70 20 41 50 49 5d 0a 2a 2f 0a 74 79 70 65 64 65 p API].*/.typede
3d3a0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
3d3b0 5f 62 61 63 6b 75 70 20 73 71 6c 69 74 65 33 5f _backup sqlite3_
3d3c0 62 61 63 6b 75 70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 backup;../*.** C
3d3d0 41 50 49 33 52 45 46 3a 20 4f 6e 6c 69 6e 65 20 API3REF: Online
3d3e0 42 61 63 6b 75 70 20 41 50 49 2e 0a 2a 2a 20 45 Backup API..** E
3d3f0 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
3d400 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 75 73 * This API is us
3d410 65 64 20 74 6f 20 6f 76 65 72 77 72 69 74 65 20 ed to overwrite
3d420 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 the contents of
3d430 6f 6e 65 20 64 61 74 61 62 61 73 65 20 77 69 74 one database wit
3d440 68 20 74 68 61 74 0a 2a 2a 20 6f 66 20 61 6e 6f h that.** of ano
3d450 74 68 65 72 2e 20 49 74 20 69 73 20 75 73 65 66 ther. It is usef
3d460 75 6c 20 65 69 74 68 65 72 20 66 6f 72 20 63 72 ul either for cr
3d470 65 61 74 69 6e 67 20 62 61 63 6b 75 70 73 20 6f eating backups o
3d480 66 20 64 61 74 61 62 61 73 65 73 20 6f 72 0a 2a f databases or.*
3d490 2a 20 66 6f 72 20 63 6f 70 79 69 6e 67 20 69 6e * for copying in
3d4a0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 -memory database
3d4b0 73 20 74 6f 20 6f 72 20 66 72 6f 6d 20 70 65 72 s to or from per
3d4c0 73 69 73 74 65 6e 74 20 66 69 6c 65 73 2e 20 0a sistent files. .
3d4d0 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 **.** See Also:
3d4e0 5b 55 73 69 6e 67 20 74 68 65 20 53 51 4c 69 74 [Using the SQLit
3d4f0 65 20 4f 6e 6c 69 6e 65 20 42 61 63 6b 75 70 20 e Online Backup
3d500 41 50 49 5d 0a 2a 2a 0a 2a 2a 20 45 78 63 6c 75 API].**.** Exclu
3d510 73 69 76 65 20 61 63 63 65 73 73 20 69 73 20 72 sive access is r
3d520 65 71 75 69 72 65 64 20 74 6f 20 74 68 65 20 64 equired to the d
3d530 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 estination datab
3d540 61 73 65 20 66 6f 72 20 74 68 65 20 0a 2a 2a 20 ase for the .**
3d550 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 duration of the
3d560 6f 70 65 72 61 74 69 6f 6e 2e 20 48 6f 77 65 76 operation. Howev
3d570 65 72 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 er the source da
3d580 74 61 62 61 73 65 20 69 73 20 6f 6e 6c 79 0a 2a tabase is only.*
3d590 2a 20 72 65 61 64 2d 6c 6f 63 6b 65 64 20 77 68 * read-locked wh
3d5a0 69 6c 65 20 69 74 20 69 73 20 61 63 74 75 61 6c ile it is actual
3d5b0 6c 79 20 62 65 69 6e 67 20 72 65 61 64 2c 20 69 ly being read, i
3d5c0 74 20 69 73 20 6e 6f 74 20 6c 6f 63 6b 65 64 0a t is not locked.
3d5d0 2a 2a 20 63 6f 6e 74 69 6e 75 6f 75 73 6c 79 20 ** continuously
3d5e0 66 6f 72 20 74 68 65 20 65 6e 74 69 72 65 20 6f for the entire o
3d5f0 70 65 72 61 74 69 6f 6e 2e 20 54 68 75 73 2c 20 peration. Thus,
3d600 74 68 65 20 62 61 63 6b 75 70 20 6d 61 79 20 62 the backup may b
3d610 65 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 6f e.** performed o
3d620 6e 20 61 20 6c 69 76 65 20 64 61 74 61 62 61 73 n a live databas
3d630 65 20 77 69 74 68 6f 75 74 20 70 72 65 76 65 6e e without preven
3d640 74 69 6e 67 20 6f 74 68 65 72 20 75 73 65 72 73 ting other users
3d650 20 66 72 6f 6d 0a 2a 2a 20 77 72 69 74 69 6e 67 from.** writing
3d660 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 to the database
3d670 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64 for an extended
3d680 20 70 65 72 69 6f 64 20 6f 66 20 74 69 6d 65 2e period of time.
3d690 0a 2a 2a 20 0a 2a 2a 20 54 6f 20 70 65 72 66 6f .** .** To perfo
3d6a0 72 6d 20 61 20 62 61 63 6b 75 70 20 6f 70 65 72 rm a backup oper
3d6b0 61 74 69 6f 6e 3a 20 0a 2a 2a 20 20 20 3c 6f 6c ation: .** <ol
3d6c0 3e 0a 2a 2a 20 20 20 20 20 3c 6c 69 3e 3c 62 3e >.** <li><b>
3d6d0 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 sqlite3_backup_i
3d6e0 6e 69 74 28 29 3c 2f 62 3e 20 69 73 20 63 61 6c nit()</b> is cal
3d6f0 6c 65 64 20 6f 6e 63 65 20 74 6f 20 69 6e 69 74 led once to init
3d700 69 61 6c 69 7a 65 20 74 68 65 0a 2a 2a 20 20 20 ialize the.**
3d710 20 20 20 20 20 20 62 61 63 6b 75 70 2c 20 0a 2a backup, .*
3d720 2a 20 20 20 20 20 3c 6c 69 3e 3c 62 3e 73 71 6c * <li><b>sql
3d730 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3d740 28 29 3c 2f 62 3e 20 69 73 20 63 61 6c 6c 65 64 ()</b> is called
3d750 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
3d760 65 73 20 74 6f 20 74 72 61 6e 73 66 65 72 20 0a es to transfer .
3d770 2a 2a 20 20 20 20 20 20 20 20 20 74 68 65 20 64 ** the d
3d780 61 74 61 20 62 65 74 77 65 65 6e 20 74 68 65 20 ata between the
3d790 74 77 6f 20 64 61 74 61 62 61 73 65 73 2c 20 61 two databases, a
3d7a0 6e 64 20 66 69 6e 61 6c 6c 79 0a 2a 2a 20 20 20 nd finally.**
3d7b0 20 20 3c 6c 69 3e 3c 62 3e 73 71 6c 69 74 65 33 <li><b>sqlite3
3d7c0 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 _backup_finish()
3d7d0 3c 2f 62 3e 20 69 73 20 63 61 6c 6c 65 64 20 74 </b> is called t
3d7e0 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c 20 72 65 o release all re
3d7f0 73 6f 75 72 63 65 73 20 0a 2a 2a 20 20 20 20 20 sources .**
3d800 20 20 20 20 61 73 73 6f 63 69 61 74 65 64 20 77 associated w
3d810 69 74 68 20 74 68 65 20 62 61 63 6b 75 70 20 6f ith the backup o
3d820 70 65 72 61 74 69 6f 6e 2e 20 0a 2a 2a 20 20 20 peration. .**
3d830 3c 2f 6f 6c 3e 0a 2a 2a 20 54 68 65 72 65 20 73 </ol>.** There s
3d840 68 6f 75 6c 64 20 62 65 20 65 78 61 63 74 6c 79 hould be exactly
3d850 20 6f 6e 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c one call to sql
3d860 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 ite3_backup_fini
3d870 73 68 28 29 20 66 6f 72 20 65 61 63 68 0a 2a 2a sh() for each.**
3d880 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
3d890 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b to sqlite3_back
3d8a0 75 70 5f 69 6e 69 74 28 29 2e 0a 2a 2a 0a 2a 2a up_init()..**.**
3d8b0 20 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b <b>sqlite3_back
3d8c0 75 70 5f 69 6e 69 74 28 29 3c 2f 62 3e 0a 2a 2a up_init()</b>.**
3d8d0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 77 .** The first tw
3d8e0 6f 20 61 72 67 75 6d 65 6e 74 73 20 70 61 73 73 o arguments pass
3d8f0 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 ed to [sqlite3_b
3d900 61 63 6b 75 70 5f 69 6e 69 74 28 29 5d 20 61 72 ackup_init()] ar
3d910 65 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a e the database.*
3d920 2a 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61 * handle associa
3d930 74 65 64 20 77 69 74 68 20 74 68 65 20 64 65 73 ted with the des
3d940 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 tination databas
3d950 65 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 e and the databa
3d960 73 65 20 6e 61 6d 65 20 0a 2a 2a 20 75 73 65 64 se name .** used
3d970 20 74 6f 20 61 74 74 61 63 68 20 74 68 65 20 64 to attach the d
3d980 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 estination datab
3d990 61 73 65 20 74 6f 20 74 68 65 20 68 61 6e 64 6c ase to the handl
3d9a0 65 2e 20 54 68 65 20 64 61 74 61 62 61 73 65 20 e. The database
3d9b0 6e 61 6d 65 0a 2a 2a 20 69 73 20 22 6d 61 69 6e name.** is "main
3d9c0 22 20 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 " for the main d
3d9d0 61 74 61 62 61 73 65 2c 20 22 74 65 6d 70 22 20 atabase, "temp"
3d9e0 66 6f 72 20 74 68 65 20 74 65 6d 70 6f 72 61 72 for the temporar
3d9f0 79 20 64 61 74 61 62 61 73 65 2c 20 6f 72 0a 2a y database, or.*
3da00 2a 20 74 68 65 20 6e 61 6d 65 20 73 70 65 63 69 * the name speci
3da10 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 fied as part of
3da20 74 68 65 20 5b 41 54 54 41 43 48 5d 20 73 74 61 the [ATTACH] sta
3da30 74 65 6d 65 6e 74 20 69 66 20 74 68 65 20 64 65 tement if the de
3da40 73 74 69 6e 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 stination is.**
3da50 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61 an attached data
3da60 62 61 73 65 2e 20 54 68 65 20 74 68 69 72 64 20 base. The third
3da70 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d and fourth argum
3da80 65 6e 74 73 20 70 61 73 73 65 64 20 74 6f 20 0a ents passed to .
3da90 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ** sqlite3_backu
3daa0 70 5f 69 6e 69 74 28 29 20 69 64 65 6e 74 69 66 p_init() identif
3dab0 79 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 y the [database
3dac0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 61 connection].** a
3dad0 6e 64 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 nd database name
3dae0 20 75 73 65 64 0a 2a 2a 20 74 6f 20 61 63 63 65 used.** to acce
3daf0 73 73 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 ss the source da
3db00 74 61 62 61 73 65 2e 20 54 68 65 20 76 61 6c 75 tabase. The valu
3db10 65 73 20 70 61 73 73 65 64 20 66 6f 72 20 74 68 es passed for th
3db20 65 20 73 6f 75 72 63 65 20 61 6e 64 20 0a 2a 2a e source and .**
3db30 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 5b 64 61 destination [da
3db40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3db50 6e 5d 20 70 61 72 61 6d 65 74 65 72 73 20 6d 75 n] parameters mu
3db60 73 74 20 6e 6f 74 20 62 65 20 74 68 65 20 73 61 st not be the sa
3db70 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 me..**.** If an
3db80 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 69 74 error occurs wit
3db90 68 69 6e 20 73 71 6c 69 74 65 33 5f 62 61 63 6b hin sqlite3_back
3dba0 75 70 5f 69 6e 69 74 28 29 2c 20 74 68 65 6e 20 up_init(), then
3dbb0 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 NULL is returned
3dbc0 0a 2a 2a 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 .** and an error
3dbd0 20 63 6f 64 65 20 61 6e 64 20 65 72 72 6f 72 20 code and error
3dbe0 6d 65 73 73 61 67 65 20 77 72 69 74 74 65 6e 20 message written
3dbf0 69 6e 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 into the [databa
3dc00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 0a se connection] .
3dc10 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 ** passed as the
3dc20 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e first argument.
3dc30 20 54 68 65 79 20 6d 61 79 20 62 65 20 72 65 74 They may be ret
3dc40 72 69 65 76 65 64 20 75 73 69 6e 67 20 74 68 65 rieved using the
3dc50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 .** [sqlite3_err
3dc60 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 code()], [sqlite
3dc70 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 3_errmsg()], and
3dc80 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
3dc90 31 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73 2e 16()] functions.
3dca0 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 69 .** Otherwise, i
3dcb0 66 20 73 75 63 63 65 73 73 66 75 6c 2c 20 61 20 f successful, a
3dcc0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 pointer to an [s
3dcd0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f qlite3_backup] o
3dce0 62 6a 65 63 74 20 69 73 0a 2a 2a 20 72 65 74 75 bject is.** retu
3dcf0 72 6e 65 64 2e 20 54 68 69 73 20 70 6f 69 6e 74 rned. This point
3dd00 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 77 er may be used w
3dd10 69 74 68 20 74 68 65 20 73 71 6c 69 74 65 33 5f ith the sqlite3_
3dd20 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 61 6e backup_step() an
3dd30 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 d.** sqlite3_bac
3dd40 6b 75 70 5f 66 69 6e 69 73 68 28 29 20 66 75 6e kup_finish() fun
3dd50 63 74 69 6f 6e 73 20 74 6f 20 70 65 72 66 6f 72 ctions to perfor
3dd60 6d 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 m the specified
3dd70 62 61 63 6b 75 70 20 0a 2a 2a 20 6f 70 65 72 61 backup .** opera
3dd80 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 73 tion..**.** <b>s
3dd90 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3dda0 65 70 28 29 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 46 ep()</b>.**.** F
3ddb0 75 6e 63 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 unction [sqlite3
3ddc0 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 5d 20 _backup_step()]
3ddd0 69 73 20 75 73 65 64 20 74 6f 20 63 6f 70 79 20 is used to copy
3dde0 75 70 20 74 6f 20 6e 50 61 67 65 20 70 61 67 65 up to nPage page
3ddf0 73 20 62 65 74 77 65 65 6e 20 0a 2a 2a 20 74 68 s between .** th
3de00 65 20 73 6f 75 72 63 65 20 61 6e 64 20 64 65 73 e source and des
3de10 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 tination databas
3de20 65 73 2c 20 77 68 65 72 65 20 6e 50 61 67 65 20 es, where nPage
3de30 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 is the value of
3de40 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 the .** second p
3de50 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 arameter passed
3de60 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 to sqlite3_backu
3de70 70 5f 73 74 65 70 28 29 2e 20 49 66 20 6e 50 61 p_step(). If nPa
3de80 67 65 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 ge is a negative
3de90 0a 2a 2a 20 76 61 6c 75 65 2c 20 61 6c 6c 20 72 .** value, all r
3dea0 65 6d 61 69 6e 69 6e 67 20 73 6f 75 72 63 65 20 emaining source
3deb0 70 61 67 65 73 20 61 72 65 20 63 6f 70 69 65 64 pages are copied
3dec0 2e 20 49 66 20 74 68 65 20 72 65 71 75 69 72 65 . If the require
3ded0 64 20 70 61 67 65 73 20 61 72 65 20 0a 2a 2a 20 d pages are .**
3dee0 73 75 63 63 65 73 66 75 6c 6c 79 20 63 6f 70 69 succesfully copi
3def0 65 64 2c 20 62 75 74 20 74 68 65 72 65 20 61 72 ed, but there ar
3df00 65 20 73 74 69 6c 6c 20 6d 6f 72 65 20 70 61 67 e still more pag
3df10 65 73 20 74 6f 20 63 6f 70 79 20 62 65 66 6f 72 es to copy befor
3df20 65 20 74 68 65 20 0a 2a 2a 20 62 61 63 6b 75 70 e the .** backup
3df30 20 69 73 20 63 6f 6d 70 6c 65 74 65 2c 20 69 74 is complete, it
3df40 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
3df50 5f 4f 4b 5d 2e 20 49 66 20 6e 6f 20 65 72 72 6f _OK]. If no erro
3df60 72 20 6f 63 63 75 72 65 64 20 61 6e 64 20 74 68 r occured and th
3df70 65 72 65 20 0a 2a 2a 20 61 72 65 20 6e 6f 20 6d ere .** are no m
3df80 6f 72 65 20 70 61 67 65 73 20 74 6f 20 63 6f 70 ore pages to cop
3df90 79 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f y, then [SQLITE_
3dfa0 44 4f 4e 45 5d 20 69 73 20 72 65 74 75 72 6e 65 DONE] is returne
3dfb0 64 2e 20 49 66 20 61 6e 20 65 72 72 6f 72 20 0a d. If an error .
3dfc0 2a 2a 20 6f 63 63 75 72 73 2c 20 74 68 65 6e 20 ** occurs, then
3dfd0 61 6e 20 53 51 4c 69 74 65 20 65 72 72 6f 72 20 an SQLite error
3dfe0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 code is returned
3dff0 2e 20 41 73 20 77 65 6c 6c 20 61 73 20 5b 53 51 . As well as [SQ
3e000 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 0a 2a 2a 20 LITE_OK] and.**
3e010 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 61 [SQLITE_DONE], a
3e020 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
3e030 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 6d _backup_step() m
3e040 61 79 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ay return [SQLIT
3e050 45 5f 52 45 41 44 4f 4e 4c 59 5d 2c 0a 2a 2a 20 E_READONLY],.**
3e060 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 [SQLITE_NOMEM],
3e070 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 5b [SQLITE_BUSY], [
3e080 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5d 2c 20 SQLITE_LOCKED],
3e090 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 or an.** [SQLITE
3e0a0 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 7c 20 _IOERR_ACCESS |
3e0b0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 58 58 58 SQLITE_IOERR_XXX
3e0c0 5d 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 ] extended error
3e0d0 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 code..**.** As
3e0e0 77 65 6c 6c 20 61 73 20 74 68 65 20 63 61 73 65 well as the case
3e0f0 20 77 68 65 72 65 20 74 68 65 20 64 65 73 74 69 where the desti
3e100 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 20 nation database
3e110 66 69 6c 65 20 77 61 73 20 6f 70 65 6e 65 64 20 file was opened
3e120 66 6f 72 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 for.** read-only
3e130 20 61 63 63 65 73 73 2c 20 73 71 6c 69 74 65 33 access, sqlite3
3e140 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 6d _backup_step() m
3e150 61 79 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ay return [SQLIT
3e160 45 5f 52 45 41 44 4f 4e 4c 59 5d 20 69 66 0a 2a E_READONLY] if.*
3e170 2a 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f * the destinatio
3e180 6e 20 69 73 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 n is an in-memor
3e190 79 20 64 61 74 61 62 61 73 65 20 77 69 74 68 20 y database with
3e1a0 61 20 64 69 66 66 65 72 65 6e 74 20 70 61 67 65 a different page
3e1b0 20 73 69 7a 65 0a 2a 2a 20 66 72 6f 6d 20 74 68 size.** from th
3e1c0 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 73 e source databas
3e1d0 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 e..**.** If sqli
3e1e0 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
3e1f0 29 20 63 61 6e 6e 6f 74 20 6f 62 74 61 69 6e 20 ) cannot obtain
3e200 61 20 72 65 71 75 69 72 65 64 20 66 69 6c 65 2d a required file-
3e210 73 79 73 74 65 6d 20 6c 6f 63 6b 2c 20 74 68 65 system lock, the
3e220 6e 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 n.** the [sqlite
3e230 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 3_busy_handler |
3e240 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 66 75 busy-handler fu
3e250 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 69 6e nction].** is in
3e260 76 6f 6b 65 64 20 28 69 66 20 6f 6e 65 20 69 73 voked (if one is
3e270 20 73 70 65 63 69 66 69 65 64 29 2e 20 49 66 20 specified). If
3e280 74 68 65 20 0a 2a 2a 20 62 75 73 79 2d 68 61 6e the .** busy-han
3e290 64 6c 65 72 20 72 65 74 75 72 6e 73 20 6e 6f 6e dler returns non
3e2a0 2d 7a 65 72 6f 20 62 65 66 6f 72 65 20 74 68 65 -zero before the
3e2b0 20 6c 6f 63 6b 20 69 73 20 61 76 61 69 6c 61 62 lock is availab
3e2c0 6c 65 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 53 51 le, then .** [SQ
3e2d0 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 LITE_BUSY] is re
3e2e0 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 turned to the ca
3e2f0 6c 6c 65 72 2e 20 49 6e 20 74 68 69 73 20 63 61 ller. In this ca
3e300 73 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a se the call to.*
3e310 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 * sqlite3_backup
3e320 5f 73 74 65 70 28 29 20 63 61 6e 20 62 65 20 72 _step() can be r
3e330 65 74 72 69 65 64 20 6c 61 74 65 72 2e 20 49 66 etried later. If
3e340 20 74 68 65 20 73 6f 75 72 63 65 0a 2a 2a 20 5b the source.** [
3e350 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3e360 69 6f 6e 5d 0a 2a 2a 20 69 73 20 62 65 69 6e 67 ion].** is being
3e370 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 74 used to write t
3e380 6f 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 o the source dat
3e390 61 62 61 73 65 20 77 68 65 6e 20 73 71 6c 69 74 abase when sqlit
3e3a0 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 e3_backup_step()
3e3b0 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 .** is called, t
3e3c0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b hen [SQLITE_LOCK
3e3d0 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 ED] is returned
3e3e0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 20 41 67 61 immediately. Aga
3e3f0 69 6e 2c 20 69 6e 20 74 68 69 73 0a 2a 2a 20 63 in, in this.** c
3e400 61 73 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 ase the call to
3e410 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 sqlite3_backup_s
3e420 74 65 70 28 29 20 63 61 6e 20 62 65 20 72 65 74 tep() can be ret
3e430 72 69 65 64 20 6c 61 74 65 72 20 6f 6e 2e 20 49 ried later on. I
3e440 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 f.** [SQLITE_IOE
3e450 52 52 5f 41 43 43 45 53 53 20 7c 20 53 51 4c 49 RR_ACCESS | SQLI
3e460 54 45 5f 49 4f 45 52 52 5f 58 58 58 5d 2c 20 5b TE_IOERR_XXX], [
3e470 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 6f SQLITE_NOMEM], o
3e480 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 45 41 r.** [SQLITE_REA
3e490 44 4f 4e 4c 59 5d 20 69 73 20 72 65 74 75 72 6e DONLY] is return
3e4a0 65 64 2c 20 74 68 65 6e 20 0a 2a 2a 20 74 68 65 ed, then .** the
3e4b0 72 65 20 69 73 20 6e 6f 20 70 6f 69 6e 74 20 69 re is no point i
3e4c0 6e 20 72 65 74 72 79 69 6e 67 20 74 68 65 20 63 n retrying the c
3e4d0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 all to sqlite3_b
3e4e0 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 20 54 68 ackup_step(). Th
3e4f0 65 73 65 20 0a 2a 2a 20 65 72 72 6f 72 73 20 61 ese .** errors a
3e500 72 65 20 63 6f 6e 73 69 64 65 72 65 64 20 66 61 re considered fa
3e510 74 61 6c 2e 20 41 74 20 74 68 69 73 20 70 6f 69 tal. At this poi
3e520 6e 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 nt the applicati
3e530 6f 6e 20 6d 75 73 74 20 61 63 63 65 70 74 20 0a on must accept .
3e540 2a 2a 20 74 68 61 74 20 74 68 65 20 62 61 63 6b ** that the back
3e550 75 70 20 6f 70 65 72 61 74 69 6f 6e 20 68 61 73 up operation has
3e560 20 66 61 69 6c 65 64 20 61 6e 64 20 70 61 73 73 failed and pass
3e570 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 the backup oper
3e580 61 74 69 6f 6e 20 68 61 6e 64 6c 65 20 0a 2a 2a ation handle .**
3e590 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
3e5a0 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 20 backup_finish()
3e5b0 74 6f 20 72 65 6c 65 61 73 65 20 61 73 73 6f 63 to release assoc
3e5c0 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 2e iated resources.
3e5d0 0a 2a 2a 0a 2a 2a 20 46 6f 6c 6c 6f 77 69 6e 67 .**.** Following
3e5e0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 the first call
3e5f0 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 to sqlite3_backu
3e600 70 5f 73 74 65 70 28 29 2c 20 61 6e 20 65 78 63 p_step(), an exc
3e610 6c 75 73 69 76 65 20 6c 6f 63 6b 20 69 73 0a 2a lusive lock is.*
3e620 2a 20 6f 62 74 61 69 6e 65 64 20 6f 6e 20 74 68 * obtained on th
3e630 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 66 69 e destination fi
3e640 6c 65 2e 20 49 74 20 69 73 20 6e 6f 74 20 72 65 le. It is not re
3e650 6c 65 61 73 65 64 20 75 6e 74 69 6c 20 65 69 74 leased until eit
3e660 68 65 72 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f her .** sqlite3_
3e670 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 20 backup_finish()
3e680 69 73 20 63 61 6c 6c 65 64 20 6f 72 20 74 68 65 is called or the
3e690 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f backup operatio
3e6a0 6e 20 69 73 20 63 6f 6d 70 6c 65 74 65 20 0a 2a n is complete .*
3e6b0 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 62 61 * and sqlite3_ba
3e6c0 63 6b 75 70 5f 73 74 65 70 28 29 20 72 65 74 75 ckup_step() retu
3e6d0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 rns [SQLITE_DONE
3e6e0 5d 2e 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c ]. Additionally,
3e6f0 20 65 61 63 68 20 74 69 6d 65 20 0a 2a 2a 20 61 each time .** a
3e700 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
3e710 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 69 _backup_step() i
3e720 73 20 6d 61 64 65 20 61 20 5b 73 68 61 72 65 64 s made a [shared
3e730 20 6c 6f 63 6b 5d 20 69 73 20 6f 62 74 61 69 6e lock] is obtain
3e740 65 64 20 6f 6e 0a 2a 2a 20 74 68 65 20 73 6f 75 ed on.** the sou
3e750 72 63 65 20 64 61 74 61 62 61 73 65 20 66 69 6c rce database fil
3e760 65 2e 20 54 68 69 73 20 6c 6f 63 6b 20 69 73 20 e. This lock is
3e770 72 65 6c 65 61 73 65 64 20 62 65 66 6f 72 65 20 released before
3e780 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 the.** sqlite3_b
3e790 61 63 6b 75 70 5f 73 74 65 70 28 29 20 63 61 6c ackup_step() cal
3e7a0 6c 20 72 65 74 75 72 6e 73 2e 20 42 65 63 61 75 l returns. Becau
3e7b0 73 65 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 se the source da
3e7c0 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a tabase is not.**
3e7d0 20 6c 6f 63 6b 65 64 20 62 65 74 77 65 65 6e 20 locked between
3e7e0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
3e7f0 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2c 20 _backup_step(),
3e800 69 74 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 it may be modifi
3e810 65 64 20 6d 69 64 2d 77 61 79 0a 2a 2a 20 74 68 ed mid-way.** th
3e820 72 6f 75 67 68 20 74 68 65 20 62 61 63 6b 75 70 rough the backup
3e830 20 70 72 6f 63 65 64 75 72 65 2e 20 49 66 20 74 procedure. If t
3e840 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 he source databa
3e850 73 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62 se is modified b
3e860 79 20 61 6e 0a 2a 2a 20 65 78 74 65 72 6e 61 6c y an.** external
3e870 20 70 72 6f 63 65 73 73 20 6f 72 20 76 69 61 20 process or via
3e880 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 a database conne
3e890 63 74 69 6f 6e 20 6f 74 68 65 72 20 74 68 61 6e ction other than
3e8a0 20 74 68 65 20 6f 6e 65 20 62 65 69 6e 67 0a 2a the one being.*
3e8b0 2a 20 75 73 65 64 20 62 79 20 74 68 65 20 62 61 * used by the ba
3e8c0 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 2c 20 ckup operation,
3e8d0 74 68 65 6e 20 74 68 65 20 62 61 63 6b 75 70 20 then the backup
3e8e0 77 69 6c 6c 20 62 65 20 74 72 61 6e 73 70 61 72 will be transpar
3e8f0 65 6e 74 6c 79 0a 2a 2a 20 72 65 73 74 61 72 74 ently.** restart
3e900 65 64 20 62 79 20 74 68 65 20 6e 65 78 74 20 63 ed by the next c
3e910 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 all to sqlite3_b
3e920 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 20 49 66 ackup_step(). If
3e930 20 74 68 65 20 73 6f 75 72 63 65 20 0a 2a 2a 20 the source .**
3e940 64 61 74 61 62 61 73 65 20 69 73 20 6d 6f 64 69 database is modi
3e950 66 69 65 64 20 62 79 20 74 68 65 20 75 73 69 6e fied by the usin
3e960 67 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 g the same datab
3e970 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 ase connection a
3e980 73 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 s is used.** by
3e990 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 the backup opera
3e9a0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 62 tion, then the b
3e9b0 61 63 6b 75 70 20 64 61 74 61 62 61 73 65 20 69 ackup database i
3e9c0 73 20 74 72 61 6e 73 70 61 72 65 6e 74 6c 79 20 s transparently
3e9d0 0a 2a 2a 20 75 70 64 61 74 65 64 20 61 74 20 74 .** updated at t
3e9e0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a he same time..**
3e9f0 0a 2a 2a 20 3c 62 3e 73 71 6c 69 74 65 33 5f 62 .** <b>sqlite3_b
3ea00 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 3c 2f ackup_finish()</
3ea10 62 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 63 65 20 73 71 b>.**.** Once sq
3ea20 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3ea30 70 28 29 20 68 61 73 20 72 65 74 75 72 6e 65 64 p() has returned
3ea40 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 [SQLITE_DONE],
3ea50 6f 72 20 77 68 65 6e 20 74 68 65 20 0a 2a 2a 20 or when the .**
3ea60 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 69 73 68 application wish
3ea70 65 73 20 74 6f 20 61 62 61 6e 64 6f 6e 20 74 68 es to abandon th
3ea80 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 e backup operati
3ea90 6f 6e 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 on, the [sqlite3
3eaa0 5f 62 61 63 6b 75 70 5d 0a 2a 2a 20 6f 62 6a 65 _backup].** obje
3eab0 63 74 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 ct should be pas
3eac0 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 sed to sqlite3_b
3ead0 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 2e 20 ackup_finish().
3eae0 54 68 69 73 20 72 65 6c 65 61 73 65 73 20 61 6c This releases al
3eaf0 6c 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61 l.** resources a
3eb00 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
3eb10 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 he backup operat
3eb20 69 6f 6e 2e 20 49 66 20 73 71 6c 69 74 65 33 5f ion. If sqlite3_
3eb30 62 61 63 6b 75 70 5f 73 74 65 70 28 29 0a 2a 2a backup_step().**
3eb40 20 68 61 73 20 6e 6f 74 20 79 65 74 20 72 65 74 has not yet ret
3eb50 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f urned [SQLITE_DO
3eb60 4e 45 5d 2c 20 74 68 65 6e 20 61 6e 79 20 61 63 NE], then any ac
3eb70 74 69 76 65 20 77 72 69 74 65 2d 74 72 61 6e 73 tive write-trans
3eb80 61 63 74 69 6f 6e 20 6f 6e 20 74 68 65 0a 2a 2a action on the.**
3eb90 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 destination dat
3eba0 61 62 61 73 65 20 69 73 20 72 6f 6c 6c 65 64 20 abase is rolled
3ebb0 62 61 63 6b 2e 20 54 68 65 20 5b 73 71 6c 69 74 back. The [sqlit
3ebc0 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 e3_backup] objec
3ebd0 74 20 69 73 20 69 6e 76 61 6c 69 64 0a 2a 2a 20 t is invalid.**
3ebe0 61 6e 64 20 6d 61 79 20 6e 6f 74 20 62 65 20 75 and may not be u
3ebf0 73 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 sed following a
3ec00 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
3ec10 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 2e backup_finish().
3ec20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 .**.** The value
3ec30 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
3ec40 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 ite3_backup_fini
3ec50 73 68 20 69 73 20 5b 53 51 4c 49 54 45 5f 4f 4b sh is [SQLITE_OK
3ec60 5d 20 69 66 20 6e 6f 20 65 72 72 6f 72 0a 2a 2a ] if no error.**
3ec70 20 6f 63 63 75 72 72 65 64 2c 20 72 65 67 61 72 occurred, regar
3ec80 64 6c 65 73 73 20 6f 72 20 77 68 65 74 68 65 72 dless or whether
3ec90 20 6f 72 20 6e 6f 74 20 73 71 6c 69 74 65 33 5f or not sqlite3_
3eca0 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 77 61 backup_step() wa
3ecb0 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 61 20 73 75 s called.** a su
3ecc0 66 66 69 63 69 65 6e 74 20 6e 75 6d 62 65 72 20 fficient number
3ecd0 6f 66 20 74 69 6d 65 73 20 74 6f 20 63 6f 6d 70 of times to comp
3ece0 6c 65 74 65 20 74 68 65 20 62 61 63 6b 75 70 20 lete the backup
3ecf0 6f 70 65 72 61 74 69 6f 6e 2e 20 4f 72 2c 20 69 operation. Or, i
3ed00 66 0a 2a 2a 20 61 6e 20 6f 75 74 2d 6f 66 2d 6d f.** an out-of-m
3ed10 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 20 emory condition
3ed20 6f 72 20 49 4f 20 65 72 72 6f 72 20 6f 63 63 75 or IO error occu
3ed30 72 65 64 20 64 75 72 69 6e 67 20 61 20 63 61 6c red during a cal
3ed40 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f l to.** sqlite3_
3ed50 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 74 68 backup_step() th
3ed60 65 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d en [SQLITE_NOMEM
3ed70 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 ] or an.** [SQLI
3ed80 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 TE_IOERR_ACCESS
3ed90 7c 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 58 | SQLITE_IOERR_X
3eda0 58 58 5d 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a XX] error code.*
3edb0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 * is returned. I
3edc0 6e 20 74 68 69 73 20 63 61 73 65 20 74 68 65 20 n this case the
3edd0 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 error code and a
3ede0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 n error message
3edf0 61 72 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 74 are.** written t
3ee00 6f 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f o the destinatio
3ee10 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
3ee20 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 41 ection]..**.** A
3ee30 20 72 65 74 75 72 6e 20 6f 66 20 5b 53 51 4c 49 return of [SQLI
3ee40 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c TE_BUSY] or [SQL
3ee50 49 54 45 5f 4c 4f 43 4b 45 44 5d 20 66 72 6f 6d ITE_LOCKED] from
3ee60 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3ee70 73 74 65 70 28 29 20 69 73 0a 2a 2a 20 6e 6f 74 step() is.** not
3ee80 20 61 20 70 65 72 6d 61 6e 65 6e 74 20 65 72 72 a permanent err
3ee90 6f 72 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 or and does not
3eea0 61 66 66 65 63 74 20 74 68 65 20 72 65 74 75 72 affect the retur
3eeb0 6e 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 73 71 n value of.** sq
3eec0 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e lite3_backup_fin
3eed0 69 73 68 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e ish()..**.** <b>
3eee0 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 72 sqlite3_backup_r
3eef0 65 6d 61 69 6e 69 6e 67 28 29 2c 20 73 71 6c 69 emaining(), sqli
3ef00 74 65 33 5f 62 61 63 6b 75 70 5f 70 61 67 65 63 te3_backup_pagec
3ef10 6f 75 6e 74 28 29 3c 2f 62 3e 0a 2a 2a 0a 2a 2a ount()</b>.**.**
3ef20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 Each call to sq
3ef30 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3ef40 70 28 29 20 73 65 74 73 20 74 77 6f 20 76 61 6c p() sets two val
3ef50 75 65 73 20 73 74 6f 72 65 64 20 69 6e 74 65 72 ues stored inter
3ef60 6e 61 6c 6c 79 0a 2a 2a 20 62 79 20 61 6e 20 5b nally.** by an [
3ef70 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 sqlite3_backup]
3ef80 6f 62 6a 65 63 74 2e 20 54 68 65 20 6e 75 6d 62 object. The numb
3ef90 65 72 20 6f 66 20 70 61 67 65 73 20 73 74 69 6c er of pages stil
3efa0 6c 20 74 6f 20 62 65 20 62 61 63 6b 65 64 0a 2a l to be backed.*
3efb0 2a 20 75 70 2c 20 77 68 69 63 68 20 6d 61 79 20 * up, which may
3efc0 62 65 20 71 75 65 72 69 65 64 20 62 79 20 73 71 be queried by sq
3efd0 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 72 65 6d lite3_backup_rem
3efe0 61 69 6e 69 6e 67 28 29 2c 20 61 6e 64 20 74 68 aining(), and th
3eff0 65 20 74 6f 74 61 6c 0a 2a 2a 20 6e 75 6d 62 65 e total.** numbe
3f000 72 20 6f 66 20 70 61 67 65 73 20 69 6e 20 74 68 r of pages in th
3f010 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 73 e source databas
3f020 65 20 66 69 6c 65 2c 20 77 68 69 63 68 20 6d 61 e file, which ma
3f030 79 20 62 65 20 71 75 65 72 69 65 64 20 62 79 0a y be queried by.
3f040 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ** sqlite3_backu
3f050 70 5f 70 61 67 65 63 6f 75 6e 74 28 29 2e 0a 2a p_pagecount()..*
3f060 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 20 *.** The values
3f070 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 returned by thes
3f080 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 e functions are
3f090 6f 6e 6c 79 20 75 70 64 61 74 65 64 20 62 79 0a only updated by.
3f0a0 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ** sqlite3_backu
3f0b0 70 5f 73 74 65 70 28 29 2e 20 49 66 20 74 68 65 p_step(). If the
3f0c0 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 source database
3f0d0 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 75 72 is modified dur
3f0e0 69 6e 67 20 61 20 62 61 63 6b 75 70 0a 2a 2a 20 ing a backup.**
3f0f0 6f 70 65 72 61 74 69 6f 6e 2c 20 74 68 65 6e 20 operation, then
3f100 74 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 6e the values are n
3f110 6f 74 20 75 70 64 61 74 65 64 20 74 6f 20 61 63 ot updated to ac
3f120 63 6f 75 6e 74 20 66 6f 72 20 61 6e 79 20 65 78 count for any ex
3f130 74 72 61 0a 2a 2a 20 70 61 67 65 73 20 74 68 61 tra.** pages tha
3f140 74 20 6e 65 65 64 20 74 6f 20 62 65 20 75 70 64 t need to be upd
3f150 61 74 65 64 20 6f 72 20 74 68 65 20 73 69 7a 65 ated or the size
3f160 20 6f 66 20 74 68 65 20 73 6f 75 72 63 65 20 64 of the source d
3f170 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 atabase file.**
3f180 63 68 61 6e 67 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 changing..**.**
3f190 3c 62 3e 43 6f 6e 63 75 72 72 65 6e 74 20 55 73 <b>Concurrent Us
3f1a0 61 67 65 20 6f 66 20 44 61 74 61 62 61 73 65 20 age of Database
3f1b0 48 61 6e 64 6c 65 73 3c 2f 62 3e 0a 2a 2a 0a 2a Handles</b>.**.*
3f1c0 2a 20 54 68 65 20 73 6f 75 72 63 65 20 5b 64 61 * The source [da
3f1d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3f1e0 6e 5d 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 n] may be used b
3f1f0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f y the applicatio
3f200 6e 20 66 6f 72 20 6f 74 68 65 72 0a 2a 2a 20 70 n for other.** p
3f210 75 72 70 6f 73 65 73 20 77 68 69 6c 65 20 61 20 urposes while a
3f220 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e backup operation
3f230 20 69 73 20 75 6e 64 65 72 77 61 79 20 6f 72 20 is underway or
3f240 62 65 69 6e 67 20 69 6e 69 74 69 61 6c 69 7a 65 being initialize
3f250 64 2e 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 d..** If SQLite
3f260 69 73 20 63 6f 6d 70 69 6c 65 64 20 61 6e 64 20 is compiled and
3f270 63 6f 6e 66 69 67 75 72 65 64 20 74 6f 20 73 75 configured to su
3f280 70 70 6f 72 74 20 74 68 72 65 61 64 73 61 66 65 pport threadsafe
3f290 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e database.** con
3f2a0 6e 65 63 74 69 6f 6e 73 2c 20 74 68 65 6e 20 74 nections, then t
3f2b0 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 he source databa
3f2c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 61 se connection ma
3f2d0 79 20 62 65 20 75 73 65 64 20 63 6f 6e 63 75 72 y be used concur
3f2e0 72 65 6e 74 6c 79 0a 2a 2a 20 66 72 6f 6d 20 77 rently.** from w
3f2f0 69 74 68 69 6e 20 6f 74 68 65 72 20 74 68 72 65 ithin other thre
3f300 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 48 6f 77 65 76 ads..**.** Howev
3f310 65 72 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 er, the applicat
3f320 69 6f 6e 20 6d 75 73 74 20 67 75 61 72 61 6e 74 ion must guarant
3f330 65 65 20 74 68 61 74 20 74 68 65 20 64 65 73 74 ee that the dest
3f340 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 ination database
3f350 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 .** connection h
3f360 61 6e 64 6c 65 20 69 73 20 6e 6f 74 20 70 61 73 andle is not pas
3f370 73 65 64 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 sed to any other
3f380 20 41 50 49 20 28 62 79 20 61 6e 79 20 74 68 72 API (by any thr
3f390 65 61 64 29 20 61 66 74 65 72 20 0a 2a 2a 20 73 ead) after .** s
3f3a0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e qlite3_backup_in
3f3b0 69 74 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 it() is called a
3f3c0 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 63 6f nd before the co
3f3d0 72 72 65 73 70 6f 6e 64 69 6e 67 20 63 61 6c 6c rresponding call
3f3e0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 to.** sqlite3_b
3f3f0 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 2e 20 ackup_finish().
3f400 55 6e 66 6f 72 74 75 6e 61 74 65 6c 79 20 53 51 Unfortunately SQ
3f410 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 63 75 Lite does not cu
3f420 72 72 65 6e 74 6c 79 20 63 68 65 63 6b 0a 2a 2a rrently check.**
3f430 20 66 6f 72 20 74 68 69 73 2c 20 69 66 20 74 68 for this, if th
3f440 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f e application do
3f450 65 73 20 75 73 65 20 74 68 65 20 64 65 73 74 69 es use the desti
3f460 6e 61 74 69 6f 6e 20 5b 64 61 74 61 62 61 73 65 nation [database
3f470 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 connection].**
3f480 66 6f 72 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 for some other p
3f490 75 72 70 6f 73 65 20 64 75 72 69 6e 67 20 61 20 urpose during a
3f4a0 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e backup operation
3f4b0 2c 20 74 68 69 6e 67 73 20 6d 61 79 20 61 70 70 , things may app
3f4c0 65 61 72 20 74 6f 0a 2a 2a 20 77 6f 72 6b 20 63 ear to.** work c
3f4d0 6f 72 72 65 63 74 6c 79 20 62 75 74 20 69 6e 20 orrectly but in
3f4e0 66 61 63 74 20 62 65 20 73 75 62 74 6c 79 20 6d fact be subtly m
3f4f0 61 6c 66 75 6e 63 74 69 6f 6e 69 6e 67 2e 20 20 alfunctioning.
3f500 55 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 Use of the.** de
3f510 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 stination databa
3f520 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 se connection wh
3f530 69 6c 65 20 61 20 62 61 63 6b 75 70 20 69 73 20 ile a backup is
3f540 69 6e 20 70 72 6f 67 72 65 73 73 20 6d 69 67 68 in progress migh
3f550 74 0a 2a 2a 20 61 6c 73 6f 20 63 61 75 73 65 20 t.** also cause
3f560 61 20 6d 75 74 65 78 20 64 65 61 64 6c 6f 63 6b a mutex deadlock
3f570 2e 0a 2a 2a 0a 2a 2a 20 46 75 72 74 68 65 72 6d ..**.** Furtherm
3f580 6f 72 65 2c 20 69 66 20 72 75 6e 6e 69 6e 67 20 ore, if running
3f590 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 in [shared cache
3f5a0 20 6d 6f 64 65 5d 2c 20 74 68 65 20 61 70 70 6c mode], the appl
3f5b0 69 63 61 74 69 6f 6e 20 6d 75 73 74 0a 2a 2a 20 ication must.**
3f5c0 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 guarantee that t
3f5d0 68 65 20 73 68 61 72 65 64 20 63 61 63 68 65 20 he shared cache
3f5e0 75 73 65 64 20 62 79 20 74 68 65 20 64 65 73 74 used by the dest
3f5f0 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 ination database
3f600 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 63 63 65 73 .** is not acces
3f610 73 65 64 20 77 68 69 6c 65 20 74 68 65 20 62 61 sed while the ba
3f620 63 6b 75 70 20 69 73 20 72 75 6e 6e 69 6e 67 2e ckup is running.
3f630 20 49 6e 20 70 72 61 63 74 69 63 65 20 74 68 69 In practice thi
3f640 73 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 s means.** that
3f650 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
3f660 6d 75 73 74 20 67 75 61 72 61 6e 74 65 65 20 74 must guarantee t
3f670 68 61 74 20 74 68 65 20 66 69 6c 65 2d 73 79 73 hat the file-sys
3f680 74 65 6d 20 66 69 6c 65 20 62 65 69 6e 67 20 0a tem file being .
3f690 2a 2a 20 62 61 63 6b 65 64 20 75 70 20 74 6f 20 ** backed up to
3f6a0 69 73 20 6e 6f 74 20 61 63 63 65 73 73 65 64 20 is not accessed
3f6b0 62 79 20 61 6e 79 20 63 6f 6e 6e 65 63 74 69 6f by any connectio
3f6c0 6e 20 77 69 74 68 69 6e 20 74 68 65 20 70 72 6f n within the pro
3f6d0 63 65 73 73 2c 0a 2a 2a 20 6e 6f 74 20 6a 75 73 cess,.** not jus
3f6e0 74 20 74 68 65 20 73 70 65 63 69 66 69 63 20 63 t the specific c
3f6f0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 77 onnection that w
3f700 61 73 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c as passed to sql
3f710 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 ite3_backup_init
3f720 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 ()..**.** The [s
3f730 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f qlite3_backup] o
3f740 62 6a 65 63 74 20 69 74 73 65 6c 66 20 69 73 20 bject itself is
3f750 70 61 72 74 69 61 6c 6c 79 20 74 68 72 65 61 64 partially thread
3f760 73 61 66 65 2e 20 4d 75 6c 74 69 70 6c 65 20 0a safe. Multiple .
3f770 2a 2a 20 74 68 72 65 61 64 73 20 6d 61 79 20 73 ** threads may s
3f780 61 66 65 6c 79 20 6d 61 6b 65 20 6d 75 6c 74 69 afely make multi
3f790 70 6c 65 20 63 6f 6e 63 75 72 72 65 6e 74 20 63 ple concurrent c
3f7a0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
3f7b0 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 0a 2a backup_step()..*
3f7c0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 73 * However, the s
3f7d0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 72 65 qlite3_backup_re
3f7e0 6d 61 69 6e 69 6e 67 28 29 20 61 6e 64 20 73 71 maining() and sq
3f7f0 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 70 61 67 lite3_backup_pag
3f800 65 63 6f 75 6e 74 28 29 0a 2a 2a 20 41 50 49 73 ecount().** APIs
3f810 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c are not strictl
3f820 79 20 73 70 65 61 6b 69 6e 67 20 74 68 72 65 61 y speaking threa
3f830 64 73 61 66 65 2e 20 49 66 20 74 68 65 79 20 61 dsafe. If they a
3f840 72 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 74 68 re invoked at th
3f850 65 0a 2a 2a 20 73 61 6d 65 20 74 69 6d 65 20 61 e.** same time a
3f860 73 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 s another thread
3f870 20 69 73 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c is invoking sql
3f880 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3f890 28 29 20 69 74 20 69 73 0a 2a 2a 20 70 6f 73 73 () it is.** poss
3f8a0 69 62 6c 65 20 74 68 61 74 20 74 68 65 79 20 72 ible that they r
3f8b0 65 74 75 72 6e 20 69 6e 76 61 6c 69 64 20 76 61 eturn invalid va
3f8c0 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f lues..*/.SQLITE_
3f8d0 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
3f8e0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
3f8f0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 62 61 63 _API sqlite3_bac
3f900 6b 75 70 20 2a 73 71 6c 69 74 65 33 5f 62 61 63 kup *sqlite3_bac
3f910 6b 75 70 5f 69 6e 69 74 28 0a 20 20 73 71 6c 69 kup_init(. sqli
3f920 74 65 33 20 2a 70 44 65 73 74 2c 20 20 20 20 20 te3 *pDest,
3f930 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3f940 20 20 20 2f 2a 20 44 65 73 74 69 6e 61 74 69 6f /* Destinatio
3f950 6e 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c n database handl
3f960 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
3f970 72 20 2a 7a 44 65 73 74 4e 61 6d 65 2c 20 20 20 r *zDestName,
3f980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
3f990 20 44 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 Destination dat
3f9a0 61 62 61 73 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 abase name */.
3f9b0 73 71 6c 69 74 65 33 20 2a 70 53 6f 75 72 63 65 sqlite3 *pSource
3f9c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
3f9d0 20 20 20 20 20 20 20 2f 2a 20 53 6f 75 72 63 65 /* Source
3f9e0 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 database handle
3f9f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
3fa00 20 2a 7a 53 6f 75 72 63 65 4e 61 6d 65 20 20 20 *zSourceName
3fa10 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
3fa20 53 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 20 Source database
3fa30 6e 61 6d 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 name */.);.SQLIT
3fa40 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
3fa50 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 SQLITE_API SQLI
3fa60 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
3fa70 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 73 e3_backup_step(s
3fa80 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 2a 70 qlite3_backup *p
3fa90 2c 20 69 6e 74 20 6e 50 61 67 65 29 3b 0a 53 51 , int nPage);.SQ
3faa0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
3fab0 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
3fac0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
3fad0 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e lite3_backup_fin
3fae0 69 73 68 28 73 71 6c 69 74 65 33 5f 62 61 63 6b ish(sqlite3_back
3faf0 75 70 20 2a 70 29 3b 0a 53 51 4c 49 54 45 5f 41 up *p);.SQLITE_A
3fb00 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 PI SQLITE_API SQ
3fb10 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
3fb20 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
3fb30 62 61 63 6b 75 70 5f 72 65 6d 61 69 6e 69 6e 67 backup_remaining
3fb40 28 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 (sqlite3_backup
3fb50 2a 70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 *p);.SQLITE_API
3fb60 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
3fb70 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 E_API SQLITE_API
3fb80 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 61 63 int sqlite3_bac
3fb90 6b 75 70 5f 70 61 67 65 63 6f 75 6e 74 28 73 71 kup_pagecount(sq
3fba0 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 2a 70 29 lite3_backup *p)
3fbb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
3fbc0 46 3a 20 55 6e 6c 6f 63 6b 20 4e 6f 74 69 66 69 F: Unlock Notifi
3fbd0 63 61 74 69 6f 6e 0a 2a 2a 20 45 58 50 45 52 49 cation.** EXPERI
3fbe0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 57 68 65 MENTAL.**.** Whe
3fbf0 6e 20 72 75 6e 6e 69 6e 67 20 69 6e 20 73 68 61 n running in sha
3fc00 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 2c 20 red-cache mode,
3fc10 61 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 a database opera
3fc20 74 69 6f 6e 20 6d 61 79 20 66 61 69 6c 20 77 69 tion may fail wi
3fc30 74 68 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 45 th.** an [SQLITE
3fc40 5f 4c 4f 43 4b 45 44 5d 20 65 72 72 6f 72 20 69 _LOCKED] error i
3fc50 66 20 74 68 65 20 72 65 71 75 69 72 65 64 20 6c f the required l
3fc60 6f 63 6b 73 20 6f 6e 20 74 68 65 20 73 68 61 72 ocks on the shar
3fc70 65 64 2d 63 61 63 68 65 20 6f 72 0a 2a 2a 20 69 ed-cache or.** i
3fc80 6e 64 69 76 69 64 75 61 6c 20 74 61 62 6c 65 73 ndividual tables
3fc90 20 77 69 74 68 69 6e 20 74 68 65 20 73 68 61 72 within the shar
3fca0 65 64 2d 63 61 63 68 65 20 63 61 6e 6e 6f 74 20 ed-cache cannot
3fcb0 62 65 20 6f 62 74 61 69 6e 65 64 2e 20 53 65 65 be obtained. See
3fcc0 0a 2a 2a 20 5b 53 51 4c 69 74 65 20 53 68 61 72 .** [SQLite Shar
3fcd0 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 20 66 ed-Cache Mode] f
3fce0 6f 72 20 61 20 64 65 73 63 72 69 70 74 69 6f 6e or a description
3fcf0 20 6f 66 20 73 68 61 72 65 64 2d 63 61 63 68 65 of shared-cache
3fd00 20 6c 6f 63 6b 69 6e 67 2e 20 0a 2a 2a 20 54 68 locking. .** Th
3fd10 69 73 20 41 50 49 20 6d 61 79 20 62 65 20 75 73 is API may be us
3fd20 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 ed to register a
3fd30 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 53 callback that S
3fd40 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b QLite will invok
3fd50 65 20 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 63 e .** when the c
3fd60 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e onnection curren
3fd70 74 6c 79 20 68 6f 6c 64 69 6e 67 20 74 68 65 20 tly holding the
3fd80 72 65 71 75 69 72 65 64 20 6c 6f 63 6b 20 72 65 required lock re
3fd90 6c 69 6e 71 75 69 73 68 65 73 20 69 74 2e 0a 2a linquishes it..*
3fda0 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e * This API is on
3fdb0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 ly available if
3fdc0 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 the library was
3fdd0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
3fde0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 e.** [SQLITE_ENA
3fdf0 42 4c 45 5f 55 4e 4c 4f 43 4b 5f 4e 4f 54 49 46 BLE_UNLOCK_NOTIF
3fe00 59 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f Y] C-preprocesso
3fe10 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 r symbol defined
3fe20 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f ..**.** See Also
3fe30 3a 20 5b 55 73 69 6e 67 20 74 68 65 20 53 51 4c : [Using the SQL
3fe40 69 74 65 20 55 6e 6c 6f 63 6b 20 4e 6f 74 69 66 ite Unlock Notif
3fe50 69 63 61 74 69 6f 6e 20 46 65 61 74 75 72 65 5d ication Feature]
3fe60 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 2d 63 ..**.** Shared-c
3fe70 61 63 68 65 20 6c 6f 63 6b 73 20 61 72 65 20 72 ache locks are r
3fe80 65 6c 65 61 73 65 64 20 77 68 65 6e 20 61 20 64 eleased when a d
3fe90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3fea0 6f 6e 20 63 6f 6e 63 6c 75 64 65 73 0a 2a 2a 20 on concludes.**
3feb0 69 74 73 20 63 75 72 72 65 6e 74 20 74 72 61 6e its current tran
3fec0 73 61 63 74 69 6f 6e 2c 20 65 69 74 68 65 72 20 saction, either
3fed0 62 79 20 63 6f 6d 6d 69 74 74 69 6e 67 20 69 74 by committing it
3fee0 20 6f 72 20 72 6f 6c 6c 69 6e 67 20 69 74 20 62 or rolling it b
3fef0 61 63 6b 2e 20 0a 2a 2a 0a 2a 2a 20 57 68 65 6e ack. .**.** When
3ff00 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 28 6b a connection (k
3ff10 6e 6f 77 6e 20 61 73 20 74 68 65 20 62 6c 6f 63 nown as the bloc
3ff20 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 29 20 ked connection)
3ff30 66 61 69 6c 73 20 74 6f 20 6f 62 74 61 69 6e 20 fails to obtain
3ff40 61 0a 2a 2a 20 73 68 61 72 65 64 2d 63 61 63 68 a.** shared-cach
3ff50 65 20 6c 6f 63 6b 20 61 6e 64 20 53 51 4c 49 54 e lock and SQLIT
3ff60 45 5f 4c 4f 43 4b 45 44 20 69 73 20 72 65 74 75 E_LOCKED is retu
3ff70 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c rned to the call
3ff80 65 72 2c 20 74 68 65 0a 2a 2a 20 69 64 65 6e 74 er, the.** ident
3ff90 69 74 79 20 6f 66 20 74 68 65 20 64 61 74 61 62 ity of the datab
3ffa0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 28 ase connection (
3ffb0 74 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e the blocking con
3ffc0 6e 65 63 74 69 6f 6e 29 20 74 68 61 74 0a 2a 2a nection) that.**
3ffd0 20 68 61 73 20 6c 6f 63 6b 65 64 20 74 68 65 20 has locked the
3ffe0 72 65 71 75 69 72 65 64 20 72 65 73 6f 75 72 63 required resourc
3fff0 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 74 65 e is stored inte
40000 72 6e 61 6c 6c 79 2e 20 41 66 74 65 72 20 61 6e rnally. After an
40010 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e .** application
40020 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c receives an SQL
40030 49 54 45 5f 4c 4f 43 4b 45 44 20 65 72 72 6f 72 ITE_LOCKED error
40040 2c 20 69 74 20 6d 61 79 20 63 61 6c 6c 20 74 68 , it may call th
40050 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 6e 6c e.** sqlite3_unl
40060 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 6d 65 74 ock_notify() met
40070 68 6f 64 20 77 69 74 68 20 74 68 65 20 62 6c 6f hod with the blo
40080 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 cked connection
40090 68 61 6e 64 6c 65 20 61 73 20 0a 2a 2a 20 74 68 handle as .** th
400a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
400b0 20 74 6f 20 72 65 67 69 73 74 65 72 20 66 6f 72 to register for
400c0 20 61 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 a callback that
400d0 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 will be invoked
400e0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 62 6c 6f .** when the blo
400f0 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e cking connection
40100 73 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 s current transa
40110 63 74 69 6f 6e 20 69 73 20 63 6f 6e 63 6c 75 64 ction is conclud
40120 65 64 2e 20 54 68 65 0a 2a 2a 20 63 61 6c 6c 62 ed. The.** callb
40130 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 ack is invoked f
40140 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 5b rom within the [
40150 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 20 6f 72 sqlite3_step] or
40160 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5d [sqlite3_close]
40170 0a 2a 2a 20 63 61 6c 6c 20 74 68 61 74 20 63 6f .** call that co
40180 6e 63 6c 75 64 65 73 20 74 68 65 20 62 6c 6f 63 ncludes the bloc
40190 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 king connections
401a0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 0a 2a 2a transaction..**
401b0 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 75 .** If sqlite3_u
401c0 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 69 nlock_notify() i
401d0 73 20 63 61 6c 6c 65 64 20 69 6e 20 61 20 6d 75 s called in a mu
401e0 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 lti-threaded app
401f0 6c 69 63 61 74 69 6f 6e 2c 0a 2a 2a 20 74 68 65 lication,.** the
40200 72 65 20 69 73 20 61 20 63 68 61 6e 63 65 20 74 re is a chance t
40210 68 61 74 20 74 68 65 20 62 6c 6f 63 6b 69 6e 67 hat the blocking
40220 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 69 6c 6c connection will
40230 20 68 61 76 65 20 61 6c 72 65 61 64 79 0a 2a 2a have already.**
40240 20 63 6f 6e 63 6c 75 64 65 64 20 69 74 73 20 74 concluded its t
40250 72 61 6e 73 61 63 74 69 6f 6e 20 62 79 20 74 68 ransaction by th
40260 65 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 75 e time sqlite3_u
40270 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 69 nlock_notify() i
40280 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 49 66 s invoked..** If
40290 20 74 68 69 73 20 68 61 70 70 65 6e 73 2c 20 74 this happens, t
402a0 68 65 6e 20 74 68 65 20 73 70 65 63 69 66 69 65 hen the specifie
402b0 64 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e d callback is in
402c0 76 6f 6b 65 64 20 69 6d 6d 65 64 69 61 74 65 6c voked immediatel
402d0 79 2c 0a 2a 2a 20 66 72 6f 6d 20 77 69 74 68 69 y,.** from withi
402e0 6e 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 n the call to sq
402f0 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 lite3_unlock_not
40300 69 66 79 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ify()..**.** If
40310 74 68 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e the blocked conn
40320 65 63 74 69 6f 6e 20 69 73 20 61 74 74 65 6d 70 ection is attemp
40330 74 69 6e 67 20 74 6f 20 6f 62 74 61 69 6e 20 61 ting to obtain a
40340 20 77 72 69 74 65 2d 6c 6f 63 6b 20 6f 6e 20 61 write-lock on a
40350 0a 2a 2a 20 73 68 61 72 65 64 2d 63 61 63 68 65 .** shared-cache
40360 20 74 61 62 6c 65 2c 20 61 6e 64 20 6d 6f 72 65 table, and more
40370 20 74 68 61 6e 20 6f 6e 65 20 6f 74 68 65 72 20 than one other
40380 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 connection curre
40390 6e 74 6c 79 20 68 6f 6c 64 73 0a 2a 2a 20 61 20 ntly holds.** a
403a0 72 65 61 64 2d 6c 6f 63 6b 20 6f 6e 20 74 68 65 read-lock on the
403b0 20 73 61 6d 65 20 74 61 62 6c 65 2c 20 74 68 65 same table, the
403c0 6e 20 53 51 4c 69 74 65 20 61 72 62 69 74 72 61 n SQLite arbitra
403d0 72 69 6c 79 20 73 65 6c 65 63 74 73 20 6f 6e 65 rily selects one
403e0 20 6f 66 20 0a 2a 2a 20 74 68 65 20 6f 74 68 65 of .** the othe
403f0 72 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f r connections to
40400 20 75 73 65 20 61 73 20 74 68 65 20 62 6c 6f 63 use as the bloc
40410 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e king connection.
40420 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 6d 61 79 .**.** There may
40430 20 62 65 20 61 74 20 6d 6f 73 74 20 6f 6e 65 20 be at most one
40440 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 unlock-notify ca
40450 6c 6c 62 61 63 6b 20 72 65 67 69 73 74 65 72 65 llback registere
40460 64 20 62 79 20 61 20 0a 2a 2a 20 62 6c 6f 63 6b d by a .** block
40470 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 49 ed connection. I
40480 66 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b f sqlite3_unlock
40490 5f 6e 6f 74 69 66 79 28 29 20 69 73 20 63 61 6c _notify() is cal
404a0 6c 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 led when the.**
404b0 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 blocked connecti
404c0 6f 6e 20 61 6c 72 65 61 64 79 20 68 61 73 20 61 on already has a
404d0 20 72 65 67 69 73 74 65 72 65 64 20 75 6e 6c 6f registered unlo
404e0 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 ck-notify callba
404f0 63 6b 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 ck,.** then the
40500 6e 65 77 20 63 61 6c 6c 62 61 63 6b 20 72 65 70 new callback rep
40510 6c 61 63 65 73 20 74 68 65 20 6f 6c 64 2e 20 49 laces the old. I
40520 66 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b f sqlite3_unlock
40530 5f 6e 6f 74 69 66 79 28 29 20 69 73 0a 2a 2a 20 _notify() is.**
40540 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 called with a NU
40550 4c 4c 20 70 6f 69 6e 74 65 72 20 61 73 20 69 74 LL pointer as it
40560 73 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e s second argumen
40570 74 2c 20 74 68 65 6e 20 61 6e 79 20 65 78 69 73 t, then any exis
40580 74 69 6e 67 0a 2a 2a 20 75 6e 6c 6f 63 6b 2d 6e ting.** unlock-n
40590 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 69 otify callback i
405a0 73 20 63 61 6e 63 65 6c 6c 65 64 2e 20 54 68 65 s cancelled. The
405b0 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 74 blocked connect
405c0 69 6f 6e 73 20 0a 2a 2a 20 75 6e 6c 6f 63 6b 2d ions .** unlock-
405d0 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 notify callback
405e0 6d 61 79 20 61 6c 73 6f 20 62 65 20 63 61 6e 63 may also be canc
405f0 65 6c 65 64 20 62 79 20 63 6c 6f 73 69 6e 67 20 eled by closing
40600 74 68 65 20 62 6c 6f 63 6b 65 64 0a 2a 2a 20 63 the blocked.** c
40610 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 20 onnection using
40620 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
40630 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 6e 6c ]..**.** The unl
40640 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 ock-notify callb
40650 61 63 6b 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 ack is not reent
40660 72 61 6e 74 2e 20 49 66 20 61 6e 20 61 70 70 6c rant. If an appl
40670 69 63 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 0a ication invokes.
40680 2a 2a 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 78 ** any sqlite3_x
40690 78 78 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 73 xx API functions
406a0 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 61 6e 20 from within an
406b0 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 unlock-notify ca
406c0 6c 6c 62 61 63 6b 2c 20 61 0a 2a 2a 20 63 72 61 llback, a.** cra
406d0 73 68 20 6f 72 20 64 65 61 64 6c 6f 63 6b 20 6d sh or deadlock m
406e0 61 79 20 62 65 20 74 68 65 20 72 65 73 75 6c 74 ay be the result
406f0 2e 0a 2a 2a 0a 2a 2a 20 55 6e 6c 65 73 73 20 64 ..**.** Unless d
40700 65 61 64 6c 6f 63 6b 20 69 73 20 64 65 74 65 63 eadlock is detec
40710 74 65 64 20 28 73 65 65 20 62 65 6c 6f 77 29 2c ted (see below),
40720 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f sqlite3_unlock_
40730 6e 6f 74 69 66 79 28 29 20 61 6c 77 61 79 73 0a notify() always.
40740 2a 2a 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 ** returns SQLIT
40750 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 43 E_OK..**.** <b>C
40760 61 6c 6c 62 61 63 6b 20 49 6e 76 6f 63 61 74 69 allback Invocati
40770 6f 6e 20 44 65 74 61 69 6c 73 3c 2f 62 3e 0a 2a on Details</b>.*
40780 2a 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 75 6e 6c *.** When an unl
40790 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 ock-notify callb
407a0 61 63 6b 20 69 73 20 72 65 67 69 73 74 65 72 65 ack is registere
407b0 64 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 d, the applicati
407c0 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 20 0a 2a on provides a .*
407d0 2a 20 73 69 6e 67 6c 65 20 76 6f 69 64 2a 20 70 * single void* p
407e0 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 ointer that is p
407f0 61 73 73 65 64 20 74 6f 20 74 68 65 20 63 61 6c assed to the cal
40800 6c 62 61 63 6b 20 77 68 65 6e 20 69 74 20 69 73 lback when it is
40810 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 48 6f 77 invoked..** How
40820 65 76 65 72 2c 20 74 68 65 20 73 69 67 6e 61 74 ever, the signat
40830 75 72 65 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 ure of the callb
40840 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c ack function all
40850 6f 77 73 20 53 51 4c 69 74 65 20 74 6f 20 70 61 ows SQLite to pa
40860 73 73 0a 2a 2a 20 69 74 20 61 6e 20 61 72 72 61 ss.** it an arra
40870 79 20 6f 66 20 76 6f 69 64 2a 20 63 6f 6e 74 65 y of void* conte
40880 78 74 20 70 6f 69 6e 74 65 72 73 2e 20 54 68 65 xt pointers. The
40890 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
408a0 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 61 6e 20 passed to.** an
408b0 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 unlock-notify ca
408c0 6c 6c 62 61 63 6b 20 69 73 20 61 20 70 6f 69 6e llback is a poin
408d0 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 ter to an array
408e0 6f 66 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 of void* pointer
408f0 73 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 s,.** and the se
40900 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 cond is the numb
40910 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e er of entries in
40920 20 74 68 65 20 61 72 72 61 79 2e 0a 2a 2a 0a 2a the array..**.*
40930 2a 20 57 68 65 6e 20 61 20 62 6c 6f 63 6b 69 6e * When a blockin
40940 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 72 g connections tr
40950 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6e ansaction is con
40960 63 6c 75 64 65 64 2c 20 74 68 65 72 65 20 6d 61 cluded, there ma
40970 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 74 68 61 y be.** more tha
40980 6e 20 6f 6e 65 20 62 6c 6f 63 6b 65 64 20 63 6f n one blocked co
40990 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 68 61 nnection that ha
409a0 73 20 72 65 67 69 73 74 65 72 65 64 20 66 6f 72 s registered for
409b0 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 an unlock-notif
409c0 79 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 20 49 y.** callback. I
409d0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 73 75 f two or more su
409e0 63 68 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 ch blocked conne
409f0 63 74 69 6f 6e 73 20 68 61 76 65 20 73 70 65 63 ctions have spec
40a00 69 66 69 65 64 20 74 68 65 0a 2a 2a 20 73 61 6d ified the.** sam
40a10 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
40a20 69 6f 6e 2c 20 74 68 65 6e 20 69 6e 73 74 65 61 ion, then instea
40a30 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 d of invoking th
40a40 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
40a50 69 6f 6e 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 ion.** multiple
40a60 74 69 6d 65 73 2c 20 69 74 20 69 73 20 69 6e 76 times, it is inv
40a70 6f 6b 65 64 20 6f 6e 63 65 20 77 69 74 68 20 74 oked once with t
40a80 68 65 20 73 65 74 20 6f 66 20 76 6f 69 64 2a 20 he set of void*
40a90 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 73 context pointers
40aa0 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62 79 .** specified by
40ab0 20 74 68 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e the blocked con
40ac0 6e 65 63 74 69 6f 6e 73 20 62 75 6e 64 6c 65 64 nections bundled
40ad0 20 74 6f 67 65 74 68 65 72 20 69 6e 74 6f 20 61 together into a
40ae0 6e 20 61 72 72 61 79 2e 0a 2a 2a 20 54 68 69 73 n array..** This
40af0 20 67 69 76 65 73 20 74 68 65 20 61 70 70 6c 69 gives the appli
40b00 63 61 74 69 6f 6e 20 61 6e 20 6f 70 70 6f 72 74 cation an opport
40b10 75 6e 69 74 79 20 74 6f 20 70 72 69 6f 72 69 74 unity to priorit
40b20 69 7a 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 ize any actions
40b30 0a 2a 2a 20 72 65 6c 61 74 65 64 20 74 6f 20 74 .** related to t
40b40 68 65 20 73 65 74 20 6f 66 20 75 6e 62 6c 6f 63 he set of unbloc
40b50 6b 65 64 20 64 61 74 61 62 61 73 65 20 63 6f 6e ked database con
40b60 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 nections..**.**
40b70 3c 62 3e 44 65 61 64 6c 6f 63 6b 20 44 65 74 65 <b>Deadlock Dete
40b80 63 74 69 6f 6e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 ction</b>.**.**
40b90 41 73 73 75 6d 69 6e 67 20 74 68 61 74 20 61 66 Assuming that af
40ba0 74 65 72 20 72 65 67 69 73 74 65 72 69 6e 67 20 ter registering
40bb0 66 6f 72 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f for an unlock-no
40bc0 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 61 20 tify callback a
40bd0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 77 61 69 .** database wai
40be0 74 73 20 66 6f 72 20 74 68 65 20 63 61 6c 6c 62 ts for the callb
40bf0 61 63 6b 20 74 6f 20 62 65 20 69 73 73 75 65 64 ack to be issued
40c00 20 62 65 66 6f 72 65 20 74 61 6b 69 6e 67 20 61 before taking a
40c10 6e 79 20 66 75 72 74 68 65 72 0a 2a 2a 20 61 63 ny further.** ac
40c20 74 69 6f 6e 20 28 61 20 72 65 61 73 6f 6e 61 62 tion (a reasonab
40c30 6c 65 20 61 73 73 75 6d 70 74 69 6f 6e 29 2c 20 le assumption),
40c40 74 68 65 6e 20 75 73 69 6e 67 20 74 68 69 73 20 then using this
40c50 41 50 49 20 6d 61 79 20 63 61 75 73 65 20 74 68 API may cause th
40c60 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e e.** application
40c70 20 74 6f 20 64 65 61 64 6c 6f 63 6b 2e 20 46 6f to deadlock. Fo
40c80 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 63 6f r example, if co
40c90 6e 6e 65 63 74 69 6f 6e 20 58 20 69 73 20 77 61 nnection X is wa
40ca0 69 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 63 6f 6e iting for.** con
40cb0 6e 65 63 74 69 6f 6e 20 59 27 73 20 74 72 61 6e nection Y's tran
40cc0 73 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 6f saction to be co
40cd0 6e 63 6c 75 64 65 64 2c 20 61 6e 64 20 73 69 6d ncluded, and sim
40ce0 69 6c 61 72 6c 79 20 63 6f 6e 6e 65 63 74 69 6f ilarly connectio
40cf0 6e 0a 2a 2a 20 59 20 69 73 20 77 61 69 74 69 6e n.** Y is waitin
40d00 67 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 g on connection
40d10 58 27 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c X's transaction,
40d20 20 74 68 65 6e 20 6e 65 69 74 68 65 72 20 63 6f then neither co
40d30 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c nnection.** will
40d40 20 70 72 6f 63 65 65 64 20 61 6e 64 20 74 68 65 proceed and the
40d50 20 73 79 73 74 65 6d 20 6d 61 79 20 72 65 6d 61 system may rema
40d60 69 6e 20 64 65 61 64 6c 6f 63 6b 65 64 20 69 6e in deadlocked in
40d70 64 65 66 69 6e 69 74 65 6c 79 2e 0a 2a 2a 0a 2a definitely..**.*
40d80 2a 20 54 6f 20 61 76 6f 69 64 20 74 68 69 73 20 * To avoid this
40d90 73 63 65 6e 61 72 69 6f 2c 20 74 68 65 20 73 71 scenario, the sq
40da0 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 lite3_unlock_not
40db0 69 66 79 28 29 20 70 65 72 66 6f 72 6d 73 20 64 ify() performs d
40dc0 65 61 64 6c 6f 63 6b 0a 2a 2a 20 64 65 74 65 63 eadlock.** detec
40dd0 74 69 6f 6e 2e 20 49 66 20 61 20 67 69 76 65 6e tion. If a given
40de0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
40df0 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 _unlock_notify()
40e00 20 77 6f 75 6c 64 20 70 75 74 20 74 68 65 0a 2a would put the.*
40e10 2a 20 73 79 73 74 65 6d 20 69 6e 20 61 20 64 65 * system in a de
40e20 61 64 6c 6f 63 6b 65 64 20 73 74 61 74 65 2c 20 adlocked state,
40e30 74 68 65 6e 20 53 51 4c 49 54 45 5f 4c 4f 43 4b then SQLITE_LOCK
40e40 45 44 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 ED is returned a
40e50 6e 64 20 6e 6f 0a 2a 2a 20 75 6e 6c 6f 63 6b 2d nd no.** unlock-
40e60 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 notify callback
40e70 69 73 20 72 65 67 69 73 74 65 72 65 64 2e 20 54 is registered. T
40e80 68 65 20 73 79 73 74 65 6d 20 69 73 20 73 61 69 he system is sai
40e90 64 20 74 6f 20 62 65 20 69 6e 0a 2a 2a 20 61 20 d to be in.** a
40ea0 64 65 61 64 6c 6f 63 6b 65 64 20 73 74 61 74 65 deadlocked state
40eb0 20 69 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 41 if connection A
40ec0 20 68 61 73 20 72 65 67 69 73 74 65 72 65 64 20 has registered
40ed0 66 6f 72 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f for an unlock-no
40ee0 74 69 66 79 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b tify.** callback
40ef0 20 6f 6e 20 74 68 65 20 63 6f 6e 63 6c 75 73 69 on the conclusi
40f00 6f 6e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e on of connection
40f10 20 42 27 73 20 74 72 61 6e 73 61 63 74 69 6f 6e B's transaction
40f20 2c 20 61 6e 64 20 63 6f 6e 6e 65 63 74 69 6f 6e , and connection
40f30 0a 2a 2a 20 42 20 68 61 73 20 69 74 73 65 6c 66 .** B has itself
40f40 20 72 65 67 69 73 74 65 72 65 64 20 66 6f 72 20 registered for
40f50 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 an unlock-notify
40f60 20 63 61 6c 6c 62 61 63 6b 20 77 68 65 6e 20 63 callback when c
40f70 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 41 27 73 onnection.** A's
40f80 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
40f90 63 6f 6e 63 6c 75 64 65 64 2e 20 49 6e 64 69 72 concluded. Indir
40fa0 65 63 74 20 64 65 61 64 6c 6f 63 6b 20 69 73 20 ect deadlock is
40fb0 61 6c 73 6f 20 64 65 74 65 63 74 65 64 2c 20 73 also detected, s
40fc0 6f 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 o.** the system
40fd0 69 73 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 is also consider
40fe0 65 64 20 74 6f 20 62 65 20 64 65 61 64 6c 6f 63 ed to be deadloc
40ff0 6b 65 64 20 69 66 20 63 6f 6e 6e 65 63 74 69 6f ked if connectio
41000 6e 20 42 20 68 61 73 0a 2a 2a 20 72 65 67 69 73 n B has.** regis
41010 74 65 72 65 64 20 66 6f 72 20 61 6e 20 75 6e 6c tered for an unl
41020 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 ock-notify callb
41030 61 63 6b 20 6f 6e 20 74 68 65 20 63 6f 6e 63 6c ack on the concl
41040 75 73 69 6f 6e 20 6f 66 20 63 6f 6e 6e 65 63 74 usion of connect
41050 69 6f 6e 0a 2a 2a 20 43 27 73 20 74 72 61 6e 73 ion.** C's trans
41060 61 63 74 69 6f 6e 2c 20 77 68 65 72 65 20 63 6f action, where co
41070 6e 6e 65 63 74 69 6f 6e 20 43 20 69 73 20 77 61 nnection C is wa
41080 69 74 69 6e 67 20 6f 6e 20 63 6f 6e 6e 65 63 74 iting on connect
41090 69 6f 6e 20 41 2e 20 41 6e 79 0a 2a 2a 20 6e 75 ion A. Any.** nu
410a0 6d 62 65 72 20 6f 66 20 6c 65 76 65 6c 73 20 6f mber of levels o
410b0 66 20 69 6e 64 69 72 65 63 74 69 6f 6e 20 61 72 f indirection ar
410c0 65 20 61 6c 6c 6f 77 65 64 2e 0a 2a 2a 0a 2a 2a e allowed..**.**
410d0 20 3c 62 3e 54 68 65 20 22 44 52 4f 50 20 54 41 <b>The "DROP TA
410e0 42 4c 45 22 20 45 78 63 65 70 74 69 6f 6e 3c 2f BLE" Exception</
410f0 62 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 b>.**.** When a
41100 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
41110 5f 73 74 65 70 28 29 5d 20 72 65 74 75 72 6e 73 _step()] returns
41120 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 2c 20 SQLITE_LOCKED,
41130 69 74 20 69 73 20 61 6c 6d 6f 73 74 20 0a 2a 2a it is almost .**
41140 20 61 6c 77 61 79 73 20 61 70 70 72 6f 70 72 69 always appropri
41150 61 74 65 20 74 6f 20 63 61 6c 6c 20 73 71 6c 69 ate to call sqli
41160 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 te3_unlock_notif
41170 79 28 29 2e 20 54 68 65 72 65 20 69 73 20 68 6f y(). There is ho
41180 77 65 76 65 72 2c 0a 2a 2a 20 6f 6e 65 20 65 78 wever,.** one ex
41190 63 65 70 74 69 6f 6e 2e 20 57 68 65 6e 20 65 78 ception. When ex
411a0 65 63 75 74 69 6e 67 20 61 20 22 44 52 4f 50 20 ecuting a "DROP
411b0 54 41 42 4c 45 22 20 6f 72 20 22 44 52 4f 50 20 TABLE" or "DROP
411c0 49 4e 44 45 58 22 20 73 74 61 74 65 6d 65 6e 74 INDEX" statement
411d0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 63 68 65 63 ,.** SQLite chec
411e0 6b 73 20 69 66 20 74 68 65 72 65 20 61 72 65 20 ks if there are
411f0 61 6e 79 20 63 75 72 72 65 6e 74 6c 79 20 65 78 any currently ex
41200 65 63 75 74 69 6e 67 20 53 45 4c 45 43 54 20 73 ecuting SELECT s
41210 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 tatements.** tha
41220 74 20 62 65 6c 6f 6e 67 20 74 6f 20 74 68 65 20 t belong to the
41230 73 61 6d 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e same connection.
41240 20 49 66 20 74 68 65 72 65 20 61 72 65 2c 20 53 If there are, S
41250 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 69 73 0a QLITE_LOCKED is.
41260 2a 2a 20 72 65 74 75 72 6e 65 64 2e 20 49 6e 20 ** returned. In
41270 74 68 69 73 20 63 61 73 65 20 74 68 65 72 65 20 this case there
41280 69 73 20 6e 6f 20 22 62 6c 6f 63 6b 69 6e 67 20 is no "blocking
41290 63 6f 6e 6e 65 63 74 69 6f 6e 22 2c 20 73 6f 20 connection", so
412a0 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 invoking.** sqli
412b0 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 te3_unlock_notif
412c0 79 28 29 20 72 65 73 75 6c 74 73 20 69 6e 20 74 y() results in t
412d0 68 65 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 he unlock-notify
412e0 20 63 61 6c 6c 62 61 63 6b 20 62 65 69 6e 67 0a callback being.
412f0 2a 2a 20 69 6e 76 6f 6b 65 64 20 69 6d 6d 65 64 ** invoked immed
41300 69 61 74 65 6c 79 2e 20 49 66 20 74 68 65 20 61 iately. If the a
41310 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 65 6e 20 pplication then
41320 72 65 2d 61 74 74 65 6d 70 74 73 20 74 68 65 20 re-attempts the
41330 22 44 52 4f 50 20 54 41 42 4c 45 22 0a 2a 2a 20 "DROP TABLE".**
41340 6f 72 20 22 44 52 4f 50 20 49 4e 44 45 58 22 20 or "DROP INDEX"
41350 71 75 65 72 79 2c 20 61 6e 20 69 6e 66 69 6e 69 query, an infini
41360 74 65 20 6c 6f 6f 70 20 6d 69 67 68 74 20 62 65 te loop might be
41370 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a the result..**.
41380 2a 2a 20 4f 6e 65 20 77 61 79 20 61 72 6f 75 6e ** One way aroun
41390 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 69 d this problem i
413a0 73 20 74 6f 20 63 68 65 63 6b 20 74 68 65 20 65 s to check the e
413b0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
413c0 64 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 de returned.** b
413d0 79 20 61 6e 20 73 71 6c 69 74 65 33 5f 73 74 65 y an sqlite3_ste
413e0 70 28 29 20 63 61 6c 6c 2e 20 49 66 20 74 68 65 p() call. If the
413f0 72 65 20 69 73 20 61 20 62 6c 6f 63 6b 69 6e 67 re is a blocking
41400 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 connection, the
41410 6e 20 74 68 65 0a 2a 2a 20 65 78 74 65 6e 64 65 n the.** extende
41420 64 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 d error code is
41430 73 65 74 20 74 6f 20 53 51 4c 49 54 45 5f 4c 4f set to SQLITE_LO
41440 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 CKED_SHAREDCACHE
41450 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 69 6e 0a . Otherwise, in.
41460 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 22 ** the special "
41470 44 52 4f 50 20 54 41 42 4c 45 2f 49 4e 44 45 58 DROP TABLE/INDEX
41480 22 20 63 61 73 65 2c 20 74 68 65 20 65 78 74 65 " case, the exte
41490 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 20 nded error code
414a0 69 73 20 6a 75 73 74 20 0a 2a 2a 20 53 51 4c 49 is just .** SQLI
414b0 54 45 5f 4c 4f 43 4b 45 44 2e 0a 2a 2f 0a 53 51 TE_LOCKED..*/.SQ
414c0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
414d0 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 53 API SQLITE_API S
414e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
414f0 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 lite3_unlock_not
41500 69 66 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a ify(. sqlite3 *
41510 70 42 6c 6f 63 6b 65 64 2c 20 20 20 20 20 20 20 pBlocked,
41520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41530 20 20 20 2f 2a 20 57 61 69 74 69 6e 67 20 63 6f /* Waiting co
41540 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f nnection */. vo
41550 69 64 20 28 2a 78 4e 6f 74 69 66 79 29 28 76 6f id (*xNotify)(vo
41560 69 64 20 2a 2a 61 70 41 72 67 2c 20 69 6e 74 20 id **apArg, int
41570 6e 41 72 67 29 2c 20 20 20 20 2f 2a 20 43 61 6c nArg), /* Cal
41580 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 lback function t
41590 6f 20 69 6e 76 6f 6b 65 20 2a 2f 0a 20 20 76 6f o invoke */. vo
415a0 69 64 20 2a 70 4e 6f 74 69 66 79 41 72 67 20 20 id *pNotifyArg
415b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
415c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 /* Arg
415d0 75 6d 65 6e 74 20 74 6f 20 70 61 73 73 20 74 6f ument to pass to
415e0 20 78 4e 6f 74 69 66 79 20 2a 2f 0a 29 3b 0a 0a xNotify */.);..
415f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
41600 20 53 74 72 69 6e 67 20 43 6f 6d 70 61 72 69 73 String Comparis
41610 6f 6e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 on.** EXPERIMENT
41620 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 AL.**.** The [sq
41630 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 lite3_strnicmp()
41640 5d 20 41 50 49 20 61 6c 6c 6f 77 73 20 61 70 70 ] API allows app
41650 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 65 78 lications and ex
41660 74 65 6e 73 69 6f 6e 73 20 74 6f 0a 2a 2a 20 63 tensions to.** c
41670 6f 6d 70 61 72 65 20 74 68 65 20 63 6f 6e 74 65 ompare the conte
41680 6e 74 73 20 6f 66 20 74 77 6f 20 62 75 66 66 65 nts of two buffe
41690 72 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 55 54 rs containing UT
416a0 46 2d 38 20 73 74 72 69 6e 67 73 20 69 6e 20 61 F-8 strings in a
416b0 0a 2a 2a 20 63 61 73 65 2d 69 6e 64 65 6e 64 65 .** case-indende
416c0 6e 74 20 66 61 73 68 69 6f 6e 2c 20 75 73 69 6e nt fashion, usin
416d0 67 20 74 68 65 20 73 61 6d 65 20 64 65 66 69 6e g the same defin
416e0 69 74 69 6f 6e 20 6f 66 20 63 61 73 65 20 69 6e ition of case in
416f0 64 65 70 65 6e 64 65 6e 63 65 20 0a 2a 2a 20 74 dependence .** t
41700 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 73 20 hat SQLite uses
41710 69 6e 74 65 72 6e 61 6c 6c 79 20 77 68 65 6e 20 internally when
41720 63 6f 6d 70 61 72 69 6e 67 20 69 64 65 6e 74 69 comparing identi
41730 66 69 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 fiers..*/.SQLITE
41740 5f 41 50 49 20 53 51 4c 49 54 45 5f 41 50 49 20 _API SQLITE_API
41750 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
41760 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
41770 33 5f 73 74 72 6e 69 63 6d 70 28 63 6f 6e 73 74 3_strnicmp(const
41780 20 63 68 61 72 20 2a 2c 20 63 6f 6e 73 74 20 63 char *, const c
41790 68 61 72 20 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a har *, int);../*
417a0 0a 2a 2a 20 55 6e 64 6f 20 74 68 65 20 68 61 63 .** Undo the hac
417b0 6b 20 74 68 61 74 20 63 6f 6e 76 65 72 74 73 20 k that converts
417c0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 74 floating point t
417d0 79 70 65 73 20 74 6f 20 69 6e 74 65 67 65 72 20 ypes to integer
417e0 66 6f 72 0a 2a 2a 20 62 75 69 6c 64 73 20 6f 6e for.** builds on
417f0 20 70 72 6f 63 65 73 73 6f 72 73 20 77 69 74 68 processors with
41800 6f 75 74 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 out floating poi
41810 6e 74 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 nt support..*/.#
41820 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 ifdef SQLITE_OMI
41830 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 T_FLOATING_POINT
41840 0a 23 20 75 6e 64 65 66 20 64 6f 75 62 6c 65 0a .# undef double.
41850 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 5f #endif..#ifdef _
41860 5f 63 70 6c 75 73 70 6c 75 73 0a 7d 20 20 2f 2a _cplusplus.} /*
41870 20 45 6e 64 20 6f 66 20 74 68 65 20 27 65 78 74 End of the 'ext
41880 65 72 6e 20 22 43 22 27 20 62 6c 6f 63 6b 20 2a ern "C"' block *
41890 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a /.#endif.#endif.
418a0 0a 0a 0a 0a ....