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 33 37 31 20 32 30 30 38 2f 30 n,v 1.371 2008/0
05f0: 37 2f 31 34 20 31 38 3a 33 38 3a 31 37 20 64 72 7/14 18:38:17 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64 h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 arg.h> /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72 ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68 f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65 _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65 SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a xtern.#endif../*
0740: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 .** Ensure these
0750: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f symbols were no
0760: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d t defined by som
0770: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 e previous heade
0780: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 r file..*/.#ifde
0790: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e f SQLITE_VERSION
07a0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f .# undef SQLITE_
07b0: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 VERSION.#endif.#
07c0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 ifdef SQLITE_VER
07d0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e SION_NUMBER.# un
07e0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 def SQLITE_VERSI
07f0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 ON_NUMBER.#endif
0800: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
0810: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c : Compile-Time L
0820: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e ibrary Version N
0830: 75 6d 62 65 72 73 20 7b 46 31 30 30 31 30 7d 0a umbers {F10010}.
0840: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 **.** The SQLITE
0850: 5f 56 45 52 53 49 4f 4e 20 61 6e 64 20 53 51 4c _VERSION and SQL
0860: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
0870: 45 52 20 23 64 65 66 69 6e 65 73 20 69 6e 0a 2a ER #defines in.*
0880: 2a 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 * the sqlite3.h
0890: 66 69 6c 65 20 73 70 65 63 69 66 79 20 74 68 65 file specify the
08a0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 version of SQLi
08b0: 74 65 20 77 69 74 68 20 77 68 69 63 68 0a 2a 2a te with which.**
08c0: 20 74 68 61 74 20 68 65 61 64 65 72 20 66 69 6c that header fil
08d0: 65 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 2e e is associated.
08e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 76 65 72 73 .**.** The "vers
08f0: 69 6f 6e 22 20 6f 66 20 53 51 4c 69 74 65 20 69 ion" of SQLite i
0900: 73 20 61 20 73 74 72 69 6e 67 20 6f 66 20 74 68 s a string of th
0910: 65 20 66 6f 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a e form "X.Y.Z"..
0920: 2a 2a 20 54 68 65 20 70 68 72 61 73 65 20 22 61 ** The phrase "a
0930: 6c 70 68 61 22 20 6f 72 20 22 62 65 74 61 22 20 lpha" or "beta"
0940: 6d 69 67 68 74 20 62 65 20 61 70 70 65 6e 64 65 might be appende
0950: 64 20 61 66 74 65 72 20 74 68 65 20 5a 2e 0a 2a d after the Z..*
0960: 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20 69 73 * The X value is
0970: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e major version n
0980: 75 6d 62 65 72 20 61 6c 77 61 79 73 20 33 20 69 umber always 3 i
0990: 6e 20 53 51 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 n SQLite3..** Th
09a0: 65 20 58 20 76 61 6c 75 65 20 6f 6e 6c 79 20 63 e X value only c
09b0: 68 61 6e 67 65 73 20 77 68 65 6e 20 62 61 63 6b hanges when back
09c0: 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
09d0: 69 74 79 20 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e ity is.** broken
09e0: 20 61 6e 64 20 77 65 20 69 6e 74 65 6e 64 20 74 and we intend t
09f0: 6f 20 6e 65 76 65 72 20 62 72 65 61 6b 20 62 61 o never break ba
0a00: 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
0a10: 69 6c 69 74 79 2e 0a 2a 2a 20 54 68 65 20 59 20 ility..** The Y
0a20: 76 61 6c 75 65 20 69 73 20 74 68 65 20 6d 69 6e value is the min
0a30: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 or version numbe
0a40: 72 20 61 6e 64 20 6f 6e 6c 79 20 63 68 61 6e 67 r and only chang
0a50: 65 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65 72 65 es when.** there
0a60: 20 61 72 65 20 6d 61 6a 6f 72 20 66 65 61 74 75 are major featu
0a70: 72 65 20 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20 re enhancements
0a80: 74 68 61 74 20 61 72 65 20 66 6f 72 77 61 72 64 that are forward
0a90: 73 20 63 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 s compatible.**
0aa0: 62 75 74 20 6e 6f 74 20 62 61 63 6b 77 61 72 64 but not backward
0ab0: 73 20 63 6f 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a s compatible..**
0ac0: 20 54 68 65 20 5a 20 76 61 6c 75 65 20 69 73 20 The Z value is
0ad0: 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 the release numb
0ae0: 65 72 20 61 6e 64 20 69 73 20 69 6e 63 72 65 6d er and is increm
0af0: 65 6e 74 65 64 20 77 69 74 68 0a 2a 2a 20 65 61 ented with.** ea
0b00: 63 68 20 72 65 6c 65 61 73 65 20 62 75 74 20 72 ch release but r
0b10: 65 73 65 74 73 20 62 61 63 6b 20 74 6f 20 30 20 esets back to 0
0b20: 77 68 65 6e 65 76 65 72 20 59 20 69 73 20 69 6e whenever Y is in
0b30: 63 72 65 6d 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a cremented..**.**
0b40: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
0b50: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 te3_libversion()
0b60: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6c ] and [sqlite3_l
0b70: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 ibversion_number
0b80: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ()]..**.** INVAR
0b90: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 IANTS:.**.** {F1
0ba0: 30 30 31 31 7d 20 54 68 65 20 53 51 4c 49 54 45 0011} The SQLITE
0bb0: 5f 56 45 52 53 49 4f 4e 20 23 64 65 66 69 6e 65 _VERSION #define
0bc0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 2e in the sqlite3.
0bd0: 68 20 68 65 61 64 65 72 20 66 69 6c 65 20 73 68 h header file sh
0be0: 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 all.**
0bf0: 65 76 61 6c 75 61 74 65 20 74 6f 20 61 20 73 74 evaluate to a st
0c00: 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 ring literal tha
0c10: 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 t is the SQLite
0c20: 76 65 72 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 version.**
0c30: 20 20 20 20 77 69 74 68 20 77 68 69 63 68 20 74 with which t
0c40: 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 he header file i
0c50: 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a s associated..**
0c60: 0a 2a 2a 20 7b 46 31 30 30 31 34 7d 20 54 68 65 .** {F10014} The
0c70: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f SQLITE_VERSION_
0c80: 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 20 73 NUMBER #define s
0c90: 68 61 6c 6c 20 72 65 73 6f 6c 76 65 20 74 6f 20 hall resolve to
0ca0: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 an integer.**
0cb0: 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65 20 with the
0cc0: 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 value (X*1000000
0cd0: 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 + Y*1000 + Z) w
0ce0: 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a here X, Y, and Z
0cf0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 .** are
0d00: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 the major versi
0d10: 6f 6e 2c 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f on, minor versio
0d20: 6e 2c 20 61 6e 64 20 72 65 6c 65 61 73 65 20 6e n, and release n
0d30: 75 6d 62 65 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e umber..*/.#defin
0d40: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e e SQLITE_VERSION
0d50: 20 20 20 20 20 20 20 20 20 22 33 2e 36 2e 30 22 "3.6.0"
0d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
0d70: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 VERSION_NUMBER
0d80: 33 30 30 36 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 3006000../*.** C
0d90: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d API3REF: Run-Tim
0da0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f e Library Versio
0db0: 6e 20 4e 75 6d 62 65 72 73 20 7b 46 31 30 30 32 n Numbers {F1002
0dc0: 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 0}.** KEYWORDS:
0dd0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a sqlite3_version.
0de0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 65 61 74 **.** These feat
0df0: 75 72 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 ures provide the
0e00: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f same informatio
0e10: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 n as the [SQLITE
0e20: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 _VERSION].** and
0e30: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
0e40: 5f 4e 55 4d 42 45 52 5d 20 23 64 65 66 69 6e 65 _NUMBER] #define
0e50: 73 20 69 6e 20 74 68 65 20 68 65 61 64 65 72 2c s in the header,
0e60: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 but are associa
0e70: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ted.** with the
0e80: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 library instead
0e90: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69 of the header fi
0ea0: 6c 65 2e 20 20 43 61 75 74 69 6f 75 73 20 70 72 le. Cautious pr
0eb0: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 0a ogrammers might.
0ec0: 2a 2a 20 69 6e 63 6c 75 64 65 20 61 20 63 68 65 ** include a che
0ed0: 63 6b 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c ck in their appl
0ee0: 69 63 61 74 69 6f 6e 20 74 6f 20 76 65 72 69 66 ication to verif
0ef0: 79 20 74 68 61 74 0a 2a 2a 20 73 71 6c 69 74 65 y that.** sqlite
0f00: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 3_libversion_num
0f10: 62 65 72 28 29 20 61 6c 77 61 79 73 20 72 65 74 ber() always ret
0f20: 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 0a 2a urns the value.*
0f30: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f * [SQLITE_VERSIO
0f40: 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a N_NUMBER]..**.**
0f50: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 The sqlite3_lib
0f60: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 version() functi
0f70: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 on returns the s
0f80: 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 ame information
0f90: 61 73 20 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20 as is.** in the
0fa0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b sqlite3_version[
0fb0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e ] string constan
0fc0: 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e t. The function
0fd0: 20 69 73 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 is provided.**
0fe0: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 for use in DLLs
0ff0: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 since DLL users
1000: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 usually do not h
1010: 61 76 65 20 64 69 72 65 63 74 20 61 63 63 65 73 ave direct acces
1020: 73 20 74 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63 s to string.** c
1030: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 onstants within
1040: 74 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 the DLL..**.** I
1050: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
1060: 20 7b 46 31 30 30 32 31 7d 20 54 68 65 20 5b 73 {F10021} The [s
1070: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1080: 6e 5f 6e 75 6d 62 65 72 28 29 5d 20 69 6e 74 65 n_number()] inte
1090: 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75 rface shall retu
10a0: 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 rn.** a
10b0: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 n integer equal
10c0: 74 6f 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 to [SQLITE_VERSI
10d0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a ON_NUMBER]..**.*
10e0: 2a 20 7b 46 31 30 30 32 32 7d 20 54 68 65 20 5b * {F10022} The [
10f0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5d sqlite3_version]
1100: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 string constant
1110: 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 0a 2a shall contain.*
1120: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74 * the t
1130: 65 78 74 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 ext of the [SQLI
1140: 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73 74 72 69 TE_VERSION] stri
1150: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30 32 ng..**.** {F1002
1160: 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 3} The [sqlite3_
1170: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 66 75 libversion()] fu
1180: 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 nction shall ret
1190: 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 urn.**
11a0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
11b0: 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f [sqlite3_versio
11c0: 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 n] string consta
11d0: 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 nt..*/.SQLITE_EX
11e0: 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 TERN const char
11f0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b sqlite3_version[
1200: 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 ];.const char *s
1210: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1220: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c n(void);.int sql
1230: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f ite3_libversion_
1240: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f number(void);../
1250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
1260: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 est To See If Th
1270: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 e Library Is Thr
1280: 65 61 64 73 61 66 65 20 7b 46 31 30 31 30 30 7d eadsafe {F10100}
1290: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 .**.** SQLite ca
12a0: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 n be compiled wi
12b0: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 th or without mu
12c0: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 texes. When.**
12d0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
12e0: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f ADSAFE] C prepro
12f0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 cessor macro is
1300: 74 72 75 65 2c 20 6d 75 74 65 78 65 73 0a 2a 2a true, mutexes.**
1310: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 are enabled and
1320: 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 SQLite is threa
1330: 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 61 dsafe. When tha
1340: 74 20 6d 61 63 72 6f 20 69 73 20 66 61 6c 73 65 t macro is false
1350: 2c 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 ,.** the mutexes
1360: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 are omitted. W
1370: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 ithout the mutex
1380: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 es, it is not sa
1390: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c fe.** to use SQL
13a0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 ite concurrently
13b0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 from more than
13c0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a one thread..**.*
13d0: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 * Enabling mutex
13e0: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 es incurs a meas
13f0: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e urable performan
1400: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 ce penalty..** S
1410: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 o if speed is of
1420: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e utmost importan
1430: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e ce, it makes sen
1440: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a se to disable.**
1450: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 the mutexes. B
1460: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 ut for maximum s
1470: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 afety, mutexes s
1480: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 hould be enabled
1490: 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 ..** The default
14a0: 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 behavior is for
14b0: 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 mutexes to be e
14c0: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 nabled..**.** Th
14d0: 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e is interface can
14e0: 20 62 65 20 75 73 65 64 20 62 79 20 61 20 70 72 be used by a pr
14f0: 6f 67 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73 75 ogram to make su
1500: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 re that the.** v
1510: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 ersion of SQLite
1520: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b that it is link
1530: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 ing against was
1540: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
1550: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 the desired set
1560: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c ting of the [SQL
1570: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
1580: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 macro..**.** Thi
1590: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 s interface only
15a0: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 reports on the
15b0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 compile-time mut
15c0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 ex setting.** of
15d0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
15e0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 EADSAFE] flag.
15f0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
1600: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 piled with.** SQ
1610: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
1620: 31 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 1 then mutexes a
1630: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 re enabled by de
1640: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e fault but.** can
1650: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 be fully or par
1660: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 tially disabled
1670: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 using a call to
1680: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
1690: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 )].** with the v
16a0: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e erbs [SQLITE_CON
16b0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
16c0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ], [SQLITE_CONFI
16d0: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a G_MULTITHREAD],.
16e0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f ** or [SQLITE_CO
16f0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 NFIG_MUTEX]. Th
1700: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
1710: 66 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 f this function
1720: 73 68 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 shows.** only th
1730: 65 20 64 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c e default compil
1740: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 e-time setting,
1750: 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 not any run-time
1760: 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 changes.** to t
1770: 68 61 74 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a hat setting..**.
1780: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
1790: 2a 0a 2a 2a 20 7b 46 31 30 31 30 31 7d 20 54 68 *.** {F10101} Th
17a0: 65 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 e [sqlite3_threa
17b0: 64 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69 6f dsafe()] functio
17c0: 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 6e n shall return n
17d0: 6f 6e 7a 65 72 6f 20 69 66 0a 2a 2a 20 20 20 20 onzero if.**
17e0: 20 20 20 20 20 20 53 51 4c 69 74 65 20 77 61 73 SQLite was
17f0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
1800: 68 65 20 69 74 73 20 6d 75 74 65 78 65 73 20 65 he its mutexes e
1810: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c nabled by defaul
1820: 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 t.** or
1830: 20 7a 65 72 6f 20 69 66 20 53 51 4c 69 74 65 20 zero if SQLite
1840: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 73 75 63 was compiled suc
1850: 68 20 74 68 61 74 20 6d 75 74 65 78 65 73 20 61 h that mutexes a
1860: 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 re.** p
1870: 65 72 6d 61 6e 65 6e 74 6c 79 20 64 69 73 61 62 ermanently disab
1880: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 31 led..**.** {F101
1890: 30 32 7d 20 54 68 65 20 76 61 6c 75 65 20 72 65 02} The value re
18a0: 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 5b 73 turned by the [s
18b0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
18c0: 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a e()] function.**
18d0: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 shall
18e0: 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 65 6e 20 not change when
18f0: 6d 75 74 65 78 20 73 65 74 74 69 6e 67 20 61 72 mutex setting ar
1900: 65 20 6d 6f 64 69 66 69 65 64 20 61 74 0a 2a 2a e modified at.**
1910: 20 20 20 20 20 20 20 20 20 20 72 75 6e 74 69 6d runtim
1920: 65 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c e using the [sql
1930: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 ite3_config()] i
1940: 6e 74 65 72 66 61 63 65 20 61 6e 64 20 0a 2a 2a nterface and .**
1950: 20 20 20 20 20 20 20 20 20 20 65 73 70 65 63 69 especi
1960: 61 6c 6c 79 20 74 68 65 20 5b 53 51 4c 49 54 45 ally the [SQLITE
1970: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
1980: 52 45 41 44 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 READ],.**
1990: 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 [SQLITE_CONFI
19a0: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 20 G_MULTITHREAD],
19b0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
19c0: 45 52 49 41 4c 49 5a 45 44 5d 2c 0a 2a 2a 20 20 ERIALIZED],.**
19d0: 20 20 20 20 20 20 20 20 61 6e 64 20 5b 53 51 4c and [SQL
19e0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
19f0: 5d 20 76 65 72 62 73 2e 0a 2a 2f 0a 69 6e 74 20 ] verbs..*/.int
1a00: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 sqlite3_threadsa
1a10: 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a fe(void);../*.**
1a20: 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 CAPI3REF: Datab
1a30: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 ase Connection H
1a40: 61 6e 64 6c 65 20 7b 46 31 32 30 30 30 7d 0a 2a andle {F12000}.*
1a50: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 * KEYWORDS: {dat
1a60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1a70: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e } {database conn
1a80: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 ections}.**.** E
1a90: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 ach open SQLite
1aa0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 database is repr
1ab0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 esented by a poi
1ac0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
1ad0: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 nce of.** the op
1ae0: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e aque structure n
1af0: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 amed "sqlite3".
1b00: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f It is useful to
1b10: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c think of an sql
1b20: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 ite3.** pointer
1b30: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 as an object. T
1b40: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e he [sqlite3_open
1b50: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
1b60: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 en16()], and.**
1b70: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
1b80: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 ()] interfaces a
1b90: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 re its construct
1ba0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ors, and [sqlite
1bb0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73 3_close()].** is
1bc0: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e its destructor.
1bd0: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 There are many
1be0: 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 other interface
1bf0: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 s (such as.** [s
1c00: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1c10: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 2()], [sqlite3_c
1c20: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
1c30: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
1c40: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
1c50: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 )] to name but t
1c60: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d hree) that are m
1c70: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 ethods on an.**
1c80: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a sqlite3 object..
1c90: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
1ca0: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 t sqlite3 sqlite
1cb0: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 3;../*.** CAPI3R
1cc0: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 EF: 64-Bit Integ
1cd0: 65 72 20 54 79 70 65 73 20 7b 46 31 30 32 30 30 er Types {F10200
1ce0: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 }.** KEYWORDS: s
1cf0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 qlite_int64 sqli
1d00: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 te_uint64.**.**
1d10: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 Because there is
1d20: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f no cross-platfo
1d30: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 rm way to specif
1d40: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 y 64-bit integer
1d50: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 types.** SQLite
1d60: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 includes typede
1d70: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 fs for 64-bit si
1d80: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 gned and unsigne
1d90: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a d integers..**.*
1da0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
1db0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t64 and sqlite3_
1dc0: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 uint64 are the p
1dd0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65 referred type de
1de0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 finitions..** Th
1df0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 e sqlite_int64 a
1e00: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 nd sqlite_uint64
1e10: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f types are suppo
1e20: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 rted for backwar
1e30: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c ds.** compatibil
1e40: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ity only..**.**
1e50: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
1e60: 2a 20 7b 46 31 30 32 30 31 7d 20 54 68 65 20 5b * {F10201} The [
1e70: 73 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e sqlite_int64] an
1e80: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 d [sqlite3_int64
1e90: 5d 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 ] type shall spe
1ea0: 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 cify.**
1eb0: 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 a 64-bit signed
1ec0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 integer..**.**
1ed0: 7b 46 31 30 32 30 32 7d 20 54 68 65 20 5b 73 71 {F10202} The [sq
1ee0: 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64 lite_uint64] and
1ef0: 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 [sqlite3_uint64
1f00: 5d 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 ] type shall spe
1f10: 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 cify.**
1f20: 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e a 64-bit unsign
1f30: 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 ed integer..*/.#
1f40: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 ifdef SQLITE_INT
1f50: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 64_TYPE. typede
1f60: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 f SQLITE_INT64_T
1f70: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 YPE sqlite_int64
1f80: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 ;. typedef unsi
1f90: 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 gned SQLITE_INT6
1fa0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 4_TYPE sqlite_ui
1fb0: 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 nt64;.#elif defi
1fc0: 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c ned(_MSC_VER) ||
1fd0: 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 defined(__BORLA
1fe0: 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 NDC__). typedef
1ff0: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f __int64 sqlite_
2000: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 int64;. typedef
2010: 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 unsigned __int6
2020: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 4 sqlite_uint64;
2030: 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 .#else. typedef
2040: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 long long int s
2050: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 qlite_int64;. t
2060: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 ypedef unsigned
2070: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 long long int sq
2080: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e lite_uint64;.#en
2090: 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 dif.typedef sqli
20a0: 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 te_int64 sqlite3
20b0: 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 _int64;.typedef
20c0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 sqlite_uint64 sq
20d0: 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f lite3_uint64;../
20e0: 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e *.** If compilin
20f0: 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f g for a processo
2100: 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f r that lacks flo
2110: 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 ating point supp
2120: 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 ort,.** substitu
2130: 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 te integer for f
2140: 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a loating-point..*
2150: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f /.#ifdef SQLITE_
2160: 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f OMIT_FLOATING_PO
2170: 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 INT.# define dou
2180: 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 ble sqlite3_int6
2190: 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4.#endif../*.**
21a0: 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e CAPI3REF: Closin
21b0: 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e g A Database Con
21c0: 6e 65 63 74 69 6f 6e 20 7b 46 31 32 30 31 30 7d nection {F12010}
21d0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
21e0: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 ine is the destr
21f0: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 uctor for the [s
2200: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a qlite3] object..
2210: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f **.** Applicatio
2220: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 ns should [sqlit
2230: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 e3_finalize | fi
2240: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 nalize] all [pre
2250: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
2260: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
2270: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 3_blob_close | c
2280: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 lose] all [BLOB
2290: 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 handles] associa
22a0: 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 ted with.** the
22b0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 [sqlite3] object
22c0: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 prior to attemp
22d0: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 ting to close th
22e0: 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 e object..** The
22f0: 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 [sqlite3_next_s
2300: 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tmt()] interface
2310: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
2320: 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 locate all.** [p
2330: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2340: 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 ts] associated w
2350: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 ith a [database
2360: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64 connection] if d
2370: 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63 esired..** Typic
2380: 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f al code might lo
2390: 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a ok like this:.**
23a0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
23b0: 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 <pre>.** sqlite3
23c0: 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a _stmt *pStmt;.**
23d0: 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d while( (pStmt =
23e0: 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 sqlite3_next_st
23f0: 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b mt(db, 0))!=0 ){
2400: 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c .** sql
2410: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53 ite3_finalize(pS
2420: 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f tmt);.** }.** </
2430: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
2440: 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 >.**.** If [sqli
2450: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 te3_close()] is
2460: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 invoked while a
2470: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f transaction is o
2480: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e pen,.** the tran
2490: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d saction is autom
24a0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 atically rolled
24b0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 back..**.** INVA
24c0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 RIANTS:.**.** {F
24d0: 31 32 30 31 31 7d 20 41 20 73 75 63 63 65 73 73 12011} A success
24e0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
24f0: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73 ite3_close(C)] s
2500: 68 61 6c 6c 20 64 65 73 74 72 6f 79 20 74 68 65 hall destroy the
2510: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 .** [da
2520: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2530: 6e 5d 20 6f 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a n] object C..**.
2540: 2a 2a 20 7b 46 31 32 30 31 32 7d 20 41 20 73 75 ** {F12012} A su
2550: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
2560: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
2570: 43 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e C)] shall return
2580: 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a SQLITE_OK..**.*
2590: 2a 20 7b 46 31 32 30 31 33 7d 20 41 20 73 75 63 * {F12013} A suc
25a0: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 cessful call to
25b0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 [sqlite3_close(C
25c0: 29 5d 20 73 68 61 6c 6c 20 72 65 6c 65 61 73 65 )] shall release
25d0: 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 all.**
25e0: 20 6d 65 6d 6f 72 79 20 61 6e 64 20 73 79 73 74 memory and syst
25f0: 65 6d 20 72 65 73 6f 75 72 63 65 73 20 61 73 73 em resources ass
2600: 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b 64 61 ociated with [da
2610: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2620: 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 n].** C
2630: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31 34 7d ..**.** {F12014}
2640: 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 A call to [sqli
2650: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6f 6e te3_close(C)] on
2660: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
2670: 6e 65 63 74 69 6f 6e 5d 20 43 20 74 68 61 74 0a nection] C that.
2680: 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 73 20 ** has
2690: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 70 65 6e one or more open
26a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
26b0: 6d 65 6e 74 73 5d 20 73 68 61 6c 6c 20 66 61 69 ments] shall fai
26c0: 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 l with.**
26d0: 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 an [SQLITE_BU
26e0: 53 59 5d 20 65 72 72 6f 72 20 63 6f 64 65 2e 0a SY] error code..
26f0: 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31 35 7d 20 41 **.** {F12015} A
2700: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
2710: 33 5f 63 6c 6f 73 65 28 43 29 5d 20 77 68 65 72 3_close(C)] wher
2720: 65 20 43 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f e C is a NULL po
2730: 69 6e 74 65 72 20 73 68 61 6c 6c 0a 2a 2a 20 20 inter shall.**
2740: 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 53 return S
2750: 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 QLITE_OK..**.**
2760: 7b 46 31 32 30 31 39 7d 20 57 68 65 6e 20 5b 73 {F12019} When [s
2770: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d qlite3_close(C)]
2780: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 is invoked on a
2790: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
27a0: 63 74 69 6f 6e 5d 20 43 0a 2a 2a 20 20 20 20 20 ction] C.**
27b0: 20 20 20 20 20 74 68 61 74 20 68 61 73 20 61 20 that has a
27c0: 70 65 6e 64 69 6e 67 20 74 72 61 6e 73 61 63 74 pending transact
27d0: 69 6f 6e 2c 20 74 68 65 20 74 72 61 6e 73 61 63 ion, the transac
27e0: 74 69 6f 6e 20 73 68 61 6c 6c 20 62 65 0a 2a 2a tion shall be.**
27f0: 20 20 20 20 20 20 20 20 20 20 72 6f 6c 6c 65 64 rolled
2800: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d back..**.** LIM
2810: 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 ITATIONS:.**.**
2820: 7b 41 31 32 30 31 36 7d 20 54 68 65 20 43 20 70 {A12016} The C p
2830: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
2840: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d ite3_close(C)] m
2850: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 ust be either a
2860: 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 NULL.**
2870: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b pointer or an [
2880: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
2890: 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 pointer previous
28a0: 6c 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 ly obtained.**
28b0: 20 20 20 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 from [sq
28c0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b lite3_open()], [
28d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
28e0: 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 ], or.**
28f0: 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f [sqlite3_open_
2900: 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 v2()], and not p
2910: 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 reviously closed
2920: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2930: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a _close(sqlite3 *
2940: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 );../*.** The ty
2950: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 pe for a callbac
2960: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 k function..** T
2970: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e his is legacy an
2980: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 d deprecated. I
2990: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f t is included fo
29a0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 r historical.**
29b0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e compatibility an
29c0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e d is not documen
29d0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ted..*/.typedef
29e0: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 int (*sqlite3_ca
29f0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e llback)(void*,in
2a00: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a t,char**, char**
2a10: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2a20: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 EF: One-Step Que
2a30: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 ry Execution Int
2a40: 65 72 66 61 63 65 20 7b 46 31 32 31 30 30 7d 0a erface {F12100}.
2a50: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
2a60: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 3_exec() interfa
2a70: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 ce is a convenie
2a80: 6e 74 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e nt way of runnin
2a90: 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a g one or more.**
2aa0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
2ab0: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 without having t
2ac0: 6f 20 77 72 69 74 65 20 61 20 6c 6f 74 20 6f 66 o write a lot of
2ad0: 20 43 20 63 6f 64 65 2e 20 20 54 68 65 20 55 54 C code. The UT
2ae0: 46 2d 38 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 53 F-8 encoded.** S
2af0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 QL statements ar
2b00: 65 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 e passed in as t
2b10: 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
2b20: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
2b30: 78 65 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 74 xec()..** The st
2b40: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 atements are eva
2b50: 6c 75 61 74 65 64 20 6f 6e 65 20 62 79 20 6f 6e luated one by on
2b60: 65 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 61 e until either a
2b70: 6e 20 65 72 72 6f 72 20 6f 72 0a 2a 2a 20 61 6e n error or.** an
2b80: 20 69 6e 74 65 72 72 75 70 74 20 69 73 20 65 6e interrupt is en
2b90: 63 6f 75 6e 74 65 72 65 64 2c 20 6f 72 20 75 6e countered, or un
2ba0: 74 69 6c 20 74 68 65 79 20 61 72 65 20 61 6c 6c til they are all
2bb0: 20 64 6f 6e 65 2e 20 20 54 68 65 20 33 72 64 20 done. The 3rd
2bc0: 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 parameter.** is
2bd0: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63 61 6c 6c an optional call
2be0: 62 61 63 6b 20 74 68 61 74 20 69 73 20 69 6e 76 back that is inv
2bf0: 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 oked once for ea
2c00: 63 68 20 72 6f 77 20 6f 66 20 61 6e 79 20 71 75 ch row of any qu
2c10: 65 72 79 0a 2a 2a 20 72 65 73 75 6c 74 73 20 70 ery.** results p
2c20: 72 6f 64 75 63 65 64 20 62 79 20 74 68 65 20 53 roduced by the S
2c30: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 QL statements.
2c40: 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 The 5th paramete
2c50: 72 20 74 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a r tells where.**
2c60: 20 74 6f 20 77 72 69 74 65 20 61 6e 79 20 65 72 to write any er
2c70: 72 6f 72 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a ror messages..**
2c80: 0a 2a 2a 20 54 68 65 20 65 72 72 6f 72 20 6d 65 .** The error me
2c90: 73 73 61 67 65 20 70 61 73 73 65 64 20 62 61 63 ssage passed bac
2ca0: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 k through the 5t
2cb0: 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 68 h parameter is h
2cc0: 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d 6f 72 79 eld.** in memory
2cd0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
2ce0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
2cf0: 5d 2e 20 20 54 6f 20 61 76 6f 69 64 20 61 20 6d ]. To avoid a m
2d00: 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a 2a 20 74 emory leak,.** t
2d10: 68 65 20 63 61 6c 6c 69 6e 67 20 61 70 70 6c 69 he calling appli
2d20: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 63 61 cation should ca
2d30: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ll [sqlite3_free
2d40: 28 29 5d 20 6f 6e 20 61 6e 79 20 65 72 72 6f 72 ()] on any error
2d50: 0a 2a 2a 20 6d 65 73 73 61 67 65 20 72 65 74 75 .** message retu
2d60: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 rned through the
2d70: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 77 5th parameter w
2d80: 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 hen it has finis
2d90: 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 hed using.** the
2da0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a error message..
2db0: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c **.** If the SQL
2dc0: 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 statement in th
2dd0: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
2de0: 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d is NULL or an em
2df0: 70 74 79 20 73 74 72 69 6e 67 0a 2a 2a 20 6f 72 pty string.** or
2e00: 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 a string contai
2e10: 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 69 74 65 73 ning only whites
2e20: 70 61 63 65 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 pace and comment
2e30: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 0a 2a s, then no SQL.*
2e40: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 * statements are
2e50: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 evaluated and t
2e60: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6e he database is n
2e70: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a ot changed..**.*
2e80: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 * The sqlite3_ex
2e90: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ec() interface i
2ea0: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e s implemented in
2eb0: 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 terms of.** [sq
2ec0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2ed0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 ()], [sqlite3_st
2ee0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 ep()], and [sqli
2ef0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e te3_finalize()].
2f00: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
2f10: 65 78 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64 exec() routine d
2f20: 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20 74 oes nothing to t
2f30: 68 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74 he database that
2f40: 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a cannot be done.
2f50: 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 ** by [sqlite3_p
2f60: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 repare_v2()], [s
2f70: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 qlite3_step()],
2f80: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e and [sqlite3_fin
2f90: 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 alize()]..**.**
2fa0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
2fb0: 2a 20 7b 46 31 32 31 30 31 7d 20 41 20 73 75 63 * {F12101} A suc
2fc0: 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 cessful invocati
2fd0: 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 on of [sqlite3_e
2fe0: 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 0a xec(D,S,C,A,E)].
2ff0: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c ** shal
3000: 6c 20 73 65 71 75 65 6e 74 69 61 6c 6c 79 20 65 l sequentially e
3010: 76 61 6c 75 61 74 65 20 61 6c 6c 20 6f 66 20 74 valuate all of t
3020: 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 he UTF-8 encoded
3030: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 65 ,.** se
3040: 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 micolon-separate
3050: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 d SQL statements
3060: 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 in the zero-ter
3070: 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 minated.**
3080: 20 20 20 20 73 74 72 69 6e 67 20 53 20 77 69 74 string S wit
3090: 68 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 hin the context
30a0: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 of the [database
30b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a connection] D..
30c0: 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 32 7d 20 49 **.** {F12102} I
30d0: 66 20 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 f the S paramete
30e0: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 r to [sqlite3_ex
30f0: 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 ec(D,S,C,A,E)] i
3100: 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 s NULL then.**
3110: 20 20 20 20 20 20 20 20 74 68 65 20 61 63 74 69 the acti
3120: 6f 6e 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72 ons of the inter
3130: 66 61 63 65 20 73 68 61 6c 6c 20 62 65 20 74 68 face shall be th
3140: 65 20 73 61 6d 65 20 61 73 20 69 66 20 74 68 65 e same as if the
3150: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 20 70 .** S p
3160: 61 72 61 6d 65 74 65 72 20 77 65 72 65 20 61 6e arameter were an
3170: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a empty string..*
3180: 2a 0a 2a 2a 20 7b 46 31 32 31 30 34 7d 20 54 68 *.** {F12104} Th
3190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
31a0: 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 f [sqlite3_exec(
31b0: 29 5d 20 73 68 61 6c 6c 20 62 65 20 5b 53 51 4c )] shall be [SQL
31c0: 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6c 6c 0a 2a ITE_OK] if all.*
31d0: 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 * SQL s
31e0: 74 61 74 65 6d 65 6e 74 73 20 72 75 6e 20 73 75 tatements run su
31f0: 63 63 65 73 73 66 75 6c 6c 79 20 61 6e 64 20 74 ccessfully and t
3200: 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a o completion..**
3210: 0a 2a 2a 20 7b 46 31 32 31 30 35 7d 20 54 68 65 .** {F12105} The
3220: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
3230: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
3240: 5d 20 73 68 61 6c 6c 20 62 65 20 61 6e 20 61 70 ] shall be an ap
3250: 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 20 20 20 propriate.**
3260: 20 20 20 20 20 20 6e 6f 6e 2d 7a 65 72 6f 20 5b non-zero [
3270: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 error code] if a
3280: 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ny SQL statement
3290: 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 fails..**.** {F
32a0: 31 32 31 30 37 7d 20 49 66 20 6f 6e 65 20 6f 72 12107} If one or
32b0: 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 53 51 4c more of the SQL
32c0: 20 73 74 61 74 65 6d 65 6e 74 73 20 68 61 6e 64 statements hand
32d0: 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 ed to [sqlite3_e
32e0: 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 xec()].**
32f0: 20 20 20 72 65 74 75 72 6e 20 72 65 73 75 6c 74 return result
3300: 73 20 61 6e 64 20 74 68 65 20 33 72 64 20 70 61 s and the 3rd pa
3310: 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 4e rameter is not N
3320: 55 4c 4c 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 ULL, then.**
3330: 20 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 the callba
3340: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 70 65 63 ck function spec
3350: 69 66 69 65 64 20 62 79 20 74 68 65 20 33 72 64 ified by the 3rd
3360: 20 70 61 72 61 6d 65 74 65 72 20 73 68 61 6c 6c parameter shall
3370: 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 be.**
3380: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 invoked once for
3390: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 72 65 73 each row of res
33a0: 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 ult..**.** {F121
33b0: 31 30 7d 20 49 66 20 74 68 65 20 63 61 6c 6c 62 10} If the callb
33c0: 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 6e 6f ack returns a no
33d0: 6e 2d 7a 65 72 6f 20 76 61 6c 75 65 20 74 68 65 n-zero value the
33e0: 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 n [sqlite3_exec(
33f0: 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 )].** s
3400: 68 61 6c 6c 20 61 62 6f 72 74 20 74 68 65 20 53 hall abort the S
3410: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 74 20 QL statement it
3420: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 65 76 61 is currently eva
3430: 6c 75 61 74 69 6e 67 2c 0a 2a 2a 20 20 20 20 20 luating,.**
3440: 20 20 20 20 20 73 6b 69 70 20 61 6c 6c 20 73 75 skip all su
3450: 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 bsequent SQL sta
3460: 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 72 65 74 tements, and ret
3470: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 urn [SQLITE_ABOR
3480: 54 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 T]..**.** {F1211
3490: 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 3} The [sqlite3_
34a0: 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 exec()] routine
34b0: 73 68 61 6c 6c 20 70 61 73 73 20 69 74 73 20 34 shall pass its 4
34c0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 72 th parameter thr
34d0: 6f 75 67 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 ough.**
34e0: 20 61 73 20 74 68 65 20 31 73 74 20 70 61 72 61 as the 1st para
34f0: 6d 65 74 65 72 20 6f 66 20 74 68 65 20 63 61 6c meter of the cal
3500: 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 lback..**.** {F1
3510: 32 31 31 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 2116} The [sqlit
3520: 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 e3_exec()] routi
3530: 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 ne shall set the
3540: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 2nd parameter o
3550: 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 f its.**
3560: 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 callback to be
3570: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
3580: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 63 75 olumns in the cu
3590: 72 72 65 6e 74 20 72 6f 77 20 6f 66 0a 2a 2a 20 rrent row of.**
35a0: 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 2e result.
35b0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 39 7d 20 .**.** {F12119}
35c0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 The [sqlite3_exe
35d0: 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 c()] routine sha
35e0: 6c 6c 20 73 65 74 20 74 68 65 20 33 72 64 20 70 ll set the 3rd p
35f0: 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a arameter of its.
3600: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c ** call
3610: 62 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 back to be an ar
3620: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 ray of pointers
3630: 74 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 to strings holdi
3640: 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ng the.**
3650: 20 20 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 values for ea
3660: 63 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 ch column in the
3670: 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 current result
3680: 73 65 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 set row as.**
3690: 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 obtained
36a0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f from [sqlite3_co
36b0: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a lumn_text()]..**
36c0: 0a 2a 2a 20 7b 46 31 32 31 32 32 7d 20 54 68 65 .** {F12122} The
36d0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
36e0: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 ] routine shall
36f0: 73 65 74 20 74 68 65 20 34 74 68 20 70 61 72 61 set the 4th para
3700: 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 meter of its.**
3710: 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 callbac
3720: 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61 79 k to be an array
3730: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 of pointers to
3740: 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 strings holding
3750: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
3760: 6e 61 6d 65 73 20 6f 66 20 72 65 73 75 6c 74 20 names of result
3770: 63 6f 6c 75 6d 6e 73 20 61 73 20 6f 62 74 61 69 columns as obtai
3780: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
3790: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 3_column_name()]
37a0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 32 35 7d ..**.** {F12125}
37b0: 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 If the 3rd para
37c0: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
37d0: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 4e 55 4c 3_exec()] is NUL
37e0: 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 L then.**
37f0: 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 [sqlite3_exec
3800: 28 29 5d 20 73 68 61 6c 6c 20 73 69 6c 65 6e 74 ()] shall silent
3810: 6c 79 20 64 69 73 63 61 72 64 20 71 75 65 72 79 ly discard query
3820: 20 72 65 73 75 6c 74 73 2e 0a 2a 2a 0a 2a 2a 20 results..**.**
3830: 7b 46 31 32 31 33 31 7d 20 49 66 20 61 6e 20 65 {F12131} If an e
3840: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c rror occurs whil
3850: 65 20 70 61 72 73 69 6e 67 20 6f 72 20 65 76 61 e parsing or eva
3860: 6c 75 61 74 69 6e 67 20 61 6e 79 20 6f 66 20 74 luating any of t
3870: 68 65 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 he SQL.**
3880: 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e statements in
3890: 20 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 the S parameter
38a0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 of [sqlite3_exe
38b0: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 61 6e c(D,S,C,A,E)] an
38c0: 64 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 d if.**
38d0: 20 74 68 65 20 45 20 70 61 72 61 6d 65 74 65 72 the E parameter
38e0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 is not NULL, th
38f0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 en [sqlite3_exec
3900: 28 29 5d 20 73 68 61 6c 6c 20 73 74 6f 72 65 0a ()] shall store.
3910: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 2a ** in *
3920: 45 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 E an appropriate
3930: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 77 error message w
3940: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f ritten into memo
3950: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 ry obtained.**
3960: 20 20 20 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 from [sq
3970: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
3980: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 34 7d 20 .**.** {F12134}
3990: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 The [sqlite3_exe
39a0: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 72 6f c(D,S,C,A,E)] ro
39b0: 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 utine shall set
39c0: 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 the value of.**
39d0: 20 20 20 20 20 20 20 20 20 2a 45 20 74 6f 20 4e *E to N
39e0: 55 4c 4c 20 69 66 20 45 20 69 73 20 6e 6f 74 20 ULL if E is not
39f0: 4e 55 4c 4c 20 61 6e 64 20 74 68 65 72 65 20 61 NULL and there a
3a00: 72 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a re no errors..**
3a10: 0a 2a 2a 20 7b 46 31 32 31 33 37 7d 20 54 68 65 .** {F12137} The
3a20: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 [sqlite3_exec(D
3a30: 2c 53 2c 43 2c 41 2c 45 29 5d 20 66 75 6e 63 74 ,S,C,A,E)] funct
3a40: 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20 74 68 ion shall set th
3a50: 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a e [error code].*
3a60: 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 6d * and m
3a70: 65 73 73 61 67 65 20 61 63 63 65 73 73 69 62 6c essage accessibl
3a80: 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 e via [sqlite3_e
3a90: 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 rrcode()],.**
3aa0: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
3ab0: 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b errmsg()], and [
3ac0: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
3ad0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 ()]..**.** {F121
3ae0: 33 38 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 38} If the S par
3af0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
3b00: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c e3_exec(D,S,C,A,
3b10: 45 29 5d 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 E)] is NULL or a
3b20: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6d n.** em
3b30: 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 63 6f pty string or co
3b40: 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f ntains nothing o
3b50: 74 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 ther than whites
3b60: 70 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 0a pace, comments,.
3b70: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 2f ** and/
3b80: 6f 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 or semicolons, t
3b90: 68 65 6e 20 72 65 73 75 6c 74 73 20 6f 66 20 5b hen results of [
3ba0: 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
3bb0: 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 )],.**
3bc0: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
3bd0: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 )], and [sqlite3
3be0: 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 _errmsg16()].**
3bf0: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72 shall r
3c00: 65 73 65 74 20 74 6f 20 69 6e 64 69 63 61 74 65 eset to indicate
3c10: 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a no errors..**.*
3c20: 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a * LIMITATIONS:.*
3c30: 2a 0a 2a 2a 20 7b 41 31 32 31 34 31 7d 20 54 68 *.** {A12141} Th
3c40: 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
3c50: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 r to [sqlite3_ex
3c60: 65 63 28 29 5d 20 6d 75 73 74 20 62 65 20 61 6e ec()] must be an
3c70: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a valid and open.
3c80: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 ** [dat
3c90: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3ca0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 32 ]..**.** {A12142
3cb0: 7d 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 } The database c
3cc0: 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e onnection must n
3cd0: 6f 74 20 62 65 20 63 6c 6f 73 65 64 20 77 68 69 ot be closed whi
3ce0: 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b le.** [
3cf0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
3d00: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a is running..**.*
3d10: 2a 20 7b 41 31 32 31 34 33 7d 20 54 68 65 20 63 * {A12143} The c
3d20: 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 alling function
3d30: 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 should use [sqli
3d40: 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 te3_free()] to f
3d50: 72 65 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ree.**
3d60: 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 the memory that
3d70: 2a 65 72 72 6d 73 67 20 69 73 20 6c 65 66 74 20 *errmsg is left
3d80: 70 6f 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 pointing at once
3d90: 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 the error.**
3da0: 20 20 20 20 20 20 20 6d 65 73 73 61 67 65 20 69 message i
3db0: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 s no longer need
3dc0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 ed..**.** {A1214
3dd0: 35 7d 20 54 68 65 20 53 51 4c 20 73 74 61 74 65 5} The SQL state
3de0: 6d 65 6e 74 20 74 65 78 74 20 69 6e 20 74 68 65 ment text in the
3df0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 2nd parameter t
3e00: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 o [sqlite3_exec(
3e10: 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d )].** m
3e20: 75 73 74 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 ust remain uncha
3e30: 6e 67 65 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 nged while [sqli
3e40: 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 te3_exec()] is r
3e50: 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 unning..*/.int s
3e60: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 qlite3_exec(. s
3e70: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 qlite3*,
3e80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3e90: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 /* An
3ea0: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f open database */
3eb0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 . const char *s
3ec0: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 ql,
3ed0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
3ee0: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 SQL to be evalu
3ef0: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a ated */. int (*
3f00: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c callback)(void*,
3f10: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a int,char**,char*
3f20: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b *), /* Callback
3f30: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 function */. v
3f40: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 oid *,
3f50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3f60: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 /* 1st
3f70: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c argument to cal
3f80: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 lback */. char
3f90: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 **errmsg
3fa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3fb0: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d /* Error m
3fc0: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 sg written here
3fd0: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
3fe0: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f I3REF: Result Co
3ff0: 64 65 73 20 7b 46 31 30 32 31 30 7d 0a 2a 2a 20 des {F10210}.**
4000: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 KEYWORDS: SQLITE
4010: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d _OK {error code}
4020: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a {error codes}.*
4030: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 * KEYWORDS: {res
4040: 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c ult code} {resul
4050: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d t codes}.**.** M
4060: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 any SQLite funct
4070: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 ions return an i
4080: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f nteger result co
4090: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 de from the set
40a0: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e shown.** here in
40b0: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 order to indica
40c0: 74 65 73 20 73 75 63 63 65 73 73 20 6f 72 20 66 tes success or f
40d0: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 ailure..**.** Ne
40e0: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 w error codes ma
40f0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
4100: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
4110: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 SQLite..**.** S
4120: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 ee also: [SQLITE
4130: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 _IOERR_READ | ex
4140: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
4150: 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 des].*/.#define
4160: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 SQLITE_OK
4170: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 0 /* Succe
4180: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a ssful result */.
4190: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d /* beginning-of-
41a0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 error-codes */.#
41b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 define SQLITE_ER
41c0: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f ROR 1 /
41d0: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d * SQL error or m
41e0: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 issing database
41f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4200: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 E_INTERNAL 2
4210: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c /* Internal l
4220: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 ogic error in SQ
4230: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 Lite */.#define
4240: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 SQLITE_PERM
4250: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 3 /* Acces
4260: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e s permission den
4270: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ied */.#define S
4280: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 QLITE_ABORT
4290: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 4 /* Callba
42a0: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 ck routine reque
42b0: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f sted an abort */
42c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
42d0: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 BUSY 5
42e0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 /* The database
42f0: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 file is locked
4300: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4310: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 E_LOCKED 6
4320: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e /* A table in
4330: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
4340: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 locked */.#defi
4350: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 ne SQLITE_NOMEM
4360: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 7 /* A
4370: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 malloc() failed
4380: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4390: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 E_READONLY 8
43a0: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f /* Attempt to
43b0: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c write a readonl
43c0: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 y database */.#d
43d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 efine SQLITE_INT
43e0: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a ERRUPT 9 /*
43f0: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 Operation termi
4400: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 nated by sqlite3
4410: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 _interrupt()*/.#
4420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
4430: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f ERR 10 /
4440: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 * Some kind of d
4450: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 isk I/O error oc
4460: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e curred */.#defin
4470: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 e SQLITE_CORRUPT
4480: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 11 /* The
4490: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 database disk i
44a0: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 mage is malforme
44b0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
44c0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 ITE_NOTFOUND
44d0: 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 12 /* NOT USED
44e0: 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 . Table or recor
44f0: 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 d not found */.#
4500: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 define SQLITE_FU
4510: 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f LL 13 /
4520: 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c * Insertion fail
4530: 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 ed because datab
4540: 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 ase is full */.#
4550: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
4560: 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f NTOPEN 14 /
4570: 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e * Unable to open
4580: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
4590: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 le */.#define SQ
45a0: 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 LITE_PROTOCOL
45b0: 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 15 /* NOT USE
45c0: 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b D. Database lock
45d0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 protocol error
45e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
45f0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 E_EMPTY 16
4600: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 /* Database i
4610: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 s empty */.#defi
4620: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 ne SQLITE_SCHEMA
4630: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 17 /* Th
4640: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
4650: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 a changed */.#de
4660: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 fine SQLITE_TOOB
4670: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 IG 18 /*
4680: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 String or BLOB e
4690: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 xceeds size limi
46a0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
46b0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 ITE_CONSTRAINT
46c0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 19 /* Abort du
46d0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 e to constraint
46e0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 violation */.#de
46f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d fine SQLITE_MISM
4700: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 ATCH 20 /*
4710: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 Data type mismat
4720: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ch */.#define SQ
4730: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 LITE_MISUSE
4740: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 21 /* Library
4750: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c used incorrectl
4760: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
4770: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 ITE_NOLFS
4780: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 22 /* Uses OS
4790: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 features not sup
47a0: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a ported on host *
47b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
47c0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 _AUTH 23
47d0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 /* Authorizati
47e0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 on denied */.#de
47f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d fine SQLITE_FORM
4800: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 AT 24 /*
4810: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 Auxiliary databa
4820: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 se format error
4830: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4840: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 E_RANGE 25
4850: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 /* 2nd parame
4860: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ter to sqlite3_b
4870: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 ind out of range
4880: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4890: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 TE_NOTADB 2
48a0: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 6 /* File open
48b0: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 ed that is not a
48c0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a database file *
48d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
48e0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 _ROW 100
48f0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 /* sqlite3_ste
4900: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 p() has another
4910: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 row ready */.#de
4920: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 fine SQLITE_DONE
4930: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 101 /*
4940: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 sqlite3_step() h
4950: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 as finished exec
4960: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d uting */./* end-
4970: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a of-error-codes *
4980: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
4990: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 F: Extended Resu
49a0: 6c 74 20 43 6f 64 65 73 20 7b 46 31 30 32 32 30 lt Codes {F10220
49b0: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
49c0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
49d0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 ode} {extended e
49e0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b rror codes}.** K
49f0: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 EYWORDS: {extend
4a00: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 ed result code}
4a10: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 {extended result
4a20: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e codes}.**.** In
4a30: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e its default con
4a40: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 figuration, SQLi
4a50: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 te API routines
4a60: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 return one of 26
4a70: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c integer.** [SQL
4a80: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 ITE_OK | result
4a90: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 codes]. However
4aa0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 , experience has
4ab0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 shown that many
4ac0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 of.** these res
4ad0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f ult codes are to
4ae0: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 o coarse-grained
4af0: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 . They do not p
4b00: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 rovide as.** muc
4b10: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 h information ab
4b20: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 out problems as
4b30: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 programmers migh
4b40: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 t like. In an e
4b50: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 ffort to.** addr
4b60: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 ess this, newer
4b70: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
4b80: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e te (version 3.3.
4b90: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 8 and later) inc
4ba0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 lude.** support
4bb0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 for additional r
4bc0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 esult codes that
4bd0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 provide more de
4be0: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 tailed informati
4bf0: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f on.** about erro
4c00: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 rs. The extended
4c10: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 result codes ar
4c20: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 e enabled or dis
4c30: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 abled.** on a pe
4c40: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 r database conne
4c50: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e ction basis usin
4c60: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 g the.** [sqlite
4c70: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 3_extended_resul
4c80: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a t_codes()] API..
4c90: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 **.** Some of th
4ca0: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 e available exte
4cb0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
4cc0: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 s are listed her
4cd0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 e..** One may ex
4ce0: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 pect the number
4cf0: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 of extended resu
4d00: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 lt codes will be
4d10: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 expand.** over
4d20: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 time. Software
4d30: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 that uses extend
4d40: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 ed result codes
4d50: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a should expect.**
4d60: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 to see new resu
4d70: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 lt codes in futu
4d80: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
4d90: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 QLite..**.** The
4da0: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c SQLITE_OK resul
4db0: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 t code will neve
4dc0: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 r be extended.
4dd0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a It will always.*
4de0: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 * be exactly zer
4df0: 6f 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 o..**.** INVARIA
4e00: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 NTS:.**.** {F102
4e10: 32 33 7d 20 54 68 65 20 73 79 6d 62 6f 6c 69 63 23} The symbolic
4e20: 20 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 74 name for an ext
4e30: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
4e40: 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 73 e shall contains
4e50: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 .** a r
4e60: 65 6c 61 74 65 64 20 70 72 69 6d 61 72 79 20 72 elated primary r
4e70: 65 73 75 6c 74 20 63 6f 64 65 20 61 73 20 61 20 esult code as a
4e80: 70 72 65 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 46 prefix..**.** {F
4e90: 31 30 32 32 34 7d 20 50 72 69 6d 61 72 79 20 72 10224} Primary r
4ea0: 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 esult code names
4eb0: 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 61 shall contain a
4ec0: 20 73 69 6e 67 6c 65 20 22 5f 22 20 63 68 61 72 single "_" char
4ed0: 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 acter..**.** {F1
4ee0: 30 32 32 35 7d 20 45 78 74 65 6e 64 65 64 20 72 0225} Extended r
4ef0: 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 esult code names
4f00: 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 shall contain t
4f10: 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 wo or more "_" c
4f20: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a haracters..**.**
4f30: 20 7b 46 31 30 32 32 36 7d 20 54 68 65 20 6e 75 {F10226} The nu
4f40: 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20 61 meric value of a
4f50: 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c n extended resul
4f60: 74 20 63 6f 64 65 20 73 68 61 6c 6c 20 63 6f 6e t code shall con
4f70: 74 61 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 tain the.**
4f80: 20 20 20 20 20 6e 75 6d 65 72 69 63 20 76 61 6c numeric val
4f90: 75 65 20 6f 66 20 69 74 73 20 63 6f 72 72 65 73 ue of its corres
4fa0: 70 6f 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 ponding primary
4fb0: 72 65 73 75 6c 74 20 63 6f 64 65 20 69 6e 0a 2a result code in.*
4fc0: 2a 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6c * its l
4fd0: 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 east significant
4fe0: 20 38 20 62 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 8 bits..*/.#def
4ff0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5000: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 _READ
5010: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5020: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
5030: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5040: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 SHORT_READ
5050: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
5060: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (2<<8)).#defin
5070: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 e SQLITE_IOERR_W
5080: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 RITE
5090: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
50a0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (3<<8)).#define
50b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 SQLITE_IOERR_FS
50c0: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 YNC
50d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
50e0: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (4<<8)).#define
50f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 SQLITE_IOERR_DIR
5100: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 _FSYNC (
5110: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5120: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 5<<8)).#define S
5130: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e QLITE_IOERR_TRUN
5140: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 CATE (S
5150: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 QLITE_IOERR | (6
5160: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5170: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 LITE_IOERR_FSTAT
5180: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
5190: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c LITE_IOERR | (7<
51a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
51b0: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b ITE_IOERR_UNLOCK
51c0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
51d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c ITE_IOERR | (8<<
51e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
51f0: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 TE_IOERR_RDLOCK
5200: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
5210: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 TE_IOERR | (9<<8
5220: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5230: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 E_IOERR_DELETE
5240: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5250: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 E_IOERR | (10<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 E_IOERR_BLOCKED
5280: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 E_IOERR | (11<<8
52a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
52b0: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 E_IOERR_NOMEM
52c0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
52d0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 E_IOERR | (12<<8
52e0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
52f0: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 E_IOERR_ACCESS
5300: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5310: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 E_IOERR | (13<<8
5320: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5330: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 E_IOERR_CHECKRES
5340: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 ERVEDLOCK (SQLIT
5350: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 E_IOERR | (14<<8
5360: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ))../*.** CAPI3R
5370: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 EF: Flags For Fi
5380: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f le Open Operatio
5390: 6e 73 20 7b 46 31 30 32 33 30 7d 0a 2a 2a 0a 2a ns {F10230}.**.*
53a0: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 * These bit valu
53b0: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 es are intended
53c0: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a for use in the.*
53d0: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 * 3rd parameter
53e0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
53f0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 open_v2()] inter
5400: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 face and.** in t
5410: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
5420: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 to the xOpen me
5430: 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b thod of the.** [
5440: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
5450: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ect..*/.#define
5460: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
5470: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 ONLY 0x0
5480: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 0000001.#define
5490: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
54a0: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 WRITE 0x0
54b0: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 0000002.#define
54c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
54d0: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 TE 0x0
54e0: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 0000004.#define
54f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
5500: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 TEONCLOSE 0x0
5510: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 0000008.#define
5520: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
5530: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 USIVE 0x0
5540: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 0000010.#define
5550: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e SQLITE_OPEN_MAIN
5560: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 _DB 0x0
5570: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 0000100.#define
5580: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
5590: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 _DB 0x0
55a0: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 0000200.#define
55b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e SQLITE_OPEN_TRAN
55c0: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 SIENT_DB 0x0
55d0: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 0000400.#define
55e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e SQLITE_OPEN_MAIN
55f0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 _JOURNAL 0x0
5600: 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 0000800.#define
5610: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
5620: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 _JOURNAL 0x0
5630: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 0001000.#define
5640: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a SQLITE_OPEN_SUBJ
5650: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 OURNAL 0x0
5660: 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 0002000.#define
5670: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 SQLITE_OPEN_MAST
5680: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 ER_JOURNAL 0x0
5690: 30 30 30 34 30 30 30 0a 23 64 65 66 69 6e 65 20 0004000.#define
56a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
56b0: 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 TEX 0x0
56c0: 30 30 30 38 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 0008000../*.** C
56d0: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 API3REF: Device
56e0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 Characteristics
56f0: 7b 46 31 30 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 {F10240}.**.** T
5700: 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69 he xDeviceCapabi
5710: 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 lities method of
5720: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f the [sqlite3_io
5730: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a _methods].** obj
5740: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 ect returns an i
5750: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 nteger which is
5760: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 a vector of the
5770: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c these.** bit val
5780: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 ues expressing I
5790: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 /O characteristi
57a0: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 cs of the mass s
57b0: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 torage.** device
57c0: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 that holds the
57d0: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 file that the [s
57e0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
57f0: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e s].** refers to.
5800: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 .**.** The SQLIT
5810: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 E_IOCAP_ATOMIC p
5820: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
5830: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 at all writes of
5840: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 .** any size are
5850: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
5860: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
5870: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d Cnnn values.** m
5880: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 ean that writes
5890: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 of blocks that a
58a0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 re nnn bytes in
58b0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 size and.** are
58c0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 aligned to an ad
58d0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 dress which is a
58e0: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 n integer multip
58f0: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 le of.** nnn are
5900: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
5910: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
5920: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 APPEND value mea
5930: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 ns.** that when
5940: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
5950: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 to a file, the
5960: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
5970: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 .** first then t
5980: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 he size of the f
5990: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c ile is extended,
59a0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 never the other
59b0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 .** way around.
59c0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
59d0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f P_SEQUENTIAL pro
59e0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
59f0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
5a00: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 is written to di
5a10: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f sk in the same o
5a20: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a rder as calls.**
5a30: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f to xWrite()..*/
5a40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5a50: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 IOCAP_ATOMIC
5a60: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
5a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5a80: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 IOCAP_ATOMIC512
5a90: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
5aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5ab0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 IOCAP_ATOMIC1K
5ac0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
5ad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5ae0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 IOCAP_ATOMIC2K
5af0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0x00000008
5b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5b10: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 IOCAP_ATOMIC4K
5b20: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0x00000010
5b30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5b40: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 IOCAP_ATOMIC8K
5b50: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0x00000020
5b60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5b70: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 IOCAP_ATOMIC16K
5b80: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0x00000040
5b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5ba0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 IOCAP_ATOMIC32K
5bb0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0x00000080
5bc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5bd0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 IOCAP_ATOMIC64K
5be0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0x00000100
5bf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5c00: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e IOCAP_SAFE_APPEN
5c10: 44 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 D 0x00000200
5c20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5c30: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c IOCAP_SEQUENTIAL
5c40: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0x00000400
5c50: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
5c60: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c : File Locking L
5c70: 65 76 65 6c 73 20 7b 46 31 30 32 35 30 7d 0a 2a evels {F10250}.*
5c80: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 *.** SQLite uses
5c90: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e one of these in
5ca0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 teger values as
5cb0: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 the second.** ar
5cc0: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 gument to calls
5cd0: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 it makes to the
5ce0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c xLock() and xUnl
5cf0: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a ock() methods.**
5d00: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f of an [sqlite3_
5d10: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
5d20: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ct..*/.#define S
5d30: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 QLITE_LOCK_NONE
5d40: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 0.#defi
5d50: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 ne SQLITE_LOCK_S
5d60: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 HARED 1.#
5d70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
5d80: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 CK_RESERVED
5d90: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
5da0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 E_LOCK_PENDING
5db0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
5dc0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
5dd0: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a SIVE 4../*.*
5de0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 * CAPI3REF: Sync
5df0: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 hronization Type
5e00: 20 46 6c 61 67 73 20 7b 46 31 30 32 36 30 7d 0a Flags {F10260}.
5e10: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 **.** When SQLit
5e20: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 e invokes the xS
5e30: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 ync() method of
5e40: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 an.** [sqlite3_i
5e50: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
5e60: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 t it uses a comb
5e70: 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 ination of.** th
5e80: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 ese integer valu
5e90: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 es as the second
5ea0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
5eb0: 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 When the SQLITE
5ec0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 _SYNC_DATAONLY f
5ed0: 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 lag is used, it
5ee0: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a means that the.*
5ef0: 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e * sync operation
5f00: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 only needs to f
5f10: 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 lush data to mas
5f20: 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 s storage. Inod
5f30: 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e e.** information
5f40: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 need not be flu
5f50: 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49 54 45 shed. The SQLITE
5f60: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66 6c 61 _SYNC_NORMAL fla
5f70: 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 g means.** to us
5f80: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 e normal fsync()
5f90: 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68 65 20 semantics. The
5fa0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
5fb0: 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 flag means.** t
5fc0: 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d 58 20 73 o use Mac OS-X s
5fd0: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e tyle fullsync in
5fe0: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 stead of fsync()
5ff0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
6000: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 ITE_SYNC_NORMAL
6010: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 0x00002.#
6020: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 define SQLITE_SY
6030: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 NC_FULL
6040: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 0x00003.#define
6050: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 SQLITE_SYNC_DAT
6060: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 AONLY 0x000
6070: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 10../*.** CAPI3R
6080: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 EF: OS Interface
6090: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c Open File Handl
60a0: 65 20 7b 46 31 31 31 31 30 7d 0a 2a 2a 0a 2a 2a e {F11110}.**.**
60b0: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c An [sqlite3_fil
60c0: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 e] object repres
60d0: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c ents an open fil
60e0: 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 e in the OS.** i
60f0: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20 nterface layer.
6100: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 Individual OS i
6110: 6e 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 nterface impleme
6120: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a ntations will.**
6130: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 want to subclas
6140: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 s this object by
6150: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 appending addit
6160: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 ional fields.**
6170: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 for their own us
6180: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 e. The pMethods
6190: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e entry is a poin
61a0: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 ter to an.** [sq
61b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
61c0: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 ] object that de
61d0: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f fines methods fo
61e0: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 r performing.**
61f0: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f I/O operations o
6200: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e n the open file.
6210: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
6220: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 ct sqlite3_file
6230: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 sqlite3_file;.st
6240: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c ruct sqlite3_fil
6250: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 e {. const stru
6260: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ct sqlite3_io_me
6270: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b thods *pMethods;
6280: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 /* Methods for
6290: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f an open file */
62a0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
62b0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
62c0: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d e File Virtual M
62d0: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 46 ethods Object {F
62e0: 31 31 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 11120}.**.** Eve
62f0: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 ry file opened b
6300: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 y the [sqlite3_v
6310: 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 fs] xOpen method
6320: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a populates an.**
6330: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
6340: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 object (or, more
6350: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 commonly, a sub
6360: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 class of the.**
6370: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
6380: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f bject) with a po
6390: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
63a0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
63b0: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a ect..** This obj
63c0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 ect defines the
63d0: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 methods used to
63e0: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 perform various
63f0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 operations.** ag
6400: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 ainst the open f
6410: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 ile represented
6420: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
6430: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a file] object..**
6440: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 .** The flags ar
6450: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 gument to xSync
6460: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 may be one of [S
6470: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 QLITE_SYNC_NORMA
6480: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 L] or.** [SQLITE
6490: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 _SYNC_FULL]. Th
64a0: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 e first choice i
64b0: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 s the normal fsy
64c0: 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 nc()..** The sec
64d0: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 ond choice is a
64e0: 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 Mac OS-X style f
64f0: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 ullsync. The [S
6500: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f QLITE_SYNC_DATAO
6510: 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 NLY].** flag may
6520: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 be ORed in to i
6530: 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c ndicate that onl
6540: 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 y the data of th
6550: 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f e file.** and no
6560: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 t its inode need
6570: 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a s to be synced..
6580: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 **.** The intege
6590: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 r values to xLoc
65a0: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 k() and xUnlock(
65b0: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 ) are one of.**
65c0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
65d0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c LITE_LOCK_NONE],
65e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
65f0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a _LOCK_SHARED],.*
6600: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c * <li> [SQLITE_L
6610: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a OCK_RESERVED],.*
6620: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c * <li> [SQLITE_L
6630: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 OCK_PENDING], or
6640: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
6650: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d _LOCK_EXCLUSIVE]
6660: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c ..** </ul>.** xL
6670: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 ock() increases
6680: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 the lock. xUnloc
6690: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 k() decreases th
66a0: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 e lock..** The x
66b0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 CheckReservedLoc
66c0: 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b k() method check
66d0: 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 s whether any da
66e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
66f0: 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 n,.** either in
6700: 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 this process or
6710: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 in some other pr
6720: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e ocess, is holdin
6730: 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a g a RESERVED,.**
6740: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 PENDING, or EXC
6750: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 LUSIVE lock on t
6760: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 he file. It ret
6770: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 urns true.** if
6780: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 such a lock exis
6790: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 ts and false oth
67a0: 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 erwise..**.** Th
67b0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 e xFileControl()
67c0: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e method is a gen
67d0: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 eric interface t
67e0: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f hat allows custo
67f0: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 m.** VFS impleme
6800: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 ntations to dire
6810: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 ctly control an
6820: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 open file using
6830: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
6840: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
6850: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 interface. The
6860: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 second "op" argu
6870: 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e ment is an.** in
6880: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 teger opcode. T
6890: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
68a0: 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 t is a generic p
68b0: 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 ointer intended
68c0: 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 to.** point to a
68d0: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 structure that
68e0: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 may contain argu
68f0: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 ments or space i
6900: 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 n which to.** wr
6910: 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 ite return value
6920: 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 s. Potential us
6930: 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 es for xFileCont
6940: 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a rol() might be.*
6950: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 * functions to e
6960: 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c nable blocking l
6970: 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 ocks with timeou
6980: 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 ts, to change th
6990: 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 e.** locking str
69a0: 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 ategy (for examp
69b0: 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 le to use dot-fi
69c0: 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e le locks), to in
69d0: 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 quire.** about t
69e0: 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c he status of a l
69f0: 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b ock, or to break
6a00: 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 stale locks. T
6a10: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 he SQLite.** cor
6a20: 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f e reserves all o
6a30: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e pcodes less than
6a40: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 100 for its own
6a50: 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 use..** A [SQLI
6a60: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
6a70: 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 TE | list of opc
6a80: 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 odes] less than
6a90: 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 100 is available
6aa0: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e ..** Application
6ab0: 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 s that define a
6ac0: 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 custom xFileCont
6ad0: 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c rol method shoul
6ae0: 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a d use opcodes.**
6af0: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 greater than 10
6b00: 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 0 to avoid confl
6b10: 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 icts..**.** The
6b20: 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 xSectorSize() me
6b30: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 thod returns the
6b40: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 sector size of
6b50: 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 the.** device th
6b60: 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 at underlies the
6b70: 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 file. The sect
6b80: 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a or size is the.*
6b90: 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 * minimum write
6ba0: 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 that can be perf
6bb0: 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 ormed without di
6bc0: 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 sturbing.** othe
6bd0: 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 r bytes in the f
6be0: 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 ile. The xDevic
6bf0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 eCharacteristics
6c00: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 ().** method ret
6c10: 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f urns a bit vecto
6c20: 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 r describing beh
6c30: 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a aviors of the.**
6c40: 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 underlying devi
6c50: 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a ce:.**.** <ul>.*
6c60: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
6c70: 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 OCAP_ATOMIC].**
6c80: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
6c90: 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a AP_ATOMIC512].**
6ca0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
6cb0: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a CAP_ATOMIC1K].**
6cc0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
6cd0: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a CAP_ATOMIC2K].**
6ce0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
6cf0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a CAP_ATOMIC4K].**
6d00: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
6d10: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a CAP_ATOMIC8K].**
6d20: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
6d30: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a CAP_ATOMIC16K].*
6d40: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
6d50: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a OCAP_ATOMIC32K].
6d60: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
6d70: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d IOCAP_ATOMIC64K]
6d80: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
6d90: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
6da0: 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ND].** <li> [SQL
6db0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e ITE_IOCAP_SEQUEN
6dc0: 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a TIAL].** </ul>.*
6dd0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f *.** The SQLITE_
6de0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f IOCAP_ATOMIC pro
6df0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
6e00: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a all writes of.*
6e10: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 * any size are a
6e20: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 tomic. The SQLI
6e30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e TE_IOCAP_ATOMICn
6e40: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 nn values.** mea
6e50: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 n that writes of
6e60: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 blocks that are
6e70: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 nnn bytes in si
6e80: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c ze and.** are al
6e90: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 igned to an addr
6ea0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 ess which is an
6eb0: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 integer multiple
6ec0: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 of.** nnn are a
6ed0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 tomic. The SQLI
6ee0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
6ef0: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 PEND value means
6f00: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 .** that when da
6f10: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 ta is appended t
6f20: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 o a file, the da
6f30: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a ta is appended.*
6f40: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 * first then the
6f50: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c size of the fil
6f60: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e e is extended, n
6f70: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a ever the other.*
6f80: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 * way around. T
6f90: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
6fa0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 SEQUENTIAL prope
6fb0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a rty means that.*
6fc0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 * information is
6fd0: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b written to disk
6fe0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 in the same ord
6ff0: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 er as calls.** t
7000: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 74 o xWrite()..*/.t
7010: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
7020: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
7030: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 sqlite3_io_meth
7040: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ods;.struct sqli
7050: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b te3_io_methods {
7060: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b . int iVersion;
7070: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 . int (*xClose)
7080: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
7090: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 . int (*xRead)(
70a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 sqlite3_file*, v
70b0: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 oid*, int iAmt,
70c0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f sqlite3_int64 iO
70d0: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 fst);. int (*xW
70e0: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 rite)(sqlite3_fi
70f0: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a le*, const void*
7100: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 , int iAmt, sqli
7110: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 te3_int64 iOfst)
7120: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 ;. int (*xTrunc
7130: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ate)(sqlite3_fil
7140: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
7150: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 4 size);. int (
7160: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f *xSync)(sqlite3_
7170: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 file*, int flags
7180: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 );. int (*xFile
7190: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 Size)(sqlite3_fi
71a0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 le*, sqlite3_int
71b0: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 64 *pSize);. in
71c0: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 t (*xLock)(sqlit
71d0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a e3_file*, int);.
71e0: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 int (*xUnlock)
71f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
7200: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 int);. int (*xC
7210: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b heckReservedLock
7220: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
7230: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a int *pResOut);.
7240: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e int (*xFileCon
7250: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 trol)(sqlite3_fi
7260: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 le*, int op, voi
7270: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 d *pArg);. int
7280: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 (*xSectorSize)(s
7290: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
72a0: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 int (*xDeviceCh
72b0: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 aracteristics)(s
72c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
72d0: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d /* Additional m
72e0: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 ethods may be ad
72f0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
7300: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a leases */.};../*
7310: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 .** CAPI3REF: St
7320: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 andard File Cont
7330: 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b 46 31 31 rol Opcodes {F11
7340: 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 310}.**.** These
7350: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
7360: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 ts are opcodes f
7370: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 or the xFileCont
7380: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 rol method.** of
7390: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f the [sqlite3_io
73a0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
73b0: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 and for the [sq
73c0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
73d0: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 ol()].** interfa
73e0: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 ce..**.** The [S
73f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b QLITE_FCNTL_LOCK
7400: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 STATE] opcode is
7410: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 used for debugg
7420: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 ing. This.** op
7430: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 code causes the
7440: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
7450: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 hod to write the
7460: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f current state o
7470: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f f.** the lock (o
7480: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f ne of [SQLITE_LO
7490: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 CK_NONE], [SQLIT
74a0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a E_LOCK_SHARED],.
74b0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ** [SQLITE_LOCK_
74c0: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 RESERVED], [SQLI
74d0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d TE_LOCK_PENDING]
74e0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 , or [SQLITE_LOC
74f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a K_EXCLUSIVE]).**
7500: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 into an integer
7510: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 that the pArg a
7520: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 rgument points t
7530: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 o. This capabili
7540: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 ty.** is used du
7550: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 ring testing and
7560: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 only needs to b
7570: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e e supported when
7580: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 SQLITE_TEST.**
7590: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 is defined..*/.#
75a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
75b0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 NTL_LOCKSTATE
75c0: 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 1../*.** CA
75d0: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 PI3REF: Mutex Ha
75e0: 6e 64 6c 65 20 7b 46 31 37 31 31 30 7d 0a 2a 2a ndle {F17110}.**
75f0: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f .** The mutex mo
7600: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 dule within SQLi
7610: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 te defines [sqli
7620: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 te3_mutex] to be
7630: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 an.** abstract
7640: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 type for a mutex
7650: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 object. The SQ
7660: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 Lite core never
7670: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 looks.** at the
7680: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
7690: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 ntation of an [s
76a0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 qlite3_mutex].
76b0: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 It only.** deals
76c0: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 with pointers t
76d0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d o the [sqlite3_m
76e0: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a utex] object..**
76f0: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 .** Mutexes are
7700: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 created using [s
7710: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
7720: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 oc()]..*/.typede
7730: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
7740: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d _mutex sqlite3_m
7750: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 utex;../*.** CAP
7760: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 I3REF: OS Interf
7770: 61 63 65 20 4f 62 6a 65 63 74 20 7b 46 31 31 31 ace Object {F111
7780: 34 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 40}.**.** An ins
7790: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c tance of the sql
77a0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 ite3_vfs object
77b0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 defines the inte
77c0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a rface between.**
77d0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 the SQLite core
77e0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 and the underly
77f0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 ing operating sy
7800: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 stem. The "vfs"
7810: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 .** in the name
7820: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 of the object st
7830: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 ands for "virtua
7840: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a l file system"..
7850: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 **.** The value
7860: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 of the iVersion
7870: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c field is initial
7880: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 ly 1 but may be
7890: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 larger in.** fut
78a0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
78b0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f SQLite. Additio
78c0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 nal fields may b
78d0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 e appended to th
78e0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 is.** object whe
78f0: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 n the iVersion v
7900: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 alue is increase
7910: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 d. Note that th
7920: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f e structure.** o
7930: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 f the sqlite3_vf
7940: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 s object changes
7950: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 in the transact
7960: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 ion between.** S
7970: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
7980: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 5.9 and 3.6.0 an
7990: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 d yet the iVersi
79a0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 on field was not
79b0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a .** modified..**
79c0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 .** The szOsFile
79d0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 field is the si
79e0: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 ze of the subcla
79f0: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 ssed [sqlite3_fi
7a00: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 le].** structure
7a10: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 used by this VF
7a20: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 S. mxPathname i
7a30: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 s the maximum le
7a40: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 ngth of.** a pat
7a50: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 hname in this VF
7a60: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 S..**.** Registe
7a70: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 red sqlite3_vfs
7a80: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 objects are kept
7a90: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 on a linked lis
7aa0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 t formed by.** t
7ab0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 he pNext pointer
7ac0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
7ad0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a vfs_register()].
7ae0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
7af0: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 vfs_unregister()
7b00: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e ] interfaces man
7b10: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a age this list.**
7b20: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 in a thread-saf
7b30: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c e way. The [sql
7b40: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d ite3_vfs_find()]
7b50: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 interface.** se
7b60: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e arches the list.
7b70: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 Neither the ap
7b80: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e plication code n
7b90: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d or the VFS.** im
7ba0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f plementation sho
7bb0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 uld use the pNex
7bc0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a t pointer..**.**
7bd0: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 The pNext field
7be0: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 is the only fie
7bf0: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 ld in the sqlite
7c00: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 3_vfs.** structu
7c10: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 re that SQLite w
7c20: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e ill ever modify.
7c30: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e SQLite will on
7c40: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 ly access.** or
7c50: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c modify this fiel
7c60: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 d while holding
7c70: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 a particular sta
7c80: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 tic mutex..** Th
7c90: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
7ca0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 ould never modif
7cb0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 y anything withi
7cc0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 n the sqlite3_vf
7cd0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 s.** object once
7ce0: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 the object has
7cf0: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e been registered.
7d00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 .**.** The zName
7d10: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 field holds the
7d20: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 name of the VFS
7d30: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 module. The na
7d40: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e me must.** be un
7d50: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 ique across all
7d60: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a VFS modules..**.
7d70: 2a 2a 20 7b 46 31 31 31 34 31 7d 20 53 51 4c 69 ** {F11141} SQLi
7d80: 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 te will guarante
7d90: 65 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 e that the zFile
7da0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 name parameter t
7db0: 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 o xOpen.** is ei
7dc0: 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e ther a NULL poin
7dd0: 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 ter or string ob
7de0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 tained.** from x
7df0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 FullPathname().
7e00: 20 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 SQLite further
7e10: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a guarantees that.
7e20: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 ** the string wi
7e30: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 ll be valid and
7e40: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 unchanged until
7e50: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 xClose() is.** c
7e60: 61 6c 6c 65 64 2e 20 7b 45 4e 44 7d 20 20 42 65 alled. {END} Be
7e70: 63 61 73 75 65 20 6f 66 20 74 68 65 20 70 72 65 casue of the pre
7e80: 76 69 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c 20 vious sentense,
7e90: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 .** the [sqlite3
7ea0: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c _file] can safel
7eb0: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 y store a pointe
7ec0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 r to the.** file
7ed0: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 name if it needs
7ee0: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 to remember the
7ef0: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f filename for so
7f00: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 me reason..** If
7f10: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 the zFilename p
7f20: 61 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 arameter is xOpe
7f30: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e n is a NULL poin
7f40: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a ter then xOpen.*
7f50: 2a 20 6d 75 73 74 20 69 6e 76 69 74 65 20 69 74 * must invite it
7f60: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 s own temporary
7f70: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c name for the fil
7f80: 65 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 e. Whenever the
7f90: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 .** xFilename p
7fa0: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c arameter is NULL
7fb0: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 it will also be
7fc0: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 the case that t
7fd0: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 he.** flags para
7fe0: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 meter will inclu
7ff0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f de [SQLITE_OPEN_
8000: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a DELETEONCLOSE]..
8010: 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34 32 7d 20 54 **.** {F11142} T
8020: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
8030: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 t to xOpen() inc
8040: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 ludes all bits s
8050: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 et in.** the fla
8060: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b gs argument to [
8070: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
8080: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 )]. Or if [sqli
8090: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f te3_open()].** o
80a0: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 r [sqlite3_open1
80b0: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 6()] is used, th
80c0: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 en flags include
80d0: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 s at least.** [S
80e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
80f0: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f RITE] | [SQLITE_
8100: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 7b 45 OPEN_CREATE]. {E
8110: 4e 44 7d 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 ND}.** If xOpen(
8120: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 ) opens a file r
8130: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 ead-only then it
8140: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 sets *pOutFlags
8150: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b to.** include [
8160: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
8170: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 ONLY]. Other bi
8180: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 ts in *pOutFlags
8190: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a may be set..**.
81a0: 2a 2a 20 7b 46 31 31 31 34 33 7d 20 53 51 4c 69 ** {F11143} SQLi
81b0: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 te will also add
81c0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c one of the foll
81d0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 owing flags to t
81e0: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 he xOpen().** ca
81f0: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ll, depending on
8200: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e the object bein
8210: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 g opened:.**.**
8220: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 <ul>.** <li> [S
8230: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
8240: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 DB].** <li> [SQ
8250: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a LITE_OPEN_MAIN_J
8260: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 OURNAL].** <li>
8270: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 [SQLITE_OPEN_TE
8280: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 MP_DB].** <li>
8290: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d [SQLITE_OPEN_TEM
82a0: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c P_JOURNAL].** <l
82b0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
82c0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a _TRANSIENT_DB].*
82d0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
82e0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d OPEN_SUBJOURNAL]
82f0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
8300: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f E_OPEN_MASTER_JO
8310: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 URNAL].** </ul>
8320: 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 {END}.**.** The
8330: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 file I/O impleme
8340: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 ntation can use
8350: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 the object type
8360: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e flags to.** chan
8370: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 ge the way it de
8380: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 als with files.
8390: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e For example, an
83a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 application.**
83b0: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 that does not ca
83c0: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 re about crash r
83d0: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 ecovery or rollb
83e0: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a ack might make.*
83f0: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 * the open of a
8400: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e journal file a n
8410: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f o-op. Writes to
8420: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f this journal wo
8430: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e uld.** also be n
8440: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 o-ops, and any a
8450: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 ttempt to read t
8460: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 he journal would
8470: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 return.** SQLIT
8480: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 E_IOERR. Or the
8490: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
84a0: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 might recognize
84b0: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a that a database.
84c0: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 ** file will be
84d0: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e doing page-align
84e0: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 ed sector reads
84f0: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 and writes in a
8500: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 random.** order
8510: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 and set up its I
8520: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 /O subsystem acc
8530: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ordingly..**.**
8540: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 SQLite might als
8550: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 o add one of the
8560: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 following flags
8570: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 to the xOpen me
8580: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e thod:.**.** <ul>
8590: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
85a0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
85b0: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 OSE].** <li> [SQ
85c0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 LITE_OPEN_EXCLUS
85d0: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a IVE].** </ul>.**
85e0: 0a 2a 2a 20 7b 46 31 31 31 34 35 7d 20 54 68 65 .** {F11145} The
85f0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
8600: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 LETEONCLOSE] fla
8610: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 g means the file
8620: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 should be.** de
8630: 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 leted when it is
8640: 20 63 6c 6f 73 65 64 2e 20 20 7b 46 31 31 31 34 closed. {F1114
8650: 36 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 6} The [SQLITE_O
8660: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
8670: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 E].** will be se
8680: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 t for TEMP data
8690: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 bases, journals
86a0: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e and for subjourn
86b0: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 als..**.** {F111
86c0: 34 37 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 47} The [SQLITE_
86d0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 OPEN_EXCLUSIVE]
86e0: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 flag means the f
86f0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 ile should be op
8700: 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63 6c ened.** for excl
8710: 75 73 69 76 65 20 61 63 63 65 73 73 2e 20 20 54 usive access. T
8720: 68 69 73 20 66 6c 61 67 20 69 73 20 73 65 74 20 his flag is set
8730: 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20 65 78 for all files ex
8740: 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65 20 cept.** for the
8750: 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 main database fi
8760: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34 le..**.** {F1114
8770: 38 7d 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 8} At least szOs
8780: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 File bytes of me
8790: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 mory are allocat
87a0: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 ed by SQLite.**
87b0: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 to hold the [sq
87c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 lite3_file] stru
87d0: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 cture passed as
87e0: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 the third.** arg
87f0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 ument to xOpen.
8800: 7b 45 4e 44 7d 20 20 54 68 65 20 78 4f 70 65 6e {END} The xOpen
8810: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 method does not
8820: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f have to.** allo
8830: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 cate the structu
8840: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 re; it should ju
8850: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a st fill it in..*
8860: 2a 0a 2a 2a 20 7b 46 31 31 31 34 39 7d 20 54 68 *.** {F11149} Th
8870: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
8880: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 to xAccess() ma
8890: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 y be [SQLITE_ACC
88a0: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 ESS_EXISTS].** t
88b0: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 o test for the e
88c0: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 xistence of a fi
88d0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 le, or [SQLITE_A
88e0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d CCESS_READWRITE]
88f0: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 to.** test whet
8900: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 her a file is re
8910: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 adable and writa
8920: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f ble, or [SQLITE_
8930: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 ACCESS_READ].**
8940: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 to test whether
8950: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 a file is at lea
8960: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 7b 45 4e st readable. {EN
8970: 44 7d 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e D} The file can
8980: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f be a.** directo
8990: 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 35 ry..**.** {F1115
89a0: 30 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 0} SQLite will a
89b0: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 lways allocate a
89c0: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 t least mxPathna
89d0: 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 me+1 bytes for t
89e0: 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 he.** output buf
89f0: 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d fer xFullPathnam
8a00: 65 2e 20 7b 46 31 31 31 35 31 7d 20 54 68 65 20 e. {F11151} The
8a10: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 exact size of th
8a20: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a e output buffer.
8a30: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 ** is also passe
8a40: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 d as a parameter
8a50: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 to both method
8a60: 73 2e 20 7b 45 4e 44 7d 20 20 49 66 20 74 68 65 s. {END} If the
8a70: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a output buffer.*
8a80: 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 * is not large e
8a90: 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 nough, [SQLITE_C
8aa0: 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 ANTOPEN] should
8ab0: 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e be returned. Sin
8ac0: 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 ce this is.** ha
8ad0: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c ndled as a fatal
8ae0: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 error by SQLite
8af0: 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 , vfs implementa
8b00: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 tions should end
8b10: 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 eavor.** to prev
8b20: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 ent this by sett
8b30: 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 ing mxPathname t
8b40: 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 o a sufficiently
8b50: 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a large value..**
8b60: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e .** The xRandomn
8b70: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c ess(), xSleep(),
8b80: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d and xCurrentTim
8b90: 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a e() interfaces.*
8ba0: 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 * are not strict
8bb0: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 ly a part of the
8bc0: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 filesystem, but
8bd0: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 they are.** inc
8be0: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 luded in the VFS
8bf0: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 structure for c
8c00: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 ompleteness..**
8c10: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 The xRandomness(
8c20: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d ) function attem
8c30: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 pts to return nB
8c40: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 ytes bytes.** of
8c50: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 good-quality ra
8c60: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f ndomness into zO
8c70: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 ut. The return
8c80: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 value is.** the
8c90: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 actual number of
8ca0: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d bytes of random
8cb0: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a ness obtained..*
8cc0: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d * The xSleep() m
8cd0: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 ethod causes the
8ce0: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 calling thread
8cf0: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a to sleep for at.
8d00: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d ** least the num
8d10: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f ber of microseco
8d20: 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 nds given. The
8d30: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a xCurrentTime().*
8d40: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 * method returns
8d50: 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 a Julian Day Nu
8d60: 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 mber for the cur
8d70: 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 rent date and ti
8d80: 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 me..*/.typedef s
8d90: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 truct sqlite3_vf
8da0: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 s sqlite3_vfs;.s
8db0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 truct sqlite3_vf
8dc0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 s {. int iVersi
8dd0: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f on; /
8de0: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 * Structure vers
8df0: 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 ion number */.
8e00: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 int szOsFile;
8e10: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 /* Size
8e20: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 of subclassed s
8e30: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 qlite3_file */.
8e40: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b int mxPathname;
8e50: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
8e60: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 imum file pathna
8e70: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 me length */. s
8e80: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 qlite3_vfs *pNex
8e90: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 t; /* Next
8ea0: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a registered VFS *
8eb0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
8ec0: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 zName; /*
8ed0: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 Name of this vir
8ee0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d tual file system
8ef0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 */. void *pApp
8f00: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f Data; /
8f10: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 * Pointer to app
8f20: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 lication-specifi
8f30: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 c data */. int
8f40: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 (*xOpen)(sqlite3
8f50: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
8f60: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 r *zName, sqlite
8f70: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 3_file*,.
8f80: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 int flag
8f90: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 s, int *pOutFlag
8fa0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c s);. int (*xDel
8fb0: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ete)(sqlite3_vfs
8fc0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
8fd0: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 Name, int syncDi
8fe0: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 r);. int (*xAcc
8ff0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ess)(sqlite3_vfs
9000: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
9010: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c Name, int flags,
9020: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a int *pResOut);.
9030: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 int (*xFullPat
9040: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 hname)(sqlite3_v
9050: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
9060: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 *zName, int nOut
9070: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 , char *zOut);.
9080: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e void *(*xDlOpen
9090: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
90a0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c const char *zFil
90b0: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 ename);. void (
90c0: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 *xDlError)(sqlit
90d0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 e3_vfs*, int nBy
90e0: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 te, char *zErrMs
90f0: 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 g);. void *(*xD
9100: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 lSym)(sqlite3_vf
9110: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 s*,void*, const
9120: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a char *zSymbol);.
9130: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 void (*xDlClos
9140: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
9150: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 void*);. int (
9160: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 *xRandomness)(sq
9170: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 lite3_vfs*, int
9180: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 nByte, char *zOu
9190: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 t);. int (*xSle
91a0: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ep)(sqlite3_vfs*
91b0: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e , int microsecon
91c0: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 ds);. int (*xCu
91d0: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 rrentTime)(sqlit
91e0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a e3_vfs*, double*
91f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c );. int (*xGetL
9200: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 astError)(sqlite
9210: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 3_vfs*, int, cha
9220: 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 r *);. /* New f
9230: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 ields may be app
9240: 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 ended in figure
9250: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 versions. The i
9260: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c Version. ** val
9270: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e ue will incremen
9280: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 t whenever this
9290: 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a happens. */.};..
92a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
92b0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 Flags for the xA
92c0: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 ccess VFS method
92d0: 20 7b 46 31 31 31 39 30 7d 0a 2a 2a 0a 2a 2a 20 {F11190}.**.**
92e0: 7b 46 31 31 31 39 31 7d 20 54 68 65 73 65 20 69 {F11191} These i
92f0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
9300: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 can be used as
9310: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
9320: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 ter to.** the xA
9330: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 ccess method of
9340: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d an [sqlite3_vfs]
9350: 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20 object. {END}
9360: 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a They determine.*
9370: 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 * what kind of p
9380: 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 ermissions the x
9390: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 Access method is
93a0: 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a looking for..**
93b0: 20 7b 46 31 31 31 39 32 7d 20 57 69 74 68 20 53 {F11192} With S
93c0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
93d0: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 STS, the xAccess
93e0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c method.** simpl
93f0: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 y checks whether
9400: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 the file exists
9410: 2e 0a 2a 2a 20 7b 46 31 31 31 39 33 7d 20 57 69 ..** {F11193} Wi
9420: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
9430: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 _READWRITE, the
9440: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a xAccess method.*
9450: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 * checks whether
9460: 20 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 the file is bot
9470: 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 h readable and w
9480: 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 7b 46 31 31 ritable..** {F11
9490: 31 39 34 7d 20 57 69 74 68 20 53 51 4c 49 54 45 194} With SQLITE
94a0: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 _ACCESS_READ, th
94b0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
94c0: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 .** checks wheth
94d0: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 er the file is r
94e0: 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 eadable..*/.#def
94f0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ine SQLITE_ACCES
9500: 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 S_EXISTS 0.#d
9510: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 efine SQLITE_ACC
9520: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a ESS_READWRITE 1.
9530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
9540: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 CCESS_READ
9550: 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 2../*.** CAPI3RE
9560: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 F: Initialize Th
9570: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 e SQLite Library
9580: 20 7b 46 31 30 31 33 30 7d 0a 2a 2a 0a 2a 2a 20 {F10130}.**.**
9590: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
95a0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 ialize() routine
95b0: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 initializes the
95c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 .** SQLite libra
95d0: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 ry. The sqlite3
95e0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 _shutdown() rout
95f0: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 ine.** deallocat
9600: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 es any resources
9610: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 that were alloc
9620: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ated by sqlite3_
9630: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a initialize()..**
9640: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 .** A call to sq
9650: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
9660: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 () is an "effect
9670: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 ive" call if it
9680: 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 is.** the first
9690: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 time sqlite3_ini
96a0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 tialize() is inv
96b0: 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 oked during the
96c0: 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 lifetime of.** t
96d0: 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 he process, or i
96e0: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 f it is the firs
96f0: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 t time sqlite3_i
9700: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 nitialize() is i
9710: 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 nvoked.** follow
9720: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 ing a call to sq
9730: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
9740: 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 . Only an effec
9750: 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 tive call.** of
9760: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9770: 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e ze() does any in
9780: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 itialization. A
9790: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a ll other calls.*
97a0: 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e * are harmless n
97b0: 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f o-ops..**.** Amo
97c0: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c ng other things,
97d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
97e0: 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f ize() shall invo
97f0: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 ke.** sqlite3_os
9800: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 _init(). Simila
9810: 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 rly, sqlite3_shu
9820: 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c tdown().** shall
9830: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
9840: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 os_end()..**.**
9850: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
9860: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 ialize() routine
9870: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f returns SQLITE_
9880: 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a OK on success..*
9890: 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 * If for some re
98a0: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e ason, sqlite3_in
98b0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e itialize() is un
98c0: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 able to initiali
98d0: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 ze.** the librar
98e0: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 y (perhaps it is
98f0: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
9900: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 ate a needed res
9910: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 ource such.** as
9920: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 a mutex) it ret
9930: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 urns an [error c
9940: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 ode] other than
9950: 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a SQLITE_OK..**.**
9960: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 The sqlite3_ini
9970: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e tialize() routin
9980: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 e is called inte
9990: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f rnally by many o
99a0: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 ther.** SQLite i
99b0: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 nterfaces so tha
99c0: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e t an application
99d0: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f usually does no
99e0: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 t need to.** inv
99f0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 oke sqlite3_init
9a00: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c ialize() directl
9a10: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c y. For example,
9a20: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
9a30: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 ].** calls sqlit
9a40: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
9a50: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 so the SQLite li
9a60: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 brary will be au
9a70: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 tomatically.** i
9a80: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 nitialized when
9a90: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
9aa0: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 is called if it
9ab0: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 has not be init
9ac0: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 ialized.** alrea
9ad0: 64 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66 dy. However, if
9ae0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
9af0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c led with the SQL
9b00: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 ITE_OMIT_AUTOINI
9b10: 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d T.** compile-tim
9b20: 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 e option, then t
9b30: 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c he automatic cal
9b40: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e ls to sqlite3_in
9b50: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 itialize().** ar
9b60: 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 e omitted and th
9b70: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
9b80: 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f st call sqlite3_
9b90: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 initialize() dir
9ba0: 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 ectly.** prior t
9bb0: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 o using any othe
9bc0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
9bd0: 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d ce. For maximum
9be0: 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a portability,.**
9bf0: 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 it is recommend
9c00: 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 ed that applicat
9c10: 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f ions always invo
9c20: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ke sqlite3_initi
9c30: 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 alize().** direc
9c40: 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 tly prior to usi
9c50: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c ng any other SQL
9c60: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ite interface.
9c70: 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a Future releases.
9c80: 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 ** of SQLite may
9c90: 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 require this.
9ca0: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
9cb0: 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 the behavior exh
9cc0: 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 ibited.** when S
9cd0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
9ce0: 64 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4f 4d d with SQLITE_OM
9cf0: 49 54 5f 41 55 54 4f 49 4e 49 54 20 6d 69 67 68 IT_AUTOINIT migh
9d00: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 t become the.**
9d10: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 default behavior
9d20: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 in some future
9d30: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
9d40: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c e..**.** The sql
9d50: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 ite3_os_init() r
9d60: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 outine does oper
9d70: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 ating-system spe
9d80: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c cific.** initial
9d90: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 ization of the S
9da0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 QLite library.
9db0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 The sqlite3_os_e
9dc0: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 nd().** routine
9dd0: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 undoes the effec
9de0: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f t of sqlite3_os_
9df0: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c init(). Typical
9e00: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 tasks.** perfor
9e10: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 med by these rou
9e20: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c tines include al
9e30: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c location or deal
9e40: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 location.** of s
9e50: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c tatic resources,
9e60: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
9e70: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 of global variab
9e80: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 les,.** setting
9e90: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 up a default [sq
9ea0: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c lite3_vfs] modul
9eb0: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 e, or setting up
9ec0: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f .** a default co
9ed0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e nfiguration usin
9ee0: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 g [sqlite3_confi
9ef0: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 g()]..**.** The
9f00: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
9f10: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 ld never invoke
9f20: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f either sqlite3_o
9f30: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 s_init().** or s
9f40: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 qlite3_os_end()
9f50: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 directly. The a
9f60: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
9f70: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a d only invoke.**
9f80: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
9f90: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ize() and sqlite
9fa0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 3_shutdown(). T
9fb0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e he sqlite3_os_in
9fc0: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 it().** interfac
9fd0: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f e is called auto
9fe0: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c matically by sql
9ff0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
a000: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ) and.** sqlite3
a010: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c _os_end() is cal
a020: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 led by sqlite3_s
a030: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 hutdown(). Appr
a040: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 opriate.** imple
a050: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 mentations for s
a060: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
a070: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f and sqlite3_os_
a080: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 end().** are bui
a090: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 lt into SQLite w
a0a0: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c hen it is compil
a0b0: 65 64 20 66 6f 72 20 75 6e 69 78 2c 20 77 69 6e ed for unix, win
a0c0: 64 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a dows, or os/2..*
a0d0: 2a 20 57 68 65 6e 20 62 75 69 6c 74 20 66 6f 72 * When built for
a0e0: 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 other platforms
a0f0: 20 28 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 (using the SQLI
a100: 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 20 63 6f TE_OS_OTHER=1 co
a110: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 mpile-time.** op
a120: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 tion) the applic
a130: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c ation must suppl
a140: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 y a suitable imp
a150: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a lementation for.
a160: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e ** sqlite3_os_in
a170: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 it() and sqlite3
a180: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 _os_end(). An a
a190: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c pplication-suppl
a1a0: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 ied.** implement
a1b0: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 ation of sqlite3
a1c0: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 _os_init() or sq
a1d0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
a1e0: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 53 51 * must return SQ
a1f0: 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 LITE_OK on succe
a200: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 ss and some othe
a210: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 r [error code] u
a220: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a pon.** failure..
a230: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 */.int sqlite3_i
a240: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b nitialize(void);
a250: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 .int sqlite3_shu
a260: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 tdown(void);.int
a270: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
a280: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 (void);.int sqli
a290: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 te3_os_end(void)
a2a0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
a2b0: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 F: Configuring T
a2c0: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 he SQLite Librar
a2d0: 79 20 7b 46 31 30 31 34 35 7d 0a 2a 2a 0a 2a 2a y {F10145}.**.**
a2e0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e The sqlite3_con
a2f0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
a300: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 is used to make
a310: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 global configura
a320: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 tion.** changes
a330: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 to SQLite in ord
a340: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 er to tune SQLit
a350: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 e to the specifi
a360: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 c needs of.** th
a370: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 e application.
a380: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 The default conf
a390: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 iguration is rec
a3a0: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 ommended for mos
a3b0: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e t.** application
a3c0: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f s and so this ro
a3d0: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 utine is usually
a3e0: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 not necessary.
a3f0: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 It is.** provid
a400: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 ed to support ra
a410: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 re applications
a420: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 with unusual nee
a430: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ds..**.** The sq
a440: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
a450: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 nterface is not
a460: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 threadsafe. The
a470: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 application.**
a480: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 must insure that
a490: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 no other SQLite
a4a0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
a4b0: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 invoked by other
a4c0: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c .** threads whil
a4d0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
a4e0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 () is running.
a4f0: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c Furthermore, sql
a500: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a ite3_config().**
a510: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 may only be inv
a520: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 oked prior to li
a530: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 brary initializa
a540: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 tion using.** [s
a550: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
a560: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 e()] or after sh
a570: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 utdown by [sqlit
a580: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a e3_shutdown()]..
a590: 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 ** Note, however
a5a0: 2c 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63 , that sqlite3_c
a5b0: 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 onfig() can be c
a5c0: 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 alled as part of
a5d0: 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e the.** implemen
a5e0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 tation of an app
a5f0: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
a600: 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 [sqlite3_os_ini
a610: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 t()]..**.** The
a620: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
a630: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 o sqlite3_config
a640: 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 () is an integer
a650: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
a660: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 IG_SINGLETHREAD
a670: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 | configuration
a680: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 option] that det
a690: 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 ermines.** what
a6a0: 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 property of SQLi
a6b0: 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 te is to be conf
a6c0: 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 igured. Subsequ
a6d0: 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a ent arguments.**
a6e0: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 vary depending
a6f0: 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 on the [SQLITE_C
a700: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
a710: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 AD | configurati
a720: 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e on option].** in
a730: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
a740: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 ent..**.** When
a750: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 a configuration
a760: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 option is set, s
a770: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
a780: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f returns SQLITE_O
a790: 4b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 K..** If the opt
a7a0: 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f ion is unknown o
a7b0: 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 r SQLite is unab
a7c0: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 le to set the op
a7d0: 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 tion.** then thi
a7e0: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
a7f0: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 s a non-zero [er
a800: 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e ror code]..*/.in
a810: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 t sqlite3_config
a820: 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a (int, ...);../*.
a830: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d ** CAPI3REF: Mem
a840: 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 ory Allocation R
a850: 6f 75 74 69 6e 65 73 20 7b 46 31 30 31 35 35 7d outines {F10155}
a860: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e .**.** An instan
a870: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
a880: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e t defines the in
a890: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 terface between
a8a0: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f SQLite.** and lo
a8b0: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 w-level memory a
a8c0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
a8d0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f es..**.** This o
a8e0: 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e bject is used in
a8f0: 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 only one place
a900: 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e in the SQLite in
a910: 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f terface..** A po
a920: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
a930: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
a940: 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d ect is the argum
a950: 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ent to.** [sqlit
a960: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 e3_config()] whe
a970: 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 n the configurat
a980: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a ion option is.**
a990: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
a9a0: 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 MALLOC]. By cre
a9b0: 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 ating an instanc
a9c0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
a9d0: 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 .** and passing
a9e0: 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 it to [sqlite3_c
a9f0: 6f 6e 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20 onfig()] during
aa00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 configuration, a
aa10: 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e n.** application
aa20: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 can specify an
aa30: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f alternative memo
aa40: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 ry allocation su
aa50: 62 73 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 bsystem.** for S
aa60: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 QLite to use for
aa70: 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 all of its dyna
aa80: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 mic memory needs
aa90: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
aaa0: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 t SQLite comes w
aab0: 69 74 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d ith a built-in m
aac0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
aad0: 74 68 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 that is.** perfe
aae0: 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f ctly adequate fo
aaf0: 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 r the overwhelmi
ab00: 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 ng majority of a
ab10: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 pplications.** a
ab20: 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a nd that this obj
ab30: 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 ect is only usef
ab40: 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e ul to a tiny min
ab50: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 ority of applica
ab60: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 tions.** with sp
ab70: 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 ecialized memory
ab80: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 allocation requ
ab90: 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 irements. This
aba0: 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 object is.** als
abb0: 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 o used during te
abc0: 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 sting of SQLite
abd0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 in order to spec
abe0: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 ify an alternati
abf0: 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c ve.** memory all
ac00: 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 ocator that simu
ac10: 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 lates memory out
ac20: 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 -of-memory condi
ac30: 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 tions in.** orde
ac40: 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 r to verify that
ac50: 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 SQLite recovers
ac60: 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d gracefully from
ac70: 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 such.** conditi
ac80: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ons..**.** The x
ac90: 4d 61 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 Malloc, xFree, a
aca0: 6e 64 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 nd xRealloc meth
acb0: 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 ods must work li
acc0: 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 ke the.** malloc
acd0: 28 29 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 (), free(), and
ace0: 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 realloc() functi
acf0: 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 ons from the sta
ad00: 6e 64 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a ndard library..*
ad10: 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c *.** xSize shoul
ad20: 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c d return the all
ad30: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 ocated size of a
ad40: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
ad50: 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 on.** previously
ad60: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 obtained from x
ad70: 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c Malloc or xReall
ad80: 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 oc. The allocat
ad90: 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c ed size.** is al
ada0: 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 ways at least as
adb0: 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 big as the requ
adc0: 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d ested size but m
add0: 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a ay be larger..**
ade0: 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 .** The xRoundup
adf0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
ae00: 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 what would be th
ae10: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
ae20: 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 of.** a memory
ae30: 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e allocation given
ae40: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 a particular re
ae50: 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d quested size. M
ae60: 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c ost memory.** al
ae70: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 locators round u
ae80: 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 p memory allocat
ae90: 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f ions at least to
aea0: 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 the next multip
aeb0: 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d le.** of 8. Som
aec0: 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 e allocators rou
aed0: 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 nd up to a large
aee0: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f r multiple or to
aef0: 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a a power of 2..*
af00: 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d *.** The xInit m
af10: 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 ethod initialize
af20: 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c s the memory all
af30: 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 ocator. (For ex
af40: 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 ample,.** it mig
af50: 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 ht allocate any
af60: 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 require mutexes
af70: 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e or initialize in
af80: 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 ternal data.** s
af90: 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 tructures. The
afa0: 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 xShutdown method
afb0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 is invoked (ind
afc0: 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b irectly) by.** [
afd0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
afe0: 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 ()] and should d
aff0: 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 eallocate any re
b000: 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 sources acquired
b010: 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 .** by xInit. T
b020: 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e he pAppData poin
b030: 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 ter is used as t
b040: 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 he only paramete
b050: 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e r to.** xInit an
b060: 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a d xShutdown..*/.
b070: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
b080: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
b090: 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d ds sqlite3_mem_m
b0a0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 ethods;.struct s
b0b0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
b0c0: 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 ds {. void *(*x
b0d0: 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 Malloc)(int);
b0e0: 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 /* Memory
b0f0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 allocation funct
b100: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a ion */. void (*
b110: 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 xFree)(void*);
b120: 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 /* Free
b130: 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 a prior allocati
b140: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a on */. void *(*
b150: 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c xRealloc)(void*,
b160: 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 int); /* Resize
b170: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a an allocation *
b180: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 /. int (*xSize)
b190: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
b1a0: 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 /* Return the
b1b0: 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f size of an allo
b1c0: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 cation */. int
b1d0: 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 (*xRoundup)(int)
b1e0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f ; /* Ro
b1f0: 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 und up request s
b200: 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f ize to allocatio
b210: 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 n size */. int
b220: 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b (*xInit)(void*);
b230: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e /* In
b240: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d itialize the mem
b250: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f ory allocator */
b260: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 . void (*xShutd
b270: 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 own)(void*);
b280: 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a /* Deinitializ
b290: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c e the memory all
b2a0: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 ocator */. void
b2b0: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 *pAppData;
b2c0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 /* Ar
b2d0: 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 gument to xInit(
b2e0: 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 ) and xShutdown(
b2f0: 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ) */.};../*.** C
b300: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 API3REF: Configu
b310: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b ration Options {
b320: 46 31 30 31 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 F10160}.**.** Th
b330: 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ese constants ar
b340: 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 e the available
b350: 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 integer configur
b360: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 ation options th
b370: 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 at.** can be pas
b380: 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 sed as the first
b390: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
b3a0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
b3b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
b3c0: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 *.** <dl>.** <dt
b3d0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
b3e0: 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e INGLETHREAD</dt>
b3f0: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
b400: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
b410: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
b420: 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 This option disa
b430: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 bles.** all mute
b440: 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 xing and puts SQ
b450: 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 Lite into a mode
b460: 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e where it can on
b470: 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 ly be used.** by
b480: 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 a single thread
b490: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
b4a0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
b4b0: 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a ULTITHREAD</dt>.
b4c0: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 ** <dd>There are
b4d0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f no arguments to
b4e0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 this option. T
b4f0: 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 his option disab
b500: 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 les.** mutexing
b510: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
b520: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 nection] and [pr
b530: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
b540: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 ] objects..** Th
b550: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 e application is
b560: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
b570: 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 serializing acc
b580: 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 ess to.** [datab
b590: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d ase connections]
b5a0: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
b5b0: 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 tatements]. But
b5c0: 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a other mutexes.*
b5d0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f * are enabled so
b5e0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
b5f0: 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 l be safe to use
b600: 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 in a multi-thre
b610: 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d aded.** environm
b620: 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ent.</dd>.**.**
b630: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
b640: 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 G_SERIALIZED</dt
b650: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
b660: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
b670: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
b680: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 This option ena
b690: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 bles.** all mute
b6a0: 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 xes including th
b6b0: 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d e recursive.** m
b6c0: 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 utexes on [datab
b6d0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
b6e0: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
b6f0: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 atement] objects
b700: 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 ..** In this mod
b710: 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 e (which is the
b720: 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c default when SQL
b730: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
b740: 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f with.** [SQLITE_
b750: 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 THREADSAFE=1]) t
b760: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
b770: 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 y will itself se
b780: 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a rialize access.*
b790: 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 * to [database c
b7a0: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 onnections] and
b7b0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
b7c0: 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 ents] so that th
b7d0: 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e e.** application
b7e0: 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 is free to use
b7f0: 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 the same [databa
b800: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f se connection] o
b810: 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 r the.** same [p
b820: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
b830: 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 t] in different
b840: 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 threads at the s
b850: 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 ame time..**.**
b860: 3c 70 3e 54 68 69 73 20 63 6f 6e 66 69 67 75 72 <p>This configur
b870: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 6d 65 72 ation option mer
b880: 65 6c 79 20 73 65 74 73 20 74 68 65 20 64 65 66 ely sets the def
b890: 61 75 6c 74 20 6d 75 74 65 78 20 0a 2a 2a 20 62 ault mutex .** b
b8a0: 65 68 61 76 69 6f 72 20 74 6f 20 73 65 72 69 61 ehavior to seria
b8b0: 6c 69 7a 65 20 61 63 63 65 73 73 20 74 6f 20 5b lize access to [
b8c0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
b8d0: 69 6f 6e 73 5d 2e 20 20 49 6e 64 69 76 69 64 75 ions]. Individu
b8e0: 61 6c 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 al.** [database
b8f0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 63 61 6e connections] can
b900: 20 6f 76 65 72 72 69 64 65 20 74 68 69 73 20 73 override this s
b910: 65 74 74 69 6e 67 0a 2a 2a 20 75 73 69 6e 67 20 etting.** using
b920: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e the [SQLITE_OPEN
b930: 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 74 _NOMUTEX] flag t
b940: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f o [sqlite3_open_
b950: 76 32 28 29 5d 2e 3c 2f 70 3e 3c 2f 64 64 3e 0a v2()].</p></dd>.
b960: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
b970: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f _CONFIG_MALLOC</
b980: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
b990: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
b9a0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
b9b0: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 hich is a pointe
b9c0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 r to an.** insta
b9d0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
b9e0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
b9f0: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 structure. The
ba00: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 argument specif
ba10: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 ies.** alternati
ba20: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d ve low-level mem
ba30: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
ba40: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 outines to be us
ba50: 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a ed in place of.*
ba60: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c * the memory all
ba70: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
ba80: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 built into SQLi
ba90: 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c te.</dd>.**.** <
baa0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
bab0: 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a _GETMALLOC</dt>.
bac0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 ** <dd>This opti
bad0: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
bae0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
baf0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
bb00: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
bb10: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
bb20: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 mem_methods] str
bb30: 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 ucture. The [sq
bb40: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
bb50: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 s].** structure
bb60: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 is filled with t
bb70: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 he currently def
bb80: 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ined memory allo
bb90: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e cation routines.
bba0: 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 .** This option
bbb0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
bbc0: 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 verload the defa
bbd0: 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ult memory alloc
bbe0: 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 ation.** routine
bbf0: 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 s with a wrapper
bc00: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e that simulation
bc10: 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 s memory allocat
bc20: 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a ion failure or.*
bc30: 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 * tracks memory
bc40: 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 usage, for examp
bc50: 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c le.</dd>.**.** <
bc60: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
bc70: 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a _MEMSTATUS</dt>.
bc80: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 ** <dd>This opti
bc90: 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 on takes single
bca0: 62 6f 6f 6c 65 61 6e 20 61 72 67 75 6d 65 6e 74 boolean argument
bcb0: 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f which enables o
bcc0: 72 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 74 68 r disables.** th
bcd0: 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 e collection of
bce0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
bcf0: 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 20 57 n statistics. W
bd00: 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20 74 68 hen disabled, th
bd10: 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 e.** following S
bd20: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
bd30: 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 become non-oper
bd40: 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 ational:.** <u
bd50: 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 l>.** <li> [sq
bd60: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
bd70: 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b d()].** <li> [
bd80: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
bd90: 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 ighwater()].**
bda0: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 <li> [sqlite3_s
bdb0: 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 oft_heap_limit()
bdc0: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 73 71 6c 69 ].** <li> sqli
bdd0: 74 65 33 5f 6d 65 6d 6f 72 79 5f 73 74 61 74 75 te3_memory_statu
bde0: 73 28 29 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a s().** </ul>.*
bdf0: 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 * </dd>.**.** <d
be00: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
be10: 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 SCRATCH</dt>.**
be20: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
be30: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 specifies a stat
be40: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 ic memory buffer
be50: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e that SQLite can
be60: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 use for.** scra
be70: 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 tch memory. The
be80: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 re are three arg
be90: 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 uments: A point
bea0: 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 er to the memory
beb0: 2c 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 , the.** size of
bec0: 20 65 61 63 68 20 73 63 72 61 74 63 68 20 62 75 each scratch bu
bed0: 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 ffer (sz), and t
bee0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 75 66 he number of buf
bef0: 66 65 72 73 20 28 4e 29 2e 20 20 54 68 65 20 73 fers (N). The s
bf00: 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 z.** argument mu
bf10: 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 st be a multiple
bf20: 20 6f 66 20 31 36 2e 20 54 68 65 20 66 69 72 73 of 16. The firs
bf30: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 t.** argument sh
bf40: 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e ould point to an
bf50: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 allocation of a
bf60: 74 20 6c 65 61 73 74 20 28 73 7a 2b 34 29 2a 4e t least (sz+4)*N
bf70: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 bytes of memory
bf80: 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c ..** SQLite will
bf90: 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 use no more tha
bfa0: 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 n one scratch bu
bfb0: 66 66 65 72 20 61 74 20 6f 6e 63 65 20 70 65 72 ffer at once per
bfc0: 20 74 68 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e thread, so.** N
bfd0: 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 should be set t
bfe0: 6f 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d o the expected m
bff0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
c000: 20 74 68 72 65 61 64 73 2e 20 20 54 68 65 20 73 threads. The s
c010: 7a 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73 z.** parameter s
c020: 68 6f 75 6c 64 20 62 65 20 36 20 74 69 6d 65 73 hould be 6 times
c030: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
c040: 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 largest databas
c050: 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 e page size..**
c060: 53 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 Scratch buffers
c070: 61 72 65 20 75 73 65 64 20 61 73 20 70 61 72 74 are used as part
c080: 20 6f 66 20 74 68 65 20 62 74 72 65 65 20 62 61 of the btree ba
c090: 6c 61 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e lance operation.
c0a0: 20 20 49 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 If.** The btre
c0b0: 65 20 62 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 e balancer needs
c0c0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f additional memo
c0d0: 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 ry beyond what i
c0e0: 73 20 70 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a s provided by.**
c0f0: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 scratch buffers
c100: 20 6f 72 20 69 66 20 6e 6f 20 73 63 72 61 74 63 or if no scratc
c110: 68 20 62 75 66 66 65 72 20 73 70 61 63 65 20 69 h buffer space i
c120: 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 s specified, the
c130: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 n SQLite.** goes
c140: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c to [sqlite3_mal
c150: 6c 6f 63 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e loc()] to obtain
c160: 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e the memory it n
c170: 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a eeds.</dd>.**.**
c180: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
c190: 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 IG_PAGECACHE</dt
c1a0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 >.** <dd>This op
c1b0: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 tion specifies a
c1c0: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 static memory b
c1d0: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 uffer that SQLit
c1e0: 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a e can use for.**
c1f0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 the database pa
c200: 67 65 20 63 61 63 68 65 2e 20 20 54 68 65 72 65 ge cache. There
c210: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d are three argum
c220: 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65 72 20 ents: A pointer
c230: 74 6f 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 to the.** memory
c240: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 , the size of ea
c250: 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28 ch page buffer (
c260: 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d sz), and the num
c270: 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 ber of pages (N)
c280: 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 ..** The sz argu
c290: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 ment must be a p
c2a0: 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 ower of two betw
c2b0: 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 een 512 and 3276
c2c0: 38 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 8. The first.**
c2d0: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 argument should
c2e0: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c point to an all
c2f0: 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 ocation of at le
c300: 61 73 74 20 28 73 7a 2b 34 29 2a 4e 20 62 79 74 ast (sz+4)*N byt
c310: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a es of memory..**
c320: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 SQLite will use
c330: 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 the memory prov
c340: 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 ided by the firs
c350: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 t argument to sa
c360: 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d tisfy its.** mem
c370: 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 ory needs for th
c380: 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 e first N pages
c390: 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 that it adds to
c3a0: 63 61 63 68 65 2e 20 20 49 66 20 61 64 64 69 74 cache. If addit
c3b0: 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 ional.** page ca
c3c0: 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 che memory is ne
c3d0: 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 eded beyond what
c3e0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 is provided by
c3f0: 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 this option, the
c400: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 n.** SQLite goes
c410: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c to [sqlite3_mal
c420: 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 loc()] for the a
c430: 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 dditional storag
c440: 65 20 73 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a e space.</dd>.**
c450: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
c460: 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a ONFIG_HEAP</dt>.
c470: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 ** <dd>This opti
c480: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 on specifies a s
c490: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 tatic memory buf
c4a0: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 fer that SQLite
c4b0: 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 will use.** for
c4c0: 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d all of its dynam
c4d0: 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ic memory alloca
c4e0: 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e tion needs beyon
c4f0: 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 d those provided
c500: 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 .** for by [SQLI
c510: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
c520: 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 H] and [SQLITE_C
c530: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d ONFIG_PAGECACHE]
c540: 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 ..** There are t
c550: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 hree arguments:
c560: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 A pointer to the
c570: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 6e 75 6d memory, the num
c580: 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 ber of.** bytes
c590: 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 in the memory bu
c5a0: 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 ffer, and the mi
c5b0: 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
c5c0: 20 73 69 7a 65 2e 20 20 49 66 0a 2a 2a 20 74 68 size. If.** th
c5d0: 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 e first pointer
c5e0: 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e (the memory poin
c5f0: 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 ter) is NULL, th
c600: 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 en SQLite revert
c610: 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 s.** to using it
c620: 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 s default memory
c630: 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 allocator (the
c640: 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 system malloc()
c650: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c implementation),
c660: 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 .** undoing any
c670: 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e prior invocation
c680: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 of [SQLITE_CONF
c690: 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 IG_MALLOC]. If
c6a0: 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f the.** memory po
c6b0: 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c inter is not NUL
c6c0: 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 L and either [SQ
c6d0: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 LITE_ENABLE_MEMS
c6e0: 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 YS3] or.** [SQLI
c6f0: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 TE_ENABLE_MEMSYS
c700: 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 5] are defined,
c710: 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 then the alterna
c720: 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 tive memory.** a
c730: 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 llocator is enga
c740: 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c ged to handle al
c750: 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d l of SQLites mem
c760: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e ory allocation n
c770: 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a eeds.</dd>.**.**
c780: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
c790: 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a IG_MUTEX</dt>.**
c7a0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e <dd>This option
c7b0: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
c7c0: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
c7d0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
c7e0: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 n.** instance of
c7f0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
c800: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 tex_methods] str
c810: 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 ucture. The arg
c820: 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a ument specifies.
c830: 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c ** alternative l
c840: 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 ow-level mutex r
c850: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 outines to be us
c860: 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 ed in place.** t
c870: 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 he mutex routine
c880: 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c s built into SQL
c890: 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ite.</dd>.**.**
c8a0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
c8b0: 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a G_GETMUTEX</dt>.
c8c0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 ** <dd>This opti
c8d0: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
c8e0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
c8f0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
c900: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
c910: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
c920: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 mutex_methods] s
c930: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a tructure. The.*
c940: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 * [sqlite3_mutex
c950: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 _methods].** str
c960: 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 ucture is filled
c970: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
c980: 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 tly defined mute
c990: 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 x routines..** T
c9a0: 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 his option can b
c9b0: 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f e used to overlo
c9c0: 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d ad the default m
c9d0: 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a utex allocation.
c9e0: 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 ** routines with
c9f0: 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 a wrapper used
ca00: 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 to track mutex u
ca10: 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d sage for perform
ca20: 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e ance.** profilin
ca30: 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f g or testing, fo
ca40: 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a r example.</dd>.
ca50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
ca60: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
ca70: 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c HREAD 1 /* nil
ca80: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
ca90: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
caa0: 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 HREAD 2 /* ni
cab0: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
cac0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 ITE_CONFIG_SERIA
cad0: 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e LIZED 3 /* n
cae0: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 il */.#define SQ
caf0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
cb00: 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 OC 4 /*
cb10: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
cb20: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ods* */.#define
cb30: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
cb40: 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f TMALLOC 5 /
cb50: 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 * sqlite3_mem_me
cb60: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e thods* */.#defin
cb70: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
cb80: 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 SCRATCH 6
cb90: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 /* void*, int s
cba0: 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 z, int N */.#def
cbb0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
cbc0: 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 G_PAGECACHE
cbd0: 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 7 /* void*, int
cbe0: 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 sz, int N */.#d
cbf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
cc00: 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 FIG_HEAP
cc10: 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 8 /* void*, i
cc20: 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 nt nByte, int mi
cc30: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c n */.#define SQL
cc40: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
cc50: 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 ATUS 9 /* b
cc60: 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e oolean */.#defin
cc70: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
cc80: 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 MUTEX 10
cc90: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 /* sqlite3_mute
cca0: 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 x_methods* */.#d
ccb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
ccc0: 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 FIG_GETMUTEX
ccd0: 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 11 /* sqlite3_
cce0: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a mutex_methods* *
ccf0: 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 /.../*.** CAPI3R
cd00: 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 EF: Enable Or Di
cd10: 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 sable Extended R
cd20: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 32 esult Codes {F12
cd30: 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 200}.**.** The s
cd40: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
cd50: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 result_codes() r
cd60: 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f outine enables o
cd70: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a r disables the.*
cd80: 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 * [extended resu
cd90: 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 lt codes] featur
cda0: 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54 68 65 e of SQLite. The
cdb0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
cdc0: 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 .** codes are di
cdd0: 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
cde0: 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c t for historical
cdf0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 63 compatibility c
ce00: 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a onsiderations..*
ce10: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
ce20: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30 31 7d 20 .**.** {F12201}
ce30: 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 Each new [databa
ce40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 se connection] s
ce50: 68 61 6c 6c 20 68 61 76 65 20 74 68 65 0a 2a 2a hall have the.**
ce60: 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e [exten
ce70: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
ce80: 5d 20 66 65 61 74 75 72 65 20 64 69 73 61 62 6c ] feature disabl
ce90: 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a ed by default..*
cea0: 2a 0a 2a 2a 20 7b 46 31 32 32 30 32 7d 20 54 68 *.** {F12202} Th
ceb0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e e [sqlite3_exten
cec0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 ded_result_codes
ced0: 28 44 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65 (D,F)] interface
cee0: 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a shall enable.**
cef0: 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e [exten
cf00: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
cf10: 5d 20 66 6f 72 20 74 68 65 20 20 5b 64 61 74 61 ] for the [data
cf20: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
cf30: 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 D.** i
cf40: 66 20 74 68 65 20 46 20 70 61 72 61 6d 65 74 65 f the F paramete
cf50: 72 20 69 73 20 74 72 75 65 2c 20 6f 72 20 64 69 r is true, or di
cf60: 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20 46 20 sable them if F
cf70: 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 is false..*/.int
cf80: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 sqlite3_extende
cf90: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 d_result_codes(s
cfa0: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f qlite3*, int ono
cfb0: 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ff);../*.** CAPI
cfc0: 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 3REF: Last Inser
cfd0: 74 20 52 6f 77 69 64 20 7b 46 31 32 32 32 30 7d t Rowid {F12220}
cfe0: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 .**.** Each entr
cff0: 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 y in an SQLite t
d000: 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 able has a uniqu
d010: 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a e 64-bit signed.
d020: 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 ** integer key c
d030: 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69 64 alled the "rowid
d040: 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73 20 ". The rowid is
d050: 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 always available
d060: 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c .** as an undecl
d070: 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 ared column name
d080: 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 d ROWID, OID, or
d090: 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 _ROWID_ as long
d0a0: 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d as those.** nam
d0b0: 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 es are not also
d0c0: 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 used by explicit
d0d0: 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 ly declared colu
d0e0: 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20 74 mns. If.** the t
d0f0: 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d able has a colum
d100: 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 45 47 45 n of type INTEGE
d110: 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74 68 R PRIMARY KEY th
d120: 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a en that column.*
d130: 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 * is another ali
d140: 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 as for the rowid
d150: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
d160: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 tine returns the
d170: 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d 6f rowid of the mo
d180: 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 st recent.** suc
d190: 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20 69 cessful INSERT i
d1a0: 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 nto the database
d1b0: 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 from the [datab
d1c0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a ase connection].
d1d0: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ** in the first
d1e0: 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f argument. If no
d1f0: 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45 successful INSE
d200: 52 54 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 RTs.** have ever
d210: 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 occurred on tha
d220: 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 t database conne
d230: 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 ction, zero is r
d240: 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 eturned..**.** I
d250: 66 20 61 6e 20 49 4e 53 45 52 54 20 6f 63 63 75 f an INSERT occu
d260: 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 rs within a trig
d270: 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 6f ger, then the ro
d280: 77 69 64 20 6f 66 20 74 68 65 20 69 6e 73 65 72 wid of the inser
d290: 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 ted.** row is re
d2a0: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 turned by this r
d2b0: 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 outine as long a
d2c0: 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73 s the trigger is
d2d0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 running..** But
d2e0: 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 once the trigge
d2f0: 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 r terminates, th
d300: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
d310: 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 by this routine
d320: 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74 .** reverts to t
d330: 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e he last value in
d340: 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 serted before th
d350: 65 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e e trigger fired.
d360: 0a 2a 2a 0a 2a 2a 20 41 6e 20 49 4e 53 45 52 54 .**.** An INSERT
d370: 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 that fails due
d380: 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 to a constraint
d390: 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 violation is not
d3a0: 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c a.** successful
d3b0: 20 49 4e 53 45 52 54 20 61 6e 64 20 64 6f 65 73 INSERT and does
d3c0: 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 not change the
d3d0: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
d3e0: 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e y this.** routin
d3f0: 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54 20 e. Thus INSERT
d400: 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 OR FAIL, INSERT
d410: 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 OR IGNORE, INSER
d420: 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a T OR ROLLBACK,.*
d430: 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 * and INSERT OR
d440: 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 ABORT make no ch
d450: 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 anges to the ret
d460: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 urn value of thi
d470: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 s.** routine whe
d480: 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f n their insertio
d490: 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20 49 n fails. When I
d4a0: 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 NSERT OR REPLACE
d4b0: 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 .** encounters a
d4c0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c constraint viol
d4d0: 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e ation, it does n
d4e0: 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a ot fail. The.**
d4f0: 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 INSERT continue
d500: 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 s to completion
d510: 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 after deleting r
d520: 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a ows that caused.
d530: 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e ** the constrain
d540: 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 t problem so INS
d550: 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 ERT OR REPLACE w
d560: 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 ill always chang
d570: 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 e.** the return
d580: 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e value of this in
d590: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 terface..**.** F
d5a0: 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 or the purposes
d5b0: 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c of this routine,
d5c0: 20 61 6e 20 49 4e 53 45 52 54 20 69 73 20 63 6f an INSERT is co
d5d0: 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 nsidered to.** b
d5e0: 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 e successful eve
d5f0: 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 n if it is subse
d600: 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 quently rolled b
d610: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ack..**.** INVAR
d620: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 IANTS:.**.** {F1
d630: 32 32 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 2221} The [sqlit
d640: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
d650: 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e owid()] function
d660: 20 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 returns the row
d670: 69 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f id.** o
d680: 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
d690: 74 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53 t successful INS
d6a0: 45 52 54 20 70 65 72 66 6f 72 6d 65 64 20 6f 6e ERT performed on
d6b0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 the same.**
d6c0: 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 [database
d6d0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 connection] and
d6e0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 within the same
d6f0: 6f 72 20 68 69 67 68 65 72 20 6c 65 76 65 6c 0a or higher level.
d700: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67 ** trig
d710: 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 ger context, or
d720: 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 zero if there ha
d730: 76 65 20 62 65 65 6e 20 6e 6f 20 71 75 61 6c 69 ve been no quali
d740: 66 79 69 6e 67 20 69 6e 73 65 72 74 73 2e 0a 2a fying inserts..*
d750: 2a 0a 2a 2a 20 7b 46 31 32 32 32 33 7d 20 54 68 *.** {F12223} Th
d760: 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f e [sqlite3_last_
d770: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 insert_rowid()]
d780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
d790: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
d7a0: 20 73 61 6d 65 20 76 61 6c 75 65 20 77 68 65 6e same value when
d7b0: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
d7c0: 20 73 61 6d 65 20 74 72 69 67 67 65 72 20 63 6f same trigger co
d7d0: 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 ntext.**
d7e0: 20 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 immediately be
d7f0: 66 6f 72 65 20 61 6e 64 20 61 66 74 65 72 20 61 fore and after a
d800: 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a ROLLBACK..**.**
d810: 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a LIMITATIONS:.**
d820: 0a 2a 2a 20 7b 41 31 32 32 33 32 7d 20 49 66 20 .** {A12232} If
d830: 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
d840: 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 d performs a new
d850: 20 49 4e 53 45 52 54 20 6f 6e 20 74 68 65 20 73 INSERT on the s
d860: 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ame.**
d870: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
d880: 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 ion while the [s
d890: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
d8a0: 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 20 rt_rowid()].**
d8b0: 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e function
d8c0: 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 is running and
d8d0: 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 thus changes the
d8e0: 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 last insert row
d8f0: 69 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 id,.**
d900: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 then the value r
d910: 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
d920: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
d930: 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 20 rowid()] is.**
d940: 20 20 20 20 20 20 20 20 75 6e 70 72 65 64 69 63 unpredic
d950: 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 table and might
d960: 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 not equal either
d970: 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 the old or the
d980: 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 new.**
d990: 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 last insert rowi
d9a0: 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e d..*/.sqlite3_in
d9b0: 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 t64 sqlite3_last
d9c0: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 _insert_rowid(sq
d9d0: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
d9e0: 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 CAPI3REF: Count
d9f0: 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f The Number Of Ro
da00: 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 46 31 32 ws Modified {F12
da10: 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 240}.**.** This
da20: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
da30: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 the number of d
da40: 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 atabase rows tha
da50: 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a t were changed.*
da60: 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 * or inserted or
da70: 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 deleted by the
da80: 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f most recently co
da90: 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 mpleted SQL stat
daa0: 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 ement.** on the
dab0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
dac0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 tion] specified
dad0: 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 by the first par
dae0: 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 ameter..** Only
daf0: 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 changes that are
db00: 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 directly specif
db10: 69 65 64 20 62 79 20 74 68 65 20 49 4e 53 45 52 ied by the INSER
db20: 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20 6f 72 T, UPDATE,.** or
db30: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e DELETE statemen
db40: 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 t are counted.
db50: 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 Auxiliary change
db60: 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 s caused by.** t
db70: 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20 riggers are not
db80: 63 6f 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65 counted. Use the
db90: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f [sqlite3_total_
dba0: 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 changes()] funct
dbb0: 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 ion.** to find t
dbc0: 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 he total number
dbd0: 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 of changes inclu
dbe0: 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 ding changes cau
dbf0: 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 2e sed by triggers.
dc00: 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 .**.** A "row ch
dc10: 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 ange" is a chang
dc20: 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f e to a single ro
dc30: 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 w of a single ta
dc40: 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 ble.** caused by
dc50: 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 an INSERT, DELE
dc60: 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 TE, or UPDATE st
dc70: 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 atement. Rows t
dc80: 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 hat.** are chang
dc90: 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 ed as side effec
dca0: 74 73 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f ts of REPLACE co
dcb0: 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 nstraint resolut
dcc0: 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b ion,.** rollback
dcd0: 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 , ABORT processi
dce0: 6e 67 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 ng, DROP TABLE,
dcf0: 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a or by any other.
dd00: 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f ** mechanisms do
dd10: 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 not count as di
dd20: 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 rect row changes
dd30: 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 ..**.** A "trigg
dd40: 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 er context" is a
dd50: 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 scope of execut
dd60: 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 ion that begins
dd70: 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 and.** ends with
dd80: 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 the script of a
dd90: 20 74 72 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 trigger. Most
dda0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 SQL statements a
ddb0: 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 re.** evaluated
ddc0: 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 outside of any t
ddd0: 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 rigger. This is
dde0: 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 the "top level"
ddf0: 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 .** trigger cont
de00: 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 ext. If a trigg
de10: 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 er fires from th
de20: 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a e top level, a.*
de30: 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f * new trigger co
de40: 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 ntext is entered
de50: 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f for the duratio
de60: 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a n of that one.**
de70: 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 trigger. Subtr
de80: 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 iggers create su
de90: 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 bcontexts for th
dea0: 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a eir duration..**
deb0: 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c .** Calling [sql
dec0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 ite3_exec()] or
ded0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
dee0: 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 recursively doe
def0: 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 s.** not create
df00: 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f a new trigger co
df10: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 ntext..**.** Thi
df20: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
df30: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
df40: 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e direct row chan
df50: 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f ges in the.** mo
df60: 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 st recent INSERT
df70: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c , UPDATE, or DEL
df80: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 ETE statement wi
df90: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a thin the same.**
dfa0: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 trigger context
dfb0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68 ..**.** Thus, wh
dfc0: 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 en called from t
dfd0: 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 he top level, th
dfe0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
dff0: 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 rns the.** numbe
e000: 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 r of changes in
e010: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
e020: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
e030: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 or DELETE.** tha
e040: 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 t also occurred
e050: 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c at the top level
e060: 2e 20 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f . Within the bo
e070: 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c dy of a trigger,
e080: 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f .** the sqlite3_
e090: 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 changes() interf
e0a0: 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 ace can be calle
e0b0: 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 d to find the nu
e0c0: 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 mber of.** chang
e0d0: 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 es in the most r
e0e0: 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 ecently complete
e0f0: 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 d INSERT, UPDATE
e100: 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 , or DELETE.** s
e110: 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 tatement within
e120: 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 the body of the
e130: 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a same trigger..**
e140: 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 However, the nu
e150: 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f mber returned do
e160: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 es not include c
e170: 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 hanges.** caused
e180: 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20 by subtriggers
e190: 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 since those have
e1a0: 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 their own conte
e1b0: 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 xt..**.** SQLite
e1c0: 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 implements the
e1d0: 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 command "DELETE
e1e0: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 FROM table" with
e1f0: 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c 61 75 out a WHERE clau
e200: 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e se.** by droppin
e210: 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 g and recreating
e220: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68 the table. (Th
e230: 69 73 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 is is much faste
e240: 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 r than going.**
e250: 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 through and dele
e260: 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 ting individual
e270: 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 elements from th
e280: 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75 e table.) Becau
e290: 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 se of this.** op
e2a0: 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 timization, the
e2b0: 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 deletions in "DE
e2c0: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 LETE FROM table"
e2d0: 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 are not row cha
e2e0: 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c nges and.** will
e2f0: 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20 not be counted
e300: 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 by the sqlite3_c
e310: 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c hanges() or [sql
e320: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
e330: 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f es()].** functio
e340: 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f ns, regardless o
e350: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 f the number of
e360: 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 elements that we
e370: 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a re originally.**
e380: 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20 in the table.
e390: 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 To get an accura
e3a0: 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 te count of the
e3b0: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 number of rows d
e3c0: 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 eleted, use.** "
e3d0: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c DELETE FROM tabl
e3e0: 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 e WHERE 1" inste
e3f0: 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 ad..**.** INVARI
e400: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 ANTS:.**.** {F12
e410: 32 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 241} The [sqlite
e420: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 3_changes()] fun
e430: 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 ction shall retu
e440: 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 rn the number of
e450: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77 .** row
e460: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 changes caused
e470: 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 by the most rece
e480: 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 nt INSERT, UPDAT
e490: 45 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f E,.** o
e4a0: 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 r DELETE stateme
e4b0: 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 nt on the same d
e4c0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
e4d0: 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 on and.**
e4e0: 20 20 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 within the sa
e4f0: 6d 65 20 6f 72 20 68 69 67 68 65 72 20 74 72 69 me or higher tri
e500: 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 gger context, or
e510: 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 68 zero if there h
e520: 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ave.**
e530: 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20 71 75 61 not been any qua
e540: 6c 69 66 79 69 6e 67 20 72 6f 77 20 63 68 61 6e lifying row chan
e550: 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 ges..**.** {F122
e560: 34 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 43} Statements o
e570: 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 f the form "DELE
e580: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d TE FROM tablenam
e590: 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 e" with no.**
e5a0: 20 20 20 20 20 20 20 57 48 45 52 45 20 63 6c 61 WHERE cla
e5b0: 75 73 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20 use shall cause
e5c0: 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 subsequent calls
e5d0: 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 to.**
e5e0: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 [sqlite3_changes
e5f0: 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 7a 65 ()] to return ze
e600: 72 6f 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f ro, regardless o
e610: 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 f the.**
e620: 20 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 number of rows
e630: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 originally in t
e640: 68 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 he table..**.**
e650: 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a LIMITATIONS:.**.
e660: 2a 2a 20 7b 41 31 32 32 35 32 7d 20 49 66 20 61 ** {A12252} If a
e670: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 separate thread
e680: 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f makes changes o
e690: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 n the same datab
e6a0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
e6b0: 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c 65 * while
e6c0: 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 [sqlite3_change
e6d0: 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 s()] is running
e6e0: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 then the value r
e6f0: 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 eturned.**
e700: 20 20 20 20 69 73 20 75 6e 70 72 65 64 69 63 74 is unpredict
e710: 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 able and not mea
e720: 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 ningful..*/.int
e730: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
e740: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
e750: 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 * CAPI3REF: Tota
e760: 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 l Number Of Rows
e770: 20 4d 6f 64 69 66 69 65 64 20 7b 46 31 32 32 36 Modified {F1226
e780: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 0}.**.** This fu
e790: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 nction returns t
e7a0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 he number of row
e7b0: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 changes caused
e7c0: 62 79 20 49 4e 53 45 52 54 2c 0a 2a 2a 20 55 50 by INSERT,.** UP
e7d0: 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 DATE or DELETE s
e7e0: 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 tatements since
e7f0: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
e800: 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 nnection] was op
e810: 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 ened..** The cou
e820: 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 nt includes all
e830: 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c changes from all
e840: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 trigger context
e850: 73 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 s. However,.**
e860: 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e the count does n
e870: 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 ot include chang
e880: 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 es used to imple
e890: 6d 65 6e 74 20 52 45 50 4c 41 43 45 20 63 6f 6e ment REPLACE con
e8a0: 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 straints,.** do
e8b0: 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f rollbacks or ABO
e8c0: 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f RT processing, o
e8d0: 72 20 44 52 4f 50 20 74 61 62 6c 65 20 70 72 6f r DROP table pro
e8e0: 63 65 73 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 cessing..** The
e8f0: 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e changes are coun
e900: 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 ted as soon as t
e910: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 he statement tha
e920: 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 0a t makes them is.
e930: 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 ** completed (wh
e940: 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 en the statement
e950: 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73 73 65 handle is passe
e960: 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 d to [sqlite3_re
e970: 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 set()] or.** [sq
e980: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
e990: 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ])..**.** SQLite
e9a0: 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 implements the
e9b0: 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 command "DELETE
e9c0: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 FROM table" with
e9d0: 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c 61 75 out a WHERE clau
e9e0: 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e se.** by droppin
e9f0: 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 g and recreating
ea00: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68 the table. (Th
ea10: 69 73 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 is is much faste
ea20: 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 r than going.**
ea30: 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 through and dele
ea40: 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 ting individual
ea50: 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 elements from th
ea60: 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75 e table.) Becau
ea70: 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 se of this.** op
ea80: 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 timization, the
ea90: 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 deletions in "DE
eaa0: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 LETE FROM table"
eab0: 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 are not row cha
eac0: 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c nges and.** will
ead0: 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20 not be counted
eae0: 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 by the sqlite3_c
eaf0: 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c hanges() or [sql
eb00: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
eb10: 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f es()].** functio
eb20: 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f ns, regardless o
eb30: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 f the number of
eb40: 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 elements that we
eb50: 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a re originally.**
eb60: 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20 in the table.
eb70: 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 To get an accura
eb80: 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 te count of the
eb90: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 number of rows d
eba0: 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 eleted, use.** "
ebb0: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c DELETE FROM tabl
ebc0: 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 e WHERE 1" inste
ebd0: 61 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ad..**.** See al
ebe0: 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f so the [sqlite3_
ebf0: 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 changes()] inter
ec00: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 face..**.** INVA
ec10: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 RIANTS:.**.** {F
ec20: 31 32 32 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 12261} The [sqli
ec30: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
ec40: 73 28 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 s()] returns the
ec50: 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a total number.**
ec60: 20 20 20 20 20 20 20 20 20 20 6f 66 20 72 6f 77 of row
ec70: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 changes caused
ec80: 62 79 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 by INSERT, UPDAT
ec90: 45 2c 20 61 6e 64 2f 6f 72 20 44 45 4c 45 54 45 E, and/or DELETE
eca0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 .** sta
ecb0: 74 65 6d 65 6e 74 73 20 6f 6e 20 74 68 65 20 73 tements on the s
ecc0: 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f ame [database co
ecd0: 6e 6e 65 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e nnection], in an
ece0: 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 72 y.** tr
ecf0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 73 igger context, s
ed00: 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73 ince the databas
ed10: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 e connection was
ed20: 20 63 72 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 created..**.**
ed30: 7b 46 31 32 32 36 33 7d 20 53 74 61 74 65 6d 65 {F12263} Stateme
ed40: 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 nts of the form
ed50: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 "DELETE FROM tab
ed60: 6c 65 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a lename" with no.
ed70: 2a 2a 20 20 20 20 20 20 20 20 20 20 57 48 45 52 ** WHER
ed80: 45 20 63 6c 61 75 73 65 20 73 68 61 6c 6c 20 6e E clause shall n
ed90: 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 ot change the va
eda0: 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 lue returned.**
edb0: 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c by [sql
edc0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
edd0: 65 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d es()]..**.** LIM
ede0: 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 ITATIONS:.**.**
edf0: 7b 41 31 32 32 36 34 7d 20 49 66 20 61 20 73 65 {A12264} If a se
ee00: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 parate thread ma
ee10: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 kes changes on t
ee20: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
ee30: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 connection.**
ee40: 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73 while [s
ee50: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
ee60: 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 nges()] is runni
ee70: 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 ng then the valu
ee80: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 e.** re
ee90: 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 turned is unpred
eea0: 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 ictable and not
eeb0: 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 meaningful..*/.i
eec0: 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c nt sqlite3_total
eed0: 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 _changes(sqlite3
eee0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
eef0: 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 REF: Interrupt A
ef00: 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 Long-Running Qu
ef10: 65 72 79 20 7b 46 31 32 32 37 30 7d 0a 2a 2a 0a ery {F12270}.**.
ef20: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
ef30: 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 causes any pend
ef40: 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 ing database ope
ef50: 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 ration to abort
ef60: 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 and.** return at
ef70: 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 its earliest op
ef80: 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 portunity. This
ef90: 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 routine is typic
efa0: 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 ally.** called i
efb0: 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 n response to a
efc0: 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 user action such
efd0: 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 as pressing "Ca
efe0: 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c ncel".** or Ctrl
eff0: 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 -C where the use
f000: 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 r wants a long q
f010: 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 uery operation t
f020: 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 o halt.** immedi
f030: 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 ately..**.** It
f040: 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 is safe to call
f050: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f this routine fro
f060: 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 m a thread diffe
f070: 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a rent from the.**
f080: 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 thread that is
f090: 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e currently runnin
f0a0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f g the database o
f0b0: 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 peration. But i
f0c0: 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 t.** is not safe
f0d0: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f to call this ro
f0e0: 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 utine with a [da
f0f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
f100: 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c n] that.** is cl
f110: 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c osed or might cl
f120: 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 ose before sqlit
f130: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 e3_interrupt() r
f140: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 eturns..**.** If
f150: 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f an SQL operatio
f160: 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 n is very nearly
f170: 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 finished at the
f180: 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 time when.** sq
f190: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
f1a0: 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 ) is called, the
f1b0: 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 n it might not h
f1c0: 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 ave an opportuni
f1d0: 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 ty.** to be inte
f1e0: 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 rrupted and migh
f1f0: 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f t continue to co
f200: 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 mpletion..**.**
f210: 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e An SQL operation
f220: 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 that is interru
f230: 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e pted will return
f240: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 [SQLITE_INTERRU
f250: 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 PT]..** If the i
f260: 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f nterrupted SQL o
f270: 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 peration is an I
f280: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f NSERT, UPDATE, o
f290: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 r DELETE.** that
f2a0: 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 is inside an ex
f2b0: 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 plicit transacti
f2c0: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 on, then the ent
f2d0: 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a ire transaction.
f2e0: 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 ** will be rolle
f2f0: 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 d back automatic
f300: 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 ally..**.** A ca
f310: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e ll to sqlite3_in
f320: 74 65 72 72 75 70 74 28 29 20 68 61 73 20 6e 6f terrupt() has no
f330: 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 effect on SQL s
f340: 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 tatements.** tha
f350: 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 t are started af
f360: 74 65 72 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 ter sqlite3_inte
f370: 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e rrupt() returns.
f380: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
f390: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 37 31 S:.**.** {F12271
f3a0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 } The [sqlite3_i
f3b0: 6e 74 65 72 72 75 70 74 28 29 5d 20 69 6e 74 65 nterrupt()] inte
f3c0: 72 66 61 63 65 20 77 69 6c 6c 20 66 6f 72 63 65 rface will force
f3d0: 20 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 all running.**
f3e0: 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61 SQL sta
f3f0: 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 tements associat
f400: 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 ed with the same
f410: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
f420: 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 tion.**
f430: 20 74 6f 20 68 61 6c 74 20 61 66 74 65 72 20 70 to halt after p
f440: 72 6f 63 65 73 73 69 6e 67 20 61 74 20 6d 6f 73 rocessing at mos
f450: 74 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c t one additional
f460: 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a row of data..**
f470: 0a 2a 2a 20 7b 46 31 32 32 37 32 7d 20 41 6e 79 .** {F12272} Any
f480: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
f490: 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 hat is interrupt
f4a0: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 69 ed by [sqlite3_i
f4b0: 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 nterrupt()].**
f4c0: 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74 will ret
f4d0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 urn [SQLITE_INTE
f4e0: 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49 RRUPT]..**.** LI
f4f0: 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a MITATIONS:.**.**
f500: 20 7b 41 31 32 32 37 39 7d 20 49 66 20 74 68 65 {A12279} If the
f510: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
f520: 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c tion closes whil
f530: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 e [sqlite3_inter
f540: 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 rupt()].**
f550: 20 20 20 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 is running t
f560: 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 hen bad things w
f570: 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 ill likely happe
f580: 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 n..*/.void sqlit
f590: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c e3_interrupt(sql
f5a0: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
f5b0: 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 API3REF: Determi
f5c0: 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 ne If An SQL Sta
f5d0: 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 tement Is Comple
f5e0: 74 65 20 7b 46 31 30 35 31 30 7d 0a 2a 2a 0a 2a te {F10510}.**.*
f5f0: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
f600: 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 are useful for
f610: 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 command-line inp
f620: 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 ut to determine
f630: 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e if the.** curren
f640: 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 tly entered text
f650: 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 seems to form c
f660: 6f 6d 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74 omplete a SQL st
f670: 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 atement or.** if
f680: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 additional inpu
f690: 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f t is needed befo
f6a0: 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 re sending the t
f6b0: 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 ext into.** SQLi
f6c0: 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 te for parsing.
f6d0: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
f6e0: 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 return true if t
f6f0: 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a he input string.
f700: 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 ** appears to be
f710: 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 a complete SQL
f720: 73 74 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 statement. A st
f730: 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 atement is judge
f740: 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c d to be.** compl
f750: 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 ete if it ends w
f760: 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 ith a semicolon
f770: 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 token and is not
f780: 20 61 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 a fragment of a
f790: 0a 2a 2a 20 43 52 45 41 54 45 20 54 52 49 47 47 .** CREATE TRIGG
f7a0: 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 ER statement. S
f7b0: 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 emicolons that a
f7c0: 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 re embedded with
f7d0: 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 in.** string lit
f7e0: 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 erals or quoted
f7f0: 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 identifier names
f800: 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 or comments are
f810: 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 not.** independ
f820: 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 ent tokens (they
f830: 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 are part of the
f840: 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 token in which
f850: 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 they are.** embe
f860: 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 dded) and thus d
f870: 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 o not count as a
f880: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 statement termi
f890: 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 nator..**.** The
f8a0: 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e se routines do n
f8b0: 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c ot parse the SQL
f8c0: 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 statements thus
f8d0: 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 .** will not det
f8e0: 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c ect syntacticall
f8f0: 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e y incorrect SQL.
f900: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
f910: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 31 31 S:.**.** {F10511
f920: 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 65 } A successful e
f930: 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 valuation of [sq
f940: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 lite3_complete()
f950: 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 ] or.**
f960: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 [sqlite3_comple
f970: 74 65 31 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e te16()] function
f980: 73 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 s shall.**
f990: 20 20 20 20 72 65 74 75 72 6e 20 61 20 6e 75 6d return a num
f9a0: 65 72 69 63 20 31 20 69 66 20 61 6e 64 20 6f 6e eric 1 if and on
f9b0: 6c 79 20 69 66 20 74 68 65 20 6c 61 73 74 20 6e ly if the last n
f9c0: 6f 6e 2d 77 68 69 74 65 73 70 61 63 65 0a 2a 2a on-whitespace.**
f9d0: 20 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 20 token
f9e0: 69 6e 20 74 68 65 69 72 20 69 6e 70 75 74 20 69 in their input i
f9f0: 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 s a semicolon th
fa00: 61 74 20 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 at is not in bet
fa10: 77 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 ween.**
fa20: 20 74 68 65 20 42 45 47 49 4e 20 61 6e 64 20 45 the BEGIN and E
fa30: 4e 44 20 6f 66 20 61 20 43 52 45 41 54 45 20 54 ND of a CREATE T
fa40: 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 RIGGER statement
fa50: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 31 32 7d ..**.** {F10512}
fa60: 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c If a memory all
fa70: 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 ocation error oc
fa80: 63 75 72 73 20 64 75 72 69 6e 67 20 61 6e 20 69 curs during an i
fa90: 6e 76 6f 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 nvocation.**
faa0: 20 20 20 20 20 20 6f 66 20 5b 73 71 6c 69 74 65 of [sqlite
fab0: 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 3_complete()] or
fac0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 [sqlite3_comple
fad0: 74 65 31 36 28 29 5d 20 74 68 65 6e 20 74 68 65 te16()] then the
fae0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 .** rou
faf0: 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 tine shall retur
fb00: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d n [SQLITE_NOMEM]
fb10: 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 ..**.** LIMITATI
fb20: 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 ONS:.**.** {A105
fb30: 31 32 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 12} The input to
fb40: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 [sqlite3_comple
fb50: 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 te()] must be a
fb60: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
fb70: 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d ** UTF-
fb80: 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 8 string..**.**
fb90: 7b 41 31 30 35 31 33 7d 20 54 68 65 20 69 6e 70 {A10513} The inp
fba0: 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ut to [sqlite3_c
fbb0: 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 omplete16()] mus
fbc0: 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d t be a zero-term
fbd0: 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 inated.**
fbe0: 20 20 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 UTF-16 string
fbf0: 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 in native byte
fc00: 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 order..*/.int sq
fc10: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 lite3_complete(c
fc20: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b onst char *sql);
fc30: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d .int sqlite3_com
fc40: 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f plete16(const vo
fc50: 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a id *sql);../*.**
fc60: 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 CAPI3REF: Regis
fc70: 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 ter A Callback T
fc80: 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f o Handle SQLITE_
fc90: 42 55 53 59 20 45 72 72 6f 72 73 20 7b 46 31 32 BUSY Errors {F12
fca0: 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 310}.**.** This
fcb0: 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 routine sets a c
fcc0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
fcd0: 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 that might be i
fce0: 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a nvoked whenever.
fcf0: 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 ** an attempt is
fd00: 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 made to open a
fd10: 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 database table t
fd20: 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 hat another thre
fd30: 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 ad.** or process
fd40: 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a has locked..**.
fd50: 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 63 ** If the busy c
fd60: 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c allback is NULL,
fd70: 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 then [SQLITE_BU
fd80: 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 SY] or [SQLITE_I
fd90: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a OERR_BLOCKED].**
fda0: 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d is returned imm
fdb0: 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e ediately upon en
fdc0: 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c countering the l
fdd0: 6f 63 6b 2e 20 49 66 20 74 68 65 20 62 75 73 79 ock. If the busy
fde0: 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 callback.** is
fdf0: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 not NULL, then t
fe00: 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c he callback will
fe10: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 be invoked with
fe20: 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a two arguments..
fe30: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
fe40: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
fe50: 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 handler is a cop
fe60: 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 y of the void* p
fe70: 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 ointer which.**
fe80: 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 is the third arg
fe90: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
fea0: 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e _busy_handler().
feb0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 The second arg
fec0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 ument to.** the
fed0: 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b handler callback
fee0: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
fef0: 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 f times that the
ff00: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 busy handler ha
ff10: 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 s.** been invoke
ff20: 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 d for this locki
ff30: 6e 67 20 65 76 65 6e 74 2e 20 20 49 66 20 74 68 ng event. If th
ff40: 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 e.** busy callba
ff50: 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 ck returns 0, th
ff60: 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c en no additional
ff70: 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 attempts are ma
ff80: 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 de to.** access
ff90: 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 the database and
ffa0: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f [SQLITE_BUSY] o
ffb0: 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f r [SQLITE_IOERR_
ffc0: 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 BLOCKED] is retu
ffd0: 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 rned..** If the
ffe0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
fff0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 non-zero, then
10000 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a another attempt.
10010 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 ** is made to op
10020 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
10030 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 for reading and
10040 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 the cycle repeat
10050 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 s..**.** The pre
10060 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 sence of a busy
10070 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 handler does not
10080 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 guarantee that
10090 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b it will be invok
100a0 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 ed.** when there
100b0 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 is lock content
100c0 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 64 ion. If SQLite d
100d0 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 etermines that i
100e0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 nvoking the busy
100f0 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c .** handler coul
10100 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 d result in a de
10110 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 adlock, it will
10120 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 go ahead and ret
10130 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 urn [SQLITE_BUSY
10140 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f ].** or [SQLITE_
10150 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 IOERR_BLOCKED] i
10160 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 nstead of invoki
10170 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ng the busy hand
10180 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 ler..** Consider
10190 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 a scenario wher
101a0 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 e one process is
101b0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 holding a read
101c0 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 lock that.** it
101d0 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f is trying to pro
101e0 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 mote to a reserv
101f0 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 ed lock and.** a
10200 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
10210 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 is holding a res
10220 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 erved lock that
10230 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 it is trying.**
10240 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e to promote to an
10250 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e exclusive lock.
10260 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 The first proc
10270 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 ess cannot proce
10280 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 ed.** because it
10290 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 is blocked by t
102a0 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 he second and th
102b0 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 e second process
102c0 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 cannot.** proce
102d0 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 ed because it is
102e0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 blocked by the
102f0 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 first. If both
10300 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 processes.** inv
10310 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e oke the busy han
10320 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 dlers, neither w
10330 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f ill make any pro
10340 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 gress. Therefor
10350 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 e,.** SQLite ret
10360 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 urns [SQLITE_BUS
10370 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 Y] for the first
10380 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 process, hoping
10390 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 that this.** wi
103a0 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 ll induce the fi
103b0 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 rst process to r
103c0 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 elease its read
103d0 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a lock and allow.*
103e0 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f * the second pro
103f0 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e cess to proceed.
10400 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 .**.** The defau
10410 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b lt busy callback
10420 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 is NULL..**.**
10430 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 The [SQLITE_BUSY
10440 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 ] error is conve
10450 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f rted to [SQLITE_
10460 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a IOERR_BLOCKED].*
10470 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 * when SQLite is
10480 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f in the middle o
10490 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 f a large transa
104a0 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 ction where all
104b0 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 the.** changes w
104c0 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f ill not fit into
104d0 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 the in-memory c
104e0 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 ache. SQLite wi
104f0 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f ll.** already ho
10500 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f ld a RESERVED lo
10510 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 ck on the databa
10520 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 se file, but it
10530 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d needs.** to prom
10540 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f ote this lock to
10550 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 EXCLUSIVE so th
10560 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 at it can spill
10570 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 cache.** pages i
10580 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 nto the database
10590 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 file without ha
105a0 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 rm to concurrent
105b0 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 .** readers. If
105c0 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f it is unable to
105d0 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 promote the loc
105e0 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d k, then the in-m
105f0 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 emory.** cache w
10600 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 ill be left in a
10610 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 n inconsistent s
10620 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 tate and so the
10630 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 error.** code is
10640 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 promoted from t
10650 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 he relatively be
10660 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 nign [SQLITE_BUS
10670 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 Y] to.** the mor
10680 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 e severe [SQLITE
10690 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e _IOERR_BLOCKED].
106a0 20 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 This error cod
106b0 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 e promotion.** f
106c0 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 orces an automat
106d0 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 ic rollback of t
106e0 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 he changes. See
106f0 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d the.** <a href=
10700 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 "/cvstrac/wiki?p
10710 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f =CorruptionFollo
10720 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a wingBusyError">.
10730 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c ** CorruptionFol
10740 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c lowingBusyError<
10750 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f /a> wiki page fo
10760 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f r a discussion o
10770 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 f why.** this is
10780 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a important..**.*
10790 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 * There can only
107a0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 be a single bus
107b0 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 y handler define
107c0 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 d for each.** [d
107d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
107e0 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 on]. Setting a
107f0 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 new busy handler
10800 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 clears any.** p
10810 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 reviously set ha
10820 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 ndler. Note tha
10830 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 t calling [sqlit
10840 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
10850 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 )].** will also
10860 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 set or clear the
10870 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a busy handler..*
10880 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
10890 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 31 7d 20 .**.** {F12311}
108a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 The [sqlite3_bus
108b0 79 5f 68 61 6e 64 6c 65 72 28 44 2c 43 2c 41 29 y_handler(D,C,A)
108c0 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c ] function shall
108d0 20 72 65 70 6c 61 63 65 0a 2a 2a 20 20 20 20 20 replace.**
108e0 20 20 20 20 20 62 75 73 79 20 63 61 6c 6c 62 61 busy callba
108f0 63 6b 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 ck in the [datab
10900 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
10910 44 20 77 69 74 68 20 61 20 6e 65 77 0a 2a 2a 20 D with a new.**
10920 20 20 20 20 20 20 20 20 20 61 20 6e 65 77 20 62 a new b
10930 75 73 79 20 68 61 6e 64 6c 65 72 20 43 20 61 6e usy handler C an
10940 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 d application da
10950 74 61 20 70 6f 69 6e 74 65 72 20 41 2e 0a 2a 2a ta pointer A..**
10960 0a 2a 2a 20 7b 46 31 32 33 31 32 7d 20 4e 65 77 .** {F12312} New
10970 6c 79 20 63 72 65 61 74 65 64 20 5b 64 61 74 61 ly created [data
10980 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
10990 5d 20 73 68 61 6c 6c 20 68 61 76 65 20 61 20 62 ] shall have a b
109a0 75 73 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 usy.**
109b0 68 61 6e 64 6c 65 72 20 6f 66 20 4e 55 4c 4c 2e handler of NULL.
109c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 34 7d 20 .**.** {F12314}
109d0 57 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 When two or more
109e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
109f0 63 74 69 6f 6e 73 5d 20 73 68 61 72 65 20 61 0a ctions] share a.
10a00 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
10a10 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 ite3_enable_shar
10a20 65 64 5f 63 61 63 68 65 20 7c 20 63 6f 6d 6d 6f ed_cache | commo
10a30 6e 20 63 61 63 68 65 5d 2c 0a 2a 2a 20 20 20 20 n cache],.**
10a40 20 20 20 20 20 20 74 68 65 20 62 75 73 79 20 68 the busy h
10a50 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 64 andler for the d
10a60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
10a70 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 on currently usi
10a80 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ng.** t
10a90 68 65 20 63 61 63 68 65 20 73 68 61 6c 6c 20 62 he cache shall b
10aa0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 e invoked when t
10ab0 68 65 20 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 he cache encount
10ac0 65 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a ers a lock..**.*
10ad0 2a 20 7b 46 31 32 33 31 36 7d 20 49 66 20 61 20 * {F12316} If a
10ae0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c busy handler cal
10af0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 lback returns ze
10b00 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c ro, then the SQL
10b10 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a ite interface.**
10b20 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 70 that p
10b30 72 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b rovoked the lock
10b40 69 6e 67 20 65 76 65 6e 74 20 73 68 61 6c 6c 20 ing event shall
10b50 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 return [SQLITE_B
10b60 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 USY]..**.** {F12
10b70 33 31 38 7d 20 53 51 4c 69 74 65 20 73 68 61 6c 318} SQLite shal
10b80 6c 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 62 75 l invokes the bu
10b90 73 79 20 68 61 6e 64 6c 65 72 20 77 69 74 68 20 sy handler with
10ba0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 77 68 two arguments wh
10bb0 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ich.**
10bc0 61 72 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 are a copy of th
10bd0 65 20 70 6f 69 6e 74 65 72 20 73 75 70 70 6c 69 e pointer suppli
10be0 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61 ed by the 3rd pa
10bf0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 rameter to.**
10c00 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
10c10 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 busy_handler()]
10c20 61 6e 64 20 61 20 63 6f 75 6e 74 20 6f 66 20 74 and a count of t
10c30 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 he number of pri
10c40 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 or.** i
10c50 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
10c60 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 e busy handler f
10c70 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b or the same lock
10c80 69 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a ing event..**.**
10c90 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a LIMITATIONS:.**
10ca0 0a 2a 2a 20 7b 41 31 32 33 31 39 7d 20 41 20 62 .** {A12319} A b
10cb0 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 usy handler must
10cc0 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 not close the d
10cd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
10ce0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f on.** o
10cf0 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 r [prepared stat
10d00 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f ement] that invo
10d10 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e ked the busy han
10d20 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c dler..*/.int sql
10d30 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
10d40 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 r(sqlite3*, int(
10d50 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 *)(void*,int), v
10d60 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
10d70 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 PI3REF: Set A Bu
10d80 73 79 20 54 69 6d 65 6f 75 74 20 7b 46 31 32 33 sy Timeout {F123
10d90 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 40}.**.** This r
10da0 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 outine sets a [s
10db0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
10dc0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c ler | busy handl
10dd0 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a er] that sleeps.
10de0 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 ** for a specifi
10df0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d ed amount of tim
10e00 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 e when a table i
10e10 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 s locked. The h
10e20 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 andler.** will s
10e30 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 leep multiple ti
10e40 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 mes until at lea
10e50 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 st "ms" millisec
10e60 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 onds of sleeping
10e70 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c .** have accumul
10e80 61 74 65 64 2e 20 7b 46 31 32 33 34 33 7d 20 41 ated. {F12343} A
10e90 66 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 fter "ms" millis
10ea0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 econds of sleepi
10eb0 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c ng,.** the handl
10ec0 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 er returns 0 whi
10ed0 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 ch causes [sqlit
10ee0 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 e3_step()] to re
10ef0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f turn.** [SQLITE_
10f00 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 BUSY] or [SQLITE
10f10 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e _IOERR_BLOCKED].
10f20 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 .**.** Calling t
10f30 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 his routine with
10f40 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 an argument les
10f50 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 s than or equal
10f60 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 to zero.** turns
10f70 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 off all busy ha
10f80 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ndlers..**.** Th
10f90 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ere can only be
10fa0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 a single busy ha
10fb0 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 ndler for a part
10fc0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
10fd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
10fe0 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f any any given mo
10ff0 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 ment. If anothe
11000 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a r busy handler.*
11010 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 * was defined (
11020 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 using [sqlite3_b
11030 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 usy_handler()])
11040 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 prior to calling
11050 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
11060 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 , that other bus
11070 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 y handler is cle
11080 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 ared..**.** INVA
11090 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 RIANTS:.**.** {F
110a0 31 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 12341} The [sqli
110b0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
110c0 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 ()] function sha
110d0 6c 6c 20 6f 76 65 72 72 69 64 65 20 61 6e 79 20 ll override any
110e0 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 prior.**
110f0 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f [sqlite3_busy_
11100 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73 timeout()] or [s
11110 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
11120 6c 65 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a ler()] setting.*
11130 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 * on th
11140 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 e same [database
11150 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
11160 0a 2a 2a 20 7b 46 31 32 33 34 33 7d 20 49 66 20 .** {F12343} If
11170 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
11180 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 r to [sqlite3_bu
11190 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 sy_timeout()] is
111a0 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 less than.**
111b0 20 20 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20 or equal
111c0 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 to zero, then th
111d0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73 e busy handler s
111e0 68 61 6c 6c 20 62 65 20 63 6c 65 61 72 65 64 20 hall be cleared
111f0 73 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 so that.**
11200 20 20 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65 all subseque
11210 6e 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 nt locking event
11220 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 s immediately re
11230 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 turn [SQLITE_BUS
11240 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 Y]..**.** {F1234
11250 34 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 4} If the 2nd pa
11260 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
11270 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
11280 28 29 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76 ()] is a positiv
11290 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 e.** nu
112a0 6d 62 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 mber N, then a b
112b0 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c usy handler shal
112c0 6c 20 62 65 20 73 65 74 20 74 68 61 74 20 72 65 l be set that re
112d0 70 65 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a peatedly calls.*
112e0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 78 * the x
112f0 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69 Sleep() method i
11300 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 n the [sqlite3_v
11310 66 73 20 7c 20 56 46 53 20 69 6e 74 65 72 66 61 fs | VFS interfa
11320 63 65 5d 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 ce] until.**
11330 20 20 20 20 20 20 65 69 74 68 65 72 20 74 68 65 either the
11340 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20 lock clears or
11350 75 6e 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61 until the cumula
11360 74 69 76 65 20 73 6c 65 65 70 20 74 69 6d 65 0a tive sleep time.
11370 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 70 6f ** repo
11380 72 74 65 64 20 62 61 63 6b 20 62 79 20 78 53 6c rted back by xSl
11390 65 65 70 28 29 20 65 78 63 65 65 64 73 20 4e 20 eep() exceeds N
113a0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f milliseconds..*/
113b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 .int sqlite3_bus
113c0 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 y_timeout(sqlite
113d0 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 3*, int ms);../*
113e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
113f0 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e nvenience Routin
11400 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 es For Running Q
11410 75 65 72 69 65 73 20 7b 46 31 32 33 37 30 7d 0a ueries {F12370}.
11420 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e **.** Definition
11430 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 : A <b>result ta
11440 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 ble</b> is memor
11450 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 y data structure
11460 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a created by the.
11470 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f ** [sqlite3_get_
11480 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 table()] interfa
11490 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 ce. A result ta
114a0 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a ble records the.
114b0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 ** complete quer
114c0 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f y results from o
114d0 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 ne or more queri
114e0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 es..**.** The ta
114f0 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 ble conceptually
11500 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 has a number of
11510 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e rows and column
11520 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 s. But.** these
11530 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 numbers are not
11540 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 part of the res
11550 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 ult table itself
11560 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 . These.** numb
11570 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 ers are obtained
11580 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 separately. Le
11590 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 t N be the numbe
115a0 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 r of rows.** and
115b0 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 M be the number
115c0 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a of columns..**.
115d0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c ** A result tabl
115e0 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 e is an array of
115f0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 pointers to zer
11600 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
11610 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 -8 strings..** T
11620 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d here are (N+1)*M
11630 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 elements in the
11640 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 array. The fir
11650 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f st M pointers po
11660 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 int.** to zero-t
11670 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 erminated string
11680 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 s that contain
11690 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 the names of the
116a0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 columns..** The
116b0 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 remaining entri
116c0 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 es all point to
116d0 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 query results.
116e0 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 NULL values resu
116f0 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f lt.** in NULL po
11700 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 inters. All oth
11710 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e er values are in
11720 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 their UTF-8 zer
11730 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
11740 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 string represent
11750 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 ation as returne
11760 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f d by [sqlite3_co
11770 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a lumn_text()]..**
11780 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 .** A result tab
11790 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 le might consist
117a0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 of one or more
117b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
117c0 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 ns..** It is not
117d0 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 safe to pass a
117e0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 result table dir
117f0 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 ectly to [sqlite
11800 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 3_free()]..** A
11810 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f result table sho
11820 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 uld be deallocat
11830 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
11840 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 3_free_table()].
11850 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 .**.** As an exa
11860 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 mple of the resu
11870 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c lt table format,
11880 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 suppose a query
11890 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 result.** is as
118a0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
118b0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
118c0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 >.** Name
118d0 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a | Age.**
118e0 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d --------
118f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a ---------------.
11900 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 ** Alice
11910 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 | 43.**
11920 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 Bob
11930 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 | 28.**
11940 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 Cindy | 21
11950 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
11960 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
11970 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 ere are two colu
11980 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 mn (M==2) and th
11990 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e ree rows (N==3).
119a0 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 Thus the.** re
119b0 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 sult table has 8
119c0 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f entries. Suppo
119d0 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 se the result ta
119e0 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a ble is stored.**
119f0 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d in an array nam
11a00 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 es azResult. Th
11a10 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 en azResult hold
11a20 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a s this content:.
11a30 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
11a40 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 e><pre>.**
11a50 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 azResult[0
11a60 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 ] = "Name";.**
11a70 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
11a80 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 91;1] = "Age";.*
11a90 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
11aa0 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 t[2] = "Alic
11ab0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a e";.** az
11ac0 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 Result[3] =
11ad0 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 "43";.**
11ae0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 azResult[4]
11af0 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 = "Bob";.**
11b00 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
11b10 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 5] = "28";.**
11b20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
11b30 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 1;6] = "Cindy";.
11b40 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
11b50 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 lt[7] = "21"
11b60 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
11b70 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
11b80 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
11b90 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 able() function
11ba0 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 evaluates one or
11bb0 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c more.** semicol
11bc0 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c on-separated SQL
11bd0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 statements in t
11be0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 he zero-terminat
11bf0 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 ed UTF-8.** stri
11c00 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 ng of its 2nd pa
11c10 72 61 6d 65 74 65 72 2e 20 20 49 74 20 72 65 74 rameter. It ret
11c20 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 urns a result ta
11c30 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f ble to the.** po
11c40 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 inter given in i
11c50 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 ts 3rd parameter
11c60 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 ..**.** After th
11c70 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 e calling functi
11c80 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 on has finished
11c90 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 using the result
11ca0 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 , it should.** p
11cb0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 ass the pointer
11cc0 74 6f 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 to the result ta
11cd0 62 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 ble to sqlite3_f
11ce0 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f ree_table() in o
11cf0 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 rder to.** relea
11d00 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 se the memory th
11d10 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e at was malloced.
11d20 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 Because of the
11d30 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c way the.** [sql
11d40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 ite3_malloc()] h
11d50 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 appens within sq
11d60 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
11d70 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a ), the calling.*
11d80 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 * function must
11d90 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 not try to call
11da0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
11db0 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 directly. Only
11dc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 .** [sqlite3_fre
11dd0 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 e_table()] is ab
11de0 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 le to release th
11df0 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c e memory properl
11e00 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a y and safely..**
11e10 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
11e20 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 get_table() inte
11e30 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 rface is impleme
11e40 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 nted as a wrappe
11e50 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c r around.** [sql
11e60 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 ite3_exec()]. T
11e70 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
11e80 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 able() routine d
11e90 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 oes not have acc
11ea0 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e ess.** to any in
11eb0 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 ternal data stru
11ec0 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 ctures of SQLite
11ed0 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 . It uses only
11ee0 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e the public.** in
11ef0 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 terface defined
11f00 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 here. As a cons
11f10 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 equence, errors
11f20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 that occur in th
11f30 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 e.** wrapper lay
11f40 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 er outside of th
11f50 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 e internal [sqli
11f60 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c te3_exec()] call
11f70 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c are not.** refl
11f80 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 ected in subsequ
11f90 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ent calls to [sq
11fa0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
11fb0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 or [sqlite3_err
11fc0 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e msg()]..**.** IN
11fd0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
11fe0 7b 46 31 32 33 37 31 7d 20 49 66 20 61 20 5b 73 {F12371} If a [s
11ff0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
12000 28 29 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d 6f ()] fails a memo
12010 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 ry allocation, t
12020 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hen.**
12030 69 74 20 73 68 61 6c 6c 20 66 72 65 65 20 74 68 it shall free th
12040 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 75 e result table u
12050 6e 64 65 72 20 63 6f 6e 73 74 72 75 63 74 69 6f nder constructio
12060 6e 2c 20 61 62 6f 72 74 20 74 68 65 0a 2a 2a 20 n, abort the.**
12070 20 20 20 20 20 20 20 20 20 71 75 65 72 79 20 69 query i
12080 6e 20 70 72 6f 63 65 73 73 2c 20 73 6b 69 70 20 n process, skip
12090 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 71 any subsequent q
120a0 75 65 72 69 65 73 2c 20 73 65 74 20 74 68 65 0a ueries, set the.
120b0 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 70 61 7a ** *paz
120c0 52 65 73 75 6c 74 20 6f 75 74 70 75 74 20 70 6f Result output po
120d0 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 61 6e inter to NULL an
120e0 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 d return [SQLITE
120f0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b _NOMEM]..**.** {
12100 46 31 32 33 37 33 7d 20 49 66 20 74 68 65 20 70 F12373} If the p
12110 6e 43 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 74 65 nColumn paramete
12120 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 r to [sqlite3_ge
12130 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f t_table()] is no
12140 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 t NULL.**
12150 20 20 20 74 68 65 6e 20 61 20 73 75 63 63 65 73 then a succes
12160 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 sful invocation
12170 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f of [sqlite3_get_
12180 74 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a table()] shall.*
12190 2a 20 20 20 20 20 20 20 20 20 20 77 72 69 74 65 * write
121a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
121b0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a olumns in the.**
121c0 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 result
121d0 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 set of the quer
121e0 79 20 69 6e 74 6f 20 2a 70 6e 43 6f 6c 75 6d 6e y into *pnColumn
121f0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 34 7d ..**.** {F12374}
12200 20 49 66 20 74 68 65 20 70 6e 52 6f 77 20 70 61 If the pnRow pa
12210 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
12220 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d te3_get_table()]
12230 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 is not NULL.**
12240 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 61 20 then a
12250 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 successful invoc
12260 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 ation of [sqlite
12270 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 73 3_get_table()] s
12280 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 hall.**
12290 20 77 72 69 74 65 73 20 74 68 65 20 6e 75 6d 62 writes the numb
122a0 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 20 74 68 er of rows in th
122b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 e.** re
122c0 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 sult set of the
122d0 71 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e 52 6f query into *pnRo
122e0 77 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 36 w..**.** {F12376
122f0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 } A successful i
12300 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 nvocation of [sq
12310 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
12320 29 5d 20 74 68 61 74 20 63 6f 6d 70 75 74 65 73 )] that computes
12330 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 20 72 .** N r
12340 6f 77 73 20 6f 66 20 72 65 73 75 6c 74 20 77 69 ows of result wi
12350 74 68 20 43 20 63 6f 6c 75 6d 6e 73 20 70 65 72 th C columns per
12360 20 72 6f 77 20 73 68 61 6c 6c 20 6d 61 6b 65 20 row shall make
12370 2a 70 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 20 20 *pazResult.**
12380 20 20 20 20 20 20 20 70 6f 69 6e 74 20 74 6f 20 point to
12390 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e an array of poin
123a0 74 65 72 73 20 74 6f 20 28 4e 2b 31 29 2a 43 20 ters to (N+1)*C
123b0 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 74 68 strings where th
123c0 65 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 e first.**
123d0 20 20 20 20 43 20 73 74 72 69 6e 67 73 20 61 72 C strings ar
123e0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 61 e column names a
123f0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a s obtained from.
12400 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
12410 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
12420 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 74 ()] and the rest
12430 20 61 72 65 20 63 6f 6c 75 6d 6e 20 72 65 73 75 are column resu
12440 6c 74 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 lt values.**
12450 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 obtained f
12460 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c rom [sqlite3_col
12470 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a umn_text()]..**.
12480 2a 2a 20 7b 46 31 32 33 37 39 7d 20 54 68 65 20 ** {F12379} The
12490 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 70 61 values in the pa
124a0 7a 52 65 73 75 6c 74 20 61 72 72 61 79 20 72 65 zResult array re
124b0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
124c0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a e3_get_table()].
124d0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c ** shal
124e0 6c 20 72 65 6d 61 69 6e 20 76 61 6c 69 64 20 75 l remain valid u
124f0 6e 74 69 6c 20 63 6c 65 61 72 65 64 20 62 79 20 ntil cleared by
12500 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 [sqlite3_free_ta
12510 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 ble()]..**.** {F
12520 31 32 33 38 32 7d 20 57 68 65 6e 20 61 6e 20 65 12382} When an e
12530 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 rror occurs duri
12540 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 ng evaluation of
12550 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 [sqlite3_get_ta
12560 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 ble()].**
12570 20 20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 the function
12580 73 68 61 6c 6c 20 73 65 74 20 2a 70 61 7a 52 65 shall set *pazRe
12590 73 75 6c 74 20 74 6f 20 4e 55 4c 4c 2c 20 77 72 sult to NULL, wr
125a0 69 74 65 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 ite an error mes
125b0 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 sage.**
125c0 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 into memory obt
125d0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
125e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 6d te3_malloc()], m
125f0 61 6b 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ake.**
12600 2a 2a 70 7a 45 72 72 6d 73 67 20 70 6f 69 6e 74 **pzErrmsg point
12610 20 74 6f 20 74 68 61 74 20 65 72 72 6f 72 20 6d to that error m
12620 65 73 73 61 67 65 2c 20 61 6e 64 20 72 65 74 75 essage, and retu
12630 72 6e 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 rn a.**
12640 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 appropriate [er
12650 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e ror code]..*/.in
12660 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 t sqlite3_get_ta
12670 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a ble(. sqlite3 *
12680 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 db, /*
12690 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 An open database
126a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
126b0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 *zSql, /* S
126c0 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 QL to be evaluat
126d0 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a ed */. char ***
126e0 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a pazResult, /*
126f0 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 Results of the
12700 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a query */. int *
12710 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 pnRow,
12720 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 /* Number of re
12730 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 sult rows writte
12740 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 n here */. int
12750 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 *pnColumn,
12760 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 /* Number of r
12770 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 esult columns wr
12780 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 itten here */.
12790 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 char **pzErrmsg
127a0 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d /* Error m
127b0 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 sg written here
127c0 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 */.);.void sqlit
127d0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 e3_free_table(ch
127e0 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f ar **result);../
127f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
12800 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 ormatted String
12810 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f Printing Functio
12820 6e 73 20 7b 46 31 37 34 30 30 7d 0a 2a 2a 0a 2a ns {F17400}.**.*
12830 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
12840 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 are workalikes
12850 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 of the "printf()
12860 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 " family of func
12870 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 tions.** from th
12880 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 e standard C lib
12890 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rary..**.** The
128a0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
128b0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d ) and sqlite3_vm
128c0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 printf() routine
128d0 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a s write their.**
128e0 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 results into me
128f0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
12900 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
12910 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 oc()]..** The st
12920 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 rings returned b
12930 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 y these two rout
12940 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a ines should be.*
12950 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 * released by [s
12960 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 qlite3_free()].
12970 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 Both routines r
12980 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 eturn a.** NULL
12990 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 pointer if [sqli
129a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 te3_malloc()] is
129b0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
129c0 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 ate enough.** me
129d0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
129e0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e resulting strin
129f0 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 g..**.** In sqli
12a00 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 te3_snprintf() r
12a10 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 outine is simila
12a20 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 r to "snprintf()
12a30 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 " from.** the st
12a40 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
12a50 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 . The result is
12a60 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
12a70 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 e.** buffer supp
12a80 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f lied as the seco
12a90 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f nd parameter who
12aa0 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e se size is given
12ab0 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 by.** the first
12ac0 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 parameter. Note
12ad0 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 that the order
12ae0 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 of the.** first
12af0 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 two parameters i
12b00 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 s reversed from
12b10 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 snprintf(). Thi
12b20 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f s is an.** histo
12b30 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 rical accident t
12b40 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 hat cannot be fi
12b50 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 xed without brea
12b60 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 king.** backward
12b70 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e s compatibility.
12b80 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 Note also that
12b90 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
12ba0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 f().** returns a
12bb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 pointer to its
12bc0 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f buffer instead o
12bd0 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a f the number of.
12be0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 ** characters ac
12bf0 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 tually written i
12c00 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 nto the buffer.
12c10 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a We admit that.*
12c20 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
12c30 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 characters writt
12c40 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f en would be a mo
12c50 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e re useful return
12c60 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 .** value but we
12c70 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 cannot change t
12c80 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
12c90 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 n of sqlite3_snp
12ca0 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 rintf().** now w
12cb0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 ithout breaking
12cc0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a compatibility..*
12cd0 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 *.** As long as
12ce0 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 the buffer size
12cf0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 is greater than
12d00 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e zero, sqlite3_sn
12d10 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 printf().** guar
12d20 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 antees that the
12d30 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 buffer is always
12d40 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
12d50 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 . The first.**
12d60 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 parameter "n" is
12d70 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 the total size
12d80 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 of the buffer, i
12d90 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 ncluding space f
12da0 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 or.** the zero t
12db0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 erminator. So t
12dc0 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e he longest strin
12dd0 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f g that can be co
12de0 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 mpletely.** writ
12df0 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 ten will be n-1
12e00 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a characters..**.*
12e10 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
12e20 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 all implement s
12e30 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 ome additional f
12e40 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 ormatting.** opt
12e50 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 ions that are us
12e60 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 eful for constru
12e70 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d cting SQL statem
12e80 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 ents..** All of
12e90 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 the usual printf
12ea0 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 () formatting op
12eb0 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e tions apply. In
12ec0 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 addition, there
12ed0 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c .** is are "%q",
12ee0 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 "%Q", and "%z"
12ef0 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 options..**.** T
12f00 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 he %q option wor
12f10 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 ks like %s in th
12f20 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 at it substitute
12f30 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 s a null-termina
12f40 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 ted.** string fr
12f50 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 om the argument
12f60 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c list. But %q al
12f70 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 so doubles every
12f80 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e '\'' character.
12f90 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e .** %q is design
12fa0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 ed for use insid
12fb0 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 e a string liter
12fc0 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 al. By doubling
12fd0 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 each '\''.** ch
12fe0 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 aracter it escap
12ff0 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 es that characte
13000 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 r and allows it
13010 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 to be inserted i
13020 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e nto.** the strin
13030 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 g..**.** For exa
13040 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 mple, assume the
13050 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 string variable
13060 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 zText contains
13070 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a text as follows:
13080 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
13090 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 te><pre>.** cha
130a0 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 r *zText = "It's
130b0 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a a happy day!";.
130c0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
130d0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 quote>.**.** One
130e0 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 can use this te
130f0 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 xt in an SQL sta
13100 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 tement as follow
13110 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
13120 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 uote><pre>.** c
13130 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 har *zSQL = sqli
13140 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 te3_mprintf("INS
13150 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 ERT INTO table V
13160 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 ALUES('%q')", zT
13170 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 ext);.** sqlite
13180 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 3_exec(db, zSQL,
13190 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 0, 0, 0);.** s
131a0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c qlite3_free(zSQL
131b0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
131c0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
131d0 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 Because the %q f
131e0 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 ormat string is
131f0 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 used, the '\'' c
13200 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 haracter in zTex
13210 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 t.** is escaped
13220 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 and the SQL gene
13230 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c rated is as foll
13240 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ows:.**.** <bloc
13250 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
13260 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 INSERT INTO tab
13270 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 le1 VALUES('It''
13280 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 s a happy day!')
13290 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
132a0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
132b0 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 is is correct.
132c0 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 Had we used %s i
132d0 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 nstead of %q, th
132e0 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a e generated SQL.
132f0 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f ** would have lo
13300 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a oked like this:.
13310 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
13320 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 e><pre>.** INSE
13330 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 RT INTO table1 V
13340 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 ALUES('It's a ha
13350 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c ppy day!');.** <
13360 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
13370 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 e>.**.** This se
13380 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 cond example is
13390 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 an SQL syntax er
133a0 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 ror. As a gener
133b0 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 al rule you shou
133c0 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 ld.** always use
133d0 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 %q instead of %
133e0 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 s when inserting
133f0 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 text into a str
13400 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a ing literal..**.
13410 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e ** The %Q option
13420 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 works like %q e
13430 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 xcept it also ad
13440 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 ds single quotes
13450 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f around.** the o
13460 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f utside of the to
13470 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 tal string. Add
13480 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 itionally, if th
13490 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 e parameter in t
134a0 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c he.** argument l
134b0 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ist is a NULL po
134c0 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 inter, %Q substi
134d0 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 tutes the text "
134e0 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a NULL" (without.*
134f0 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 * single quotes)
13500 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 in place of the
13510 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c %Q option. So,
13520 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e for example, on
13530 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a e could say:.**.
13540 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
13550 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
13560 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 SQL = sqlite3_mp
13570 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e rintf("INSERT IN
13580 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 TO table VALUES(
13590 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a %Q)", zText);.**
135a0 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 sqlite3_exec(d
135b0 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 b, zSQL, 0, 0, 0
135c0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 );.** sqlite3_f
135d0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f ree(zSQL);.** </
135e0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
135f0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 >.**.** The code
13600 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 above will rend
13610 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c er a correct SQL
13620 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 statement in th
13630 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 e zSQL.** variab
13640 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a le even if the z
13650 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 Text variable is
13660 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
13670 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20 .**.** The "%z"
13680 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f formatting optio
13690 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 n works exactly
136a0 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68 20 74 like "%s" with t
136b0 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 he.** addition t
136c0 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 hat after the st
136d0 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 ring has been re
136e0 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e ad and copied in
136f0 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 to.** the result
13700 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 , [sqlite3_free(
13710 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 )] is called on
13720 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
13730 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e . {END}.**.** IN
13740 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
13750 7b 46 31 37 34 30 33 7d 20 20 54 68 65 20 5b 73 {F17403} The [s
13760 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 qlite3_mprintf()
13770 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 ] and [sqlite3_v
13780 6d 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 mprintf()] inter
13790 66 61 63 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 faces.**
137a0 20 20 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 return either
137b0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 pointers to zer
137c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
137d0 2d 38 20 73 74 72 69 6e 67 73 20 68 65 6c 64 20 -8 strings held
137e0 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 in.**
137f0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
13800 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
13810 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e 55 4c 4c 20 lloc()] or NULL
13820 70 6f 69 6e 74 65 72 73 20 69 66 0a 2a 2a 20 20 pointers if.**
13830 20 20 20 20 20 20 20 20 20 61 20 63 61 6c 6c 20 a call
13840 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c to [sqlite3_mall
13850 6f 63 28 29 5d 20 66 61 69 6c 73 2e 0a 2a 2a 0a oc()] fails..**.
13860 2a 2a 20 7b 46 31 37 34 30 36 7d 20 20 54 68 65 ** {F17406} The
13870 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e [sqlite3_snprin
13880 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 tf()] interface
13890 77 72 69 74 65 73 20 61 20 7a 65 72 6f 2d 74 65 writes a zero-te
138a0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 rminated.**
138b0 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 UTF-8 stri
138c0 6e 67 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 ng into the buff
138d0 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 er pointed to by
138e0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
138f0 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 meter.**
13900 20 20 20 70 72 6f 76 69 64 65 64 20 74 68 61 74 provided that
13910 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
13920 65 74 65 72 20 69 73 20 67 72 65 61 74 65 72 20 eter is greater
13930 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a than zero..**.**
13940 20 7b 46 31 37 34 30 37 7d 20 20 54 68 65 20 5b {F17407} The [
13950 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
13960 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f ()] interface do
13970 65 73 20 6e 6f 74 20 77 72 69 74 65 20 73 6c 6f es not write slo
13980 74 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 ts of.**
13990 20 20 20 69 74 73 20 6f 75 74 70 75 74 20 62 75 its output bu
139a0 66 66 65 72 20 28 74 68 65 20 73 65 63 6f 6e 64 ffer (the second
139b0 20 70 61 72 61 6d 65 74 65 72 29 20 6f 75 74 73 parameter) outs
139c0 69 64 65 20 74 68 65 20 72 61 6e 67 65 0a 2a 2a ide the range.**
139d0 20 20 20 20 20 20 20 20 20 20 20 6f 66 20 30 20 of 0
139e0 74 68 72 6f 75 67 68 20 4e 2d 31 20 28 77 68 65 through N-1 (whe
139f0 72 65 20 4e 20 69 73 20 74 68 65 20 66 69 72 73 re N is the firs
13a00 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 t parameter).**
13a10 20 20 20 20 20 20 20 20 20 20 72 65 67 61 72 64 regard
13a20 6c 65 73 73 20 6f 66 20 74 68 65 20 6c 65 6e 67 less of the leng
13a30 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 th of the string
13a40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 .** re
13a50 71 75 65 73 74 65 64 20 62 79 20 74 68 65 20 66 quested by the f
13a60 6f 72 6d 61 74 20 73 70 65 63 69 66 69 63 61 74 ormat specificat
13a70 69 6f 6e 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 ion..*/.char *sq
13a80 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f lite3_mprintf(co
13a90 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a nst char*,...);.
13aa0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d char *sqlite3_vm
13ab0 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 printf(const cha
13ac0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 r*, va_list);.ch
13ad0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 ar *sqlite3_snpr
13ae0 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 intf(int,char*,c
13af0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 onst char*, ...)
13b00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
13b10 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 F: Memory Alloca
13b20 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 7b tion Subsystem {
13b30 46 31 37 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 F17300}.**.** Th
13b40 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75 e SQLite core u
13b50 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 ses these three
13b60 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c routines for all
13b70 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 of its own.** i
13b80 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 nternal memory a
13b90 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e llocation needs.
13ba0 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 "Core" in the p
13bb0 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 revious sentence
13bc0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 .** does not inc
13bd0 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 lude operating-s
13be0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 ystem specific V
13bf0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
13c00 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f n. The.** Windo
13c10 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 ws VFS uses nati
13c20 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 ve malloc() and
13c30 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 free() for some
13c40 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a operations..**.*
13c50 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 * The sqlite3_ma
13c60 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 lloc() routine r
13c70 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
13c80 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f to a block.** o
13c90 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 f memory at leas
13ca0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e t N bytes in len
13cb0 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 gth, where N is
13cc0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a the parameter..*
13cd0 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c * If sqlite3_mal
13ce0 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 loc() is unable
13cf0 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 to obtain suffic
13d00 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d ient free.** mem
13d10 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 ory, it returns
13d20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 a NULL pointer.
13d30 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 If the paramete
13d40 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 r N to.** sqlite
13d50 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 3_malloc() is ze
13d60 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 ro or negative t
13d70 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c hen sqlite3_mall
13d80 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 oc() returns.**
13d90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
13da0 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71 **.** Calling sq
13db0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 lite3_free() wit
13dc0 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 h a pointer prev
13dd0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a iously returned.
13de0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 ** by sqlite3_ma
13df0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 lloc() or sqlite
13e00 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 3_realloc() rele
13e10 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 ases that memory
13e20 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d so.** that it m
13e30 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 ight be reused.
13e40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 The sqlite3_fre
13e50 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a e() routine is.*
13e60 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 * a no-op if is
13e70 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 called with a NU
13e80 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 LL pointer. Pas
13e90 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e sing a NULL poin
13ea0 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 ter.** to sqlite
13eb0 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 3_free() is harm
13ec0 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 less. After bei
13ed0 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 ng freed, memory
13ee0 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 .** should neith
13ef0 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 er be read nor w
13f00 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 ritten. Even re
13f10 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 ading previously
13f20 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 freed.** memory
13f30 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e might result in
13f40 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 a segmentation
13f50 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 fault or other s
13f60 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 evere error..**
13f70 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f Memory corruptio
13f80 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f n, a segmentatio
13f90 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 n fault, or othe
13fa0 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a r severe error.*
13fb0 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 * might result i
13fc0 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 f sqlite3_free()
13fd0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 is called with
13fe0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 a non-NULL point
13ff0 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e er that.** was n
14000 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ot obtained from
14010 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
14020 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 66 72 65 ) or sqlite3_fre
14030 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 e()..**.** The s
14040 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
14050 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d interface attem
14060 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a pts to resize a.
14070 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 ** prior memory
14080 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 allocation to be
14090 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 at least N byte
140a0 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 s, where N is th
140b0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 e.** second para
140c0 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f meter. The memo
140d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f ry allocation to
140e0 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 be resized is t
140f0 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 he first.** para
14100 6d 65 74 65 72 2e 20 20 49 66 20 74 68 65 20 66 meter. If the f
14110 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
14120 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
14130 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c c().** is a NULL
14140 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 pointer then it
14150 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 s behavior is id
14160 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 entical to calli
14170 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 ng.** sqlite3_ma
14180 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 lloc(N) where N
14190 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 is the second pa
141a0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
141b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a e3_realloc()..**
141c0 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 If the second p
141d0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
141e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 te3_realloc() is
141f0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 zero or.** nega
14200 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 tive then the be
14210 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c havior is exactl
14220 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 y the same as ca
14230 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 lling.** sqlite3
14240 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 _free(P) where P
14250 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 is the first pa
14260 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
14270 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a e3_realloc()..**
14280 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
14290 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 () returns a poi
142a0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 nter to a memory
142b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f allocation.** o
142c0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 f at least N byt
142d0 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 es in size or NU
142e0 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 LL if sufficient
142f0 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 memory is unava
14300 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 ilable..** If M
14310 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 is the size of t
14320 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
14330 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c ion, then min(N,
14340 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 M) bytes.** of t
14350 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
14360 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 ion are copied i
14370 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e nto the beginnin
14380 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 g of buffer retu
14390 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 rned.** by sqlit
143a0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 e3_realloc() and
143b0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
143c0 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a ation is freed..
143d0 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 72 65 ** If sqlite3_re
143e0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 alloc() returns
143f0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 NULL, then the p
14400 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a rior allocation.
14410 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e ** is not freed.
14420 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 .**.** The memor
14430 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 y returned by sq
14440 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 lite3_malloc() a
14450 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c nd sqlite3_reall
14460 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 oc().** is alway
14470 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 s aligned to at
14480 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 least an 8 byte
14490 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a boundary. {END}.
144a0 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c **.** The defaul
144b0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e t implementation
144c0 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 of the memory a
144d0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 llocation subsys
144e0 74 65 6d 20 75 73 65 73 0a 2a 2a 20 74 68 65 20 tem uses.** the
144f0 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f malloc(), reallo
14500 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 70 c() and free() p
14510 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 73 rovided by the s
14520 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
14530 79 2e 0a 2a 2a 20 7b 46 31 37 33 38 32 7d 20 48 y..** {F17382} H
14540 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 owever, if SQLit
14550 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
14560 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 th the.** SQLITE
14570 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e _MEMORY_SIZE=<i>
14580 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f NNN</i> C prepro
14590 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 28 77 68 cessor macro (wh
145a0 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a ere <i>NNN</i>.*
145b0 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 29 * is an integer)
145c0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72 , then SQLite cr
145d0 65 61 74 65 20 61 20 73 74 61 74 69 63 20 61 72 eate a static ar
145e0 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73 74 0a ray of at least.
145f0 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 ** <i>NNN</i> by
14600 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 tes in size and
14610 75 73 65 73 20 74 68 61 74 20 61 72 72 61 79 20 uses that array
14620 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 for all of its d
14630 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79 ynamic.** memory
14640 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 allocation need
14650 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 s. {END} Additi
14660 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f onal memory allo
14670 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a cator options.**
14680 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
14690 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
146a0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 ..**.** In SQLit
146b0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 e version 3.5.0
146c0 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 and 3.5.1, it wa
146d0 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 s possible to de
146e0 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 fine.** the SQLI
146f0 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 TE_OMIT_MEMORY_A
14700 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 LLOCATION which
14710 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 would cause the
14720 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c built-in.** impl
14730 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
14740 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 ese routines to
14750 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 be omitted. Tha
14760 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 t capability.**
14770 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f is no longer pro
14780 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 vided. Only bui
14790 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c lt-in memory all
147a0 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 ocators can be u
147b0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 sed..**.** The W
147c0 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 indows OS interf
147d0 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a ace layer calls.
147e0 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 ** the system ma
147f0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 lloc() and free(
14800 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 ) directly when
14810 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 converting.** fi
14820 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 lenames between
14830 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 the UTF-8 encodi
14840 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 ng used by SQLit
14850 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 e.** and whateve
14860 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 r filename encod
14870 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 ing is used by t
14880 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 he particular Wi
14890 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c ndows.** install
148a0 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 ation. Memory a
148b0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 llocation errors
148c0 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 are detected, b
148d0 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 ut.** they are r
148e0 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 eported back as
148f0 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e [SQLITE_CANTOPEN
14900 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ] or.** [SQLITE_
14910 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 IOERR] rather th
14920 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d an [SQLITE_NOMEM
14930 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 ]..**.** INVARIA
14940 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 NTS:.**.** {F173
14950 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 03} The [sqlite
14960 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 3_malloc(N)] int
14970 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 erface returns e
14980 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72 20 ither a pointer
14990 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 to.**
149a0 61 20 6e 65 77 6c 79 20 63 68 65 63 6b 65 64 2d a newly checked-
149b0 6f 75 74 20 62 6c 6f 63 6b 20 6f 66 20 61 74 20 out block of at
149c0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 6f 66 least N bytes of
149d0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 memory.**
149e0 20 20 20 20 20 74 68 61 74 20 69 73 20 38 2d 62 that is 8-b
149f0 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 yte aligned, or
14a00 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 it returns NULL
14a10 69 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 0a if it is unable.
14a20 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 ** to
14a30 66 75 6c 66 69 6c 6c 20 74 68 65 20 72 65 71 75 fulfill the requ
14a40 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 est..**.** {F173
14a50 30 34 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 04} The [sqlite
14a60 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 3_malloc(N)] int
14a70 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
14a80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 NULL pointer if
14a90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 4e 20 .** N
14aa0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 is less than or
14ab0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a equal to zero..*
14ac0 2a 0a 2a 2a 20 7b 46 31 37 33 30 35 7d 20 20 54 *.** {F17305} T
14ad0 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 he [sqlite3_free
14ae0 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 (P)] interface r
14af0 65 6c 65 61 73 65 73 20 6d 65 6d 6f 72 79 20 70 eleases memory p
14b00 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 reviously.**
14b10 20 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20 returned
14b20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
14b30 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 lloc()] or [sqli
14b40 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a te3_realloc()],.
14b50 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d 61 6b ** mak
14b60 69 6e 67 20 69 74 20 61 76 61 69 6c 61 62 6c 65 ing it available
14b70 20 66 6f 72 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a for reuse..**.*
14b80 2a 20 7b 46 31 37 33 30 36 7d 20 20 41 20 63 61 * {F17306} A ca
14b90 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 ll to [sqlite3_f
14ba0 72 65 65 28 4e 55 4c 4c 29 5d 20 69 73 20 61 20 ree(NULL)] is a
14bb0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a harmless no-op..
14bc0 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 30 7d 20 20 **.** {F17310}
14bd0 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 A call to [sqlit
14be0 65 33 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d e3_realloc(0,N)]
14bf0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 is equivalent t
14c00 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 o a call.**
14c10 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 to [sqlite
14c20 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 3_malloc(N)]..**
14c30 0a 2a 2a 20 7b 46 31 37 33 31 32 7d 20 20 41 20 .** {F17312} A
14c40 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
14c50 5f 72 65 61 6c 6c 6f 63 28 50 2c 30 29 5d 20 69 _realloc(P,0)] i
14c60 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 s equivalent to
14c70 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 a call.**
14c80 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f to [sqlite3_
14c90 66 72 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 free(P)]..**.**
14ca0 7b 46 31 37 33 31 35 7d 20 20 54 68 65 20 53 51 {F17315} The SQ
14cb0 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 5b Lite core uses [
14cc0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
14cd0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c ], [sqlite3_real
14ce0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 loc()],.**
14cf0 20 20 20 20 20 61 6e 64 20 5b 73 71 6c 69 74 65 and [sqlite
14d00 33 5f 66 72 65 65 28 29 5d 20 66 6f 72 20 61 6c 3_free()] for al
14d10 6c 20 6f 66 20 69 74 73 20 6d 65 6d 6f 72 79 20 l of its memory
14d20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e 64 0a 2a allocation and.*
14d30 2a 20 20 20 20 20 20 20 20 20 20 20 64 65 61 6c * deal
14d40 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a location needs..
14d50 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 38 7d 20 20 **.** {F17318}
14d60 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 The [sqlite3_rea
14d70 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69 6e 74 65 72 lloc(P,N)] inter
14d80 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 face returns eit
14d90 68 65 72 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a her a pointer.**
14da0 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 61 20 to a
14db0 62 6c 6f 63 6b 20 6f 66 20 63 68 65 63 6b 65 64 block of checked
14dc0 2d 6f 75 74 20 6d 65 6d 6f 72 79 20 6f 66 20 61 -out memory of a
14dd0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 t least N bytes
14de0 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 in size.**
14df0 20 20 20 20 20 74 68 61 74 20 69 73 20 38 2d 62 that is 8-b
14e00 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 yte aligned, or
14e10 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
14e20 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 31 7d 20 20 **.** {F17321}
14e30 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 When [sqlite3_re
14e40 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 alloc(P,N)] retu
14e50 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 rns a non-NULL p
14e60 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 ointer, it first
14e70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f .** co
14e80 70 69 65 73 20 74 68 65 20 66 69 72 73 74 20 4b pies the first K
14e90 20 62 79 74 65 73 20 6f 66 20 63 6f 6e 74 65 6e bytes of conten
14ea0 74 20 66 72 6f 6d 20 50 20 69 6e 74 6f 20 74 68 t from P into th
14eb0 65 20 6e 65 77 6c 79 0a 2a 2a 20 20 20 20 20 20 e newly.**
14ec0 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 62 allocated b
14ed0 6c 6f 63 6b 2c 20 77 68 65 72 65 20 4b 20 69 73 lock, where K is
14ee0 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66 20 4e the lesser of N
14ef0 20 61 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 and the size of
14f00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 .** th
14f10 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a e buffer P..**.*
14f20 2a 20 7b 46 31 37 33 32 32 7d 20 20 57 68 65 6e * {F17322} When
14f30 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
14f40 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 c(P,N)] returns
14f50 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 a non-NULL point
14f60 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 er, it first.**
14f70 20 20 20 20 20 20 20 20 20 20 72 65 6c 65 61 73 releas
14f80 65 73 20 74 68 65 20 62 75 66 66 65 72 20 50 2e es the buffer P.
14f90 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 33 7d 20 .**.** {F17323}
14fa0 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 When [sqlite3_r
14fb0 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 ealloc(P,N)] ret
14fc0 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 20 62 urns NULL, the b
14fd0 75 66 66 65 72 20 50 20 69 73 0a 2a 2a 20 20 20 uffer P is.**
14fe0 20 20 20 20 20 20 20 20 6e 6f 74 20 6d 6f 64 69 not modi
14ff0 66 69 65 64 20 6f 72 20 72 65 6c 65 61 73 65 64 fied or released
15000 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 ..**.** LIMITATI
15010 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 ONS:.**.** {A173
15020 35 30 7d 20 20 54 68 65 20 70 6f 69 6e 74 65 72 50} The pointer
15030 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 arguments to [s
15040 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 qlite3_free()] a
15050 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c nd [sqlite3_real
15060 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 loc()].**
15070 20 20 20 20 6d 75 73 74 20 62 65 20 65 69 74 68 must be eith
15080 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 er NULL or else
15090 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 pointers obtaine
150a0 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a d from a prior.*
150b0 2a 20 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f * invo
150c0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 cation of [sqlit
150d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 e3_malloc()] or
150e0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
150f0 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a ()] that have.**
15100 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 79 not y
15110 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 et been released
15120 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 31 7d ..**.** {A17351}
15130 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f The applicatio
15140 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 n must not read
15150 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 or write any par
15160 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 t of.**
15170 20 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d a block of mem
15180 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 ory after it has
15190 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 been released u
151a0 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 sing.**
151b0 20 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 [sqlite3_free(
151c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
151d0 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f ealloc()]..*/.vo
151e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c id *sqlite3_mall
151f0 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 oc(int);.void *s
15200 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 qlite3_realloc(v
15210 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 oid*, int);.void
15220 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f sqlite3_free(vo
15230 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
15240 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c I3REF: Memory Al
15250 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 locator Statisti
15260 63 73 20 7b 46 31 37 33 37 30 7d 0a 2a 2a 0a 2a cs {F17370}.**.*
15270 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 * SQLite provide
15280 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 s these two inte
15290 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 rfaces for repor
152a0 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 ting on the stat
152b0 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 us.** of the [sq
152c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c lite3_malloc()],
152d0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
152e0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ], and [sqlite3_
152f0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f realloc()].** ro
15300 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f utines, which fo
15310 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 rm the built-in
15320 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
15330 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a n subsystem..**.
15340 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
15350 2a 0a 2a 2a 20 7b 46 31 37 33 37 31 7d 20 54 68 *.** {F17371} Th
15360 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 e [sqlite3_memor
15370 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e y_used()] routin
15380 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 e returns the nu
15390 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a mber of bytes.**
153a0 20 20 20 20 20 20 20 20 20 20 6f 66 20 6d 65 6d of mem
153b0 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 ory currently ou
153c0 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f tstanding (mallo
153d0 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 ced but not free
153e0 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 d)..**.** {F1737
153f0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 3} The [sqlite3_
15400 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
15410 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 ()] routine retu
15420 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a rns the maximum.
15430 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 ** valu
15440 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 e of [sqlite3_me
15450 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e mory_used()] sin
15460 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 ce the high-wate
15470 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 r mark.**
15480 20 20 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 was last rese
15490 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 34 t..**.** {F17374
154a0 7d 20 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 } The values ret
154b0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
154c0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 3_memory_used()]
154d0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
154e0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
154f0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e _highwater()] in
15500 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 clude any overhe
15510 61 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 ad.** a
15520 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 dded by SQLite i
15530 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 n its implementa
15540 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
15550 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 _malloc()],.**
15560 20 20 20 20 20 20 20 20 62 75 74 20 6e 6f 74 20 but not
15570 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 overhead added b
15580 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c y the any underl
15590 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 ying system libr
155a0 61 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ary.**
155b0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 routines that [s
155c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
155d0 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a may call..**.**
155e0 20 7b 46 31 37 33 37 35 7d 20 54 68 65 20 6d 65 {F17375} The me
155f0 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 mory high-water
15600 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f mark is reset to
15610 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c the current val
15620 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 ue of.**
15630 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 [sqlite3_memor
15640 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 y_used()] if and
15650 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 only if the par
15660 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 ameter to.**
15670 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d [sqlite3_m
15680 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
15690 29 5d 20 69 73 20 74 72 75 65 2e 20 20 54 68 65 )] is true. The
156a0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a value returned.
156b0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b ** by [
156c0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
156d0 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 ighwater(1)] is
156e0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d the high-water m
156f0 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ark.**
15700 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 prior to the res
15710 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 et..*/.sqlite3_i
15720 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d nt64 sqlite3_mem
15730 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a ory_used(void);.
15740 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
15750 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
15760 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 hwater(int reset
15770 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Flag);../*.** CA
15780 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 PI3REF: Pseudo-R
15790 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e andom Number Gen
157a0 65 72 61 74 6f 72 20 7b 46 31 37 33 39 30 7d 0a erator {F17390}.
157b0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e **.** SQLite con
157c0 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 tains a high-qua
157d0 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 lity pseudo-rand
157e0 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 om number genera
157f0 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 tor (PRNG) used
15800 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e to.** select ran
15810 64 6f 6d 20 52 4f 57 49 44 73 20 77 68 65 6e 20 dom ROWIDs when
15820 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 inserting new re
15830 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 cords into a tab
15840 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 le that.** alrea
15850 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 dy uses the larg
15860 65 73 74 20 70 6f 73 73 69 62 6c 65 20 52 4f 57 est possible ROW
15870 49 44 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 ID. The PRNG is
15880 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a also used for.*
15890 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 * the build-in r
158a0 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 andom() and rand
158b0 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e omblob() SQL fun
158c0 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e ctions. This in
158d0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a terface allows.*
158e0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 * applications t
158f0 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d o access the sam
15900 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 e PRNG for other
15910 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a purposes..**.**
15920 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 A call to this
15930 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e routine stores N
15940 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d bytes of random
15950 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 ness into buffer
15960 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 P..**.** The fi
15970 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f rst time this ro
15980 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 utine is invoked
15990 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 (either interna
159a0 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 lly or by.** the
159b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 application) th
159c0 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 e PRNG is seeded
159d0 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 using randomnes
159e0 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 s obtained.** fr
159f0 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 om the xRandomne
15a00 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 ss method of the
15a10 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 default [sqlite
15a20 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 3_vfs] object..*
15a30 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 * On all subsequ
15a40 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c ent invocations,
15a50 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 the pseudo-rand
15a60 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 omness is genera
15a70 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c ted.** internall
15a80 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 y and without re
15a90 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 course to the [s
15aa0 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e qlite3_vfs] xRan
15ab0 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f domness.** metho
15ac0 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 d..**.** INVARIA
15ad0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 NTS:.**.** {F173
15ae0 39 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 92} The [sqlite3
15af0 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c 50 29 _randomness(N,P)
15b00 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 ] interface writ
15b10 65 73 20 4e 20 62 79 74 65 73 20 6f 66 0a 2a 2a es N bytes of.**
15b20 20 20 20 20 20 20 20 20 20 20 68 69 67 68 2d 71 high-q
15b30 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 uality pseudo-ra
15b40 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 ndomness into bu
15b50 66 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20 ffer P..*/.void
15b60 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 sqlite3_randomne
15b70 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a ss(int N, void *
15b80 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 P);../*.** CAPI3
15b90 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d REF: Compile-Tim
15ba0 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 e Authorization
15bb0 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 35 30 Callbacks {F1250
15bc0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 0}.**.** This ro
15bd0 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 utine registers
15be0 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c a authorizer cal
15bf0 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 lback with a par
15c00 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 ticular.** [data
15c10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
15c20 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 , supplied in th
15c30 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
15c40 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 ..** The authori
15c50 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
15c60 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 invoked as SQL s
15c70 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 tatements are be
15c80 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 ing compiled.**
15c90 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 by [sqlite3_prep
15ca0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 are()] or its va
15cb0 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f riants [sqlite3_
15cc0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a prepare_v2()],.*
15cd0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
15ce0 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c re16()] and [sql
15cf0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
15d00 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 2()]. At variou
15d10 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 s.** points duri
15d20 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 ng the compilati
15d30 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c on process, as l
15d40 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 ogic is being cr
15d50 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 eated.** to perf
15d60 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 orm various acti
15d70 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 ons, the authori
15d80 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
15d90 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 invoked to.** se
15da0 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f e if those actio
15db0 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 ns are allowed.
15dc0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 The authorizer
15dd0 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a callback should.
15de0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ** return [SQLIT
15df0 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 E_OK] to allow t
15e00 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 he action, [SQLI
15e10 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 TE_IGNORE] to di
15e20 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 sallow the.** sp
15e30 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 ecific action bu
15e40 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 t allow the SQL
15e50 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e statement to con
15e60 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 tinue to be.** c
15e70 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c ompiled, or [SQL
15e80 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 ITE_DENY] to cau
15e90 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 se the entire SQ
15ea0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 L statement to b
15eb0 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 e.** rejected wi
15ec0 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 th an error. If
15ed0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
15ee0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
15ef0 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 .** any value ot
15f00 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
15f10 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 _IGNORE], [SQLIT
15f20 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 E_OK], or [SQLIT
15f30 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 E_DENY].** then
15f40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 the [sqlite3_pre
15f50 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 pare_v2()] or eq
15f60 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 uivalent call th
15f70 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 at triggered.**
15f80 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 the authorizer w
15f90 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e ill fail with an
15fa0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a error message..
15fb0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 **.** When the c
15fc0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
15fd0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 [SQLITE_OK], tha
15fe0 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 t means the oper
15ff0 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 ation.** request
16000 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 ed is ok. When
16010 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
16020 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e urns [SQLITE_DEN
16030 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 Y], the.** [sqli
16040 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
16050 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 ] or equivalent
16060 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 call that trigge
16070 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f red the.** autho
16080 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 rizer will fail
16090 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 with an error me
160a0 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 ssage explaining
160b0 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 that.** access
160c0 69 73 20 64 65 6e 69 65 64 2e 20 20 49 66 20 74 is denied. If t
160d0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f he authorizer co
160e0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 de is [SQLITE_RE
160f0 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 AD].** and the c
16100 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
16110 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
16120 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 then the.** [pre
16130 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
16140 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f statement is co
16150 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 nstructed to sub
16160 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c stitute.** a NUL
16170 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 L value in place
16180 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f of the table co
16190 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 lumn that would
161a0 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 have.** been rea
161b0 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d d if [SQLITE_OK]
161c0 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e had been return
161d0 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 ed. The [SQLITE
161e0 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 _IGNORE].** retu
161f0 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 rn can be used t
16200 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 o deny an untrus
16210 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 ted user access
16220 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a to individual.**
16230 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 columns of a ta
16240 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ble..**.** The f
16250 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
16260 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 o the authorizer
16270 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 callback is a c
16280 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 opy of the third
16290 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f .** parameter to
162a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 the sqlite3_set
162b0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e _authorizer() in
162c0 74 65 72 66 61 63 65 2e 20 54 68 65 20 73 65 63 terface. The sec
162d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a ond parameter.**
162e0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
162f0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b is an integer [
16300 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 SQLITE_COPY | ac
16310 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 tion code] that
16320 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 specifies.** the
16330 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 particular acti
16340 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 on to be authori
16350 7a 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 74 zed. The third t
16360 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 hrough sixth par
16370 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 ameters.** to th
16380 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a e callback are z
16390 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ero-terminated s
163a0 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 trings that cont
163b0 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a ain additional.*
163c0 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 * details about
163d0 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 the action to be
163e0 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a authorized..**.
163f0 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 ** An authorizer
16400 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 is used when [s
16410 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c qlite3_prepare |
16420 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 preparing].** S
16430 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 QL statements fr
16440 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 om an untrusted
16450 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 source, to ensur
16460 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 e that the SQL s
16470 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 tatements.** do
16480 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 not try to acces
16490 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 s data they are
164a0 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 not allowed to s
164b0 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 ee, or that they
164c0 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 do not.** try t
164d0 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 o execute malici
164e0 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 ous statements t
164f0 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 hat damage the d
16500 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a atabase. For.**
16510 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 example, an app
16520 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c lication may all
16530 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 ow a user to ent
16540 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 er arbitrary.**
16550 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 SQL queries for
16560 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 evaluation by a
16570 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 database. But t
16580 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
16590 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 oes.** not want
165a0 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 the user to be a
165b0 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 ble to make arbi
165c0 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f trary changes to
165d0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
165e0 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 . An authorizer
165f0 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 could then be p
16600 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c ut in place whil
16610 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e e the.** user-en
16620 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 tered SQL is bei
16630 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ng [sqlite3_prep
16640 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 are | prepared]
16650 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 that.** disallow
16660 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 s everything exc
16670 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 ept [SELECT] sta
16680 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 tements..**.** A
16690 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
166a0 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 need to process
166b0 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 SQL from untrus
166c0 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d ted sources.** m
166d0 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 ight also consid
166e0 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f er lowering reso
166f0 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e urce limits usin
16700 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 g [sqlite3_limit
16710 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 ()].** and limit
16720 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a ing database siz
16730 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 e using the [max
16740 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 _page_count] [PR
16750 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 AGMA].** in addi
16760 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e tion to using an
16770 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a authorizer..**.
16780 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 ** Only a single
16790 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 authorizer can
167a0 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 be in place on a
167b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
167c0 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d tion.** at a tim
167d0 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f e. Each call to
167e0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 sqlite3_set_aut
167f0 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 horizer override
16800 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 s the.** previou
16810 73 20 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 s call. Disable
16820 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
16830 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 by installing a
16840 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a NULL callback..*
16850 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * The authorizer
16860 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 is disabled by
16870 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e default..**.** N
16880 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 ote that the aut
16890 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
168a0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 is invoked only
168b0 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 during.** [sqli
168c0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f te3_prepare()] o
168d0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 r its variants.
168e0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 Authorization i
168f0 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d s not.** perform
16900 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d ed during statem
16910 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 ent evaluation i
16920 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 n [sqlite3_step(
16930 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 )]..**.** INVARI
16940 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 ANTS:.**.** {F12
16950 35 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 501} The [sqlite
16960 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
16970 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 (D,...)] interfa
16980 63 65 20 72 65 67 69 73 74 65 72 73 20 61 0a 2a ce registers a.*
16990 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 68 6f * autho
169a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 rizer callback w
169b0 69 74 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e ith database con
169c0 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a nection D..**.**
169d0 20 7b 46 31 32 35 30 32 7d 20 54 68 65 20 61 75 {F12502} The au
169e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
169f0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 k is invoked as
16a00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 SQL statements a
16a10 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 re.** b
16a20 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 2e 0a 2a eing compiled..*
16a30 2a 0a 2a 2a 20 7b 46 31 32 35 30 33 7d 20 49 66 *.** {F12503} If
16a40 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
16a50 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
16a60 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 any value other
16a70 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 than.**
16a80 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 [SQLITE_IGNORE
16a90 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 ], [SQLITE_OK],
16aa0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d or [SQLITE_DENY]
16ab0 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 , then.**
16ac0 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f the [sqlite3_
16ad0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
16ae0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c equivalent call
16af0 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 that caused.**
16b00 20 20 20 20 20 20 20 20 20 74 68 65 20 61 75 74 the aut
16b10 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
16b20 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 to run shall fa
16b30 69 6c 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 il with an.**
16b40 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 [SQLITE_E
16b50 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 RROR] error code
16b60 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 and an appropri
16b70 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 ate error messag
16b80 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 34 e..**.** {F12504
16b90 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f } When the autho
16ba0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 rizer callback r
16bb0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
16bc0 4b 5d 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f K], the operatio
16bd0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 n.** de
16be0 73 63 72 69 62 65 64 20 69 73 20 70 72 6f 63 65 scribed is proce
16bf0 73 73 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a ssed normally..*
16c00 2a 0a 2a 2a 20 7b 46 31 32 35 30 35 7d 20 57 68 *.** {F12505} Wh
16c10 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 en the authorize
16c20 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 r callback retur
16c30 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d ns [SQLITE_DENY]
16c40 2c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 , the.**
16c50 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 [sqlite3_prepa
16c60 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 re_v2()] or equi
16c70 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 valent call that
16c80 20 63 61 75 73 65 64 20 74 68 65 0a 2a 2a 20 20 caused the.**
16c90 20 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a authoriz
16ca0 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 er callback to r
16cb0 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a un shall fail.**
16cc0 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 61 with a
16cd0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d n [SQLITE_ERROR]
16ce0 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 error code and
16cf0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 an error message
16d00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 70 .** exp
16d10 6c 61 69 6e 69 6e 67 20 74 68 61 74 20 61 63 63 laining that acc
16d20 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a ess is denied..*
16d30 2a 0a 2a 2a 20 7b 46 31 32 35 30 36 7d 20 49 66 *.** {F12506} If
16d40 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
16d50 63 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 code (the 2nd pa
16d60 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 rameter to the a
16d70 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 uthorizer.**
16d80 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 callback)
16d90 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d is [SQLITE_READ]
16da0 20 61 6e 64 20 74 68 65 20 61 75 74 68 6f 72 69 and the authori
16db0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 zer callback ret
16dc0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 urns.**
16dd0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
16de0 2c 20 74 68 65 6e 20 74 68 65 20 70 72 65 70 61 , then the prepa
16df0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 red statement is
16e00 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 0a constructed to.
16e10 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 65 ** inse
16e20 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 rt a NULL value
16e30 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 in place of the
16e40 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 table column tha
16e50 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 t would have.**
16e60 20 20 20 20 20 20 20 20 20 62 65 65 6e 20 72 65 been re
16e70 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b ad if [SQLITE_OK
16e80 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 ] had been retur
16e90 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 ned..**.** {F125
16ea0 30 37 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 07} If the autho
16eb0 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 rizer code (the
16ec0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 2nd parameter to
16ed0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a the authorizer.
16ee0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c ** call
16ef0 62 61 63 6b 29 20 69 73 20 61 6e 79 74 68 69 6e back) is anythin
16f00 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 g other than [SQ
16f10 4c 49 54 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e LITE_READ], then
16f20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 .** a r
16f30 65 74 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 eturn of [SQLITE
16f40 5f 49 47 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 _IGNORE] has the
16f50 20 73 61 6d 65 20 65 66 66 65 63 74 20 61 73 20 same effect as
16f60 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 0a 2a [SQLITE_DENY]..*
16f70 2a 0a 2a 2a 20 7b 46 31 32 35 31 30 7d 20 54 68 *.** {F12510} Th
16f80 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
16f90 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 r to the authori
16fa0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
16fb0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 a copy of.**
16fc0 20 20 20 20 20 20 74 68 65 20 74 68 69 72 64 20 the third
16fd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
16fe0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
16ff0 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 thorizer()] inte
17000 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 rface..**.** {F1
17010 32 35 31 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 2511} The second
17020 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
17030 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e e callback is an
17040 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 integer.**
17050 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 [SQLITE_COP
17060 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d Y | action code]
17070 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 that specifies
17080 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 the particular a
17090 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ction.**
170a0 20 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a to be authoriz
170b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 ed..**.** {F1251
170c0 32 7d 20 54 68 65 20 74 68 69 72 64 20 74 68 72 2} The third thr
170d0 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d ough sixth param
170e0 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c eters to the cal
170f0 6c 62 61 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20 lback are.**
17100 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 zero-termi
17110 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 nated strings th
17120 61 74 20 63 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20 at contain.**
17130 20 20 20 20 20 20 20 61 64 64 69 74 69 6f 6e 61 additiona
17140 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 l details about
17150 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 the action to be
17160 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a authorized..**.
17170 2a 2a 20 7b 46 31 32 35 32 30 7d 20 45 61 63 68 ** {F12520} Each
17180 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
17190 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
171a0 28 29 5d 20 6f 76 65 72 72 69 64 65 73 0a 2a 2a ()] overrides.**
171b0 20 20 20 20 20 20 20 20 20 20 61 6e 79 20 70 72 any pr
171c0 65 76 69 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c eviously install
171d0 65 64 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a ed authorizer..*
171e0 2a 0a 2a 2a 20 7b 46 31 32 35 32 31 7d 20 41 20 *.** {F12521} A
171f0 4e 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 NULL authorizer
17200 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 means that no au
17210 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 thorization.**
17220 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b callback
17230 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a is invoked..**.
17240 2a 2a 20 7b 46 31 32 35 32 32 7d 20 54 68 65 20 ** {F12522} The
17250 64 65 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a default authoriz
17260 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 er is NULL..*/.i
17270 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 nt sqlite3_set_a
17280 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c uthorizer(. sql
17290 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 ite3*,. int (*x
172a0 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c Auth)(void*,int,
172b0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 const char*,cons
172c0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
172d0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 ar*,const char*)
172e0 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 ,. void *pUserD
172f0 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ata.);../*.** CA
17300 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a PI3REF: Authoriz
17310 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 er Return Codes
17320 7b 46 31 32 35 39 30 7d 0a 2a 2a 0a 2a 2a 20 54 {F12590}.**.** T
17330 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f he [sqlite3_set_
17340 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 authorizer | aut
17350 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
17360 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a function] must.
17370 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 ** return either
17380 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 [SQLITE_OK] or
17390 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f one of these two
173a0 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 constants in or
173b0 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c der.** to signal
173c0 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 SQLite whether
173d0 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f or not the actio
173e0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 n is permitted.
173f0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c See the.** [sql
17400 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
17410 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 zer | authorizer
17420 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 documentation]
17430 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a for additional.*
17440 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a * information..*
17450 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
17460 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 _DENY 1 /* A
17470 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 bort the SQL sta
17480 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 tement with an e
17490 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rror */.#define
174a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 SQLITE_IGNORE 2
174b0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 /* Don't allow
174c0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e access, but don
174d0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 't generate an e
174e0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 rror */../*.** C
174f0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 API3REF: Authori
17500 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 zer Action Codes
17510 20 7b 46 31 32 35 35 30 7d 0a 2a 2a 0a 2a 2a 20 {F12550}.**.**
17520 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 The [sqlite3_set
17530 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 _authorizer()] i
17540 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
17550 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 rs a callback fu
17560 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 nction.** that i
17570 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 s invoked to aut
17580 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 horize certain S
17590 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 QL statement act
175a0 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 ions. The.** se
175b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
175c0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 o the callback i
175d0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 s an integer cod
175e0 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 e that specifies
175f0 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 .** what action
17600 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 is being authori
17610 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 zed. These are
17620 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 the integer acti
17630 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a on codes that.**
17640 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
17650 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 callback may be
17660 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 passed..**.** Th
17670 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 ese action code
17680 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 values signify w
17690 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 hat kind of oper
176a0 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a ation is to be.*
176b0 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 * authorized. T
176c0 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 he 3rd and 4th p
176d0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 arameters to the
176e0 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a authorization.*
176f0 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 * callback funct
17700 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 ion will be para
17710 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 meters or NULL d
17720 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 epending on whic
17730 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f h of these.** co
17740 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 des is used as t
17750 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
17760 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 61 ter. The 5th pa
17770 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a rameter to the.*
17780 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c * authorizer cal
17790 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d lback is the nam
177a0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
177b0 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 e ("main", "temp
177c0 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 ",.** etc.) if a
177d0 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 20 pplicable. The
177e0 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 6th parameter to
177f0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
17800 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 callback.** is t
17810 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 he name of the i
17820 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 nner-most trigge
17830 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 r or view that i
17840 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
17850 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 r.** the access
17860 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 attempt or NULL
17870 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 if this access a
17880 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 ttempt is direct
17890 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c ly from.** top-l
178a0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a evel SQL code..*
178b0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
178c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 31 7d 20 .**.** {F12551}
178d0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
178e0 65 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 20 20 eter to an.**
178f0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
17900 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
17910 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
17920 62 61 63 6b 5d 20 69 73 20 61 6c 77 61 79 73 20 back] is always
17930 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 an integer.**
17940 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 [SQLITE_C
17950 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 OPY | authorizer
17960 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 code] that spec
17970 69 66 69 65 73 20 77 68 61 74 20 61 63 74 69 6f ifies what actio
17980 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 n.** is
17990 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 being authorize
179a0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 32 d..**.** {F12552
179b0 7d 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 } The 3rd and 4t
179c0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 h parameters to
179d0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
179e0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
179f0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 horizer | author
17a00 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b ization callback
17a10 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 ].** wi
17a20 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 ll be parameters
17a30 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 or NULL dependi
17a40 6e 67 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 20 ng on which.**
17a50 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
17a60 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 COPY | authorize
17a70 72 20 63 6f 64 65 5d 20 69 73 20 75 73 65 64 20 r code] is used
17a80 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
17a90 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b rameter..**.** {
17aa0 46 31 32 35 35 33 7d 20 54 68 65 20 35 74 68 20 F12553} The 5th
17ab0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
17ac0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
17ad0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
17ae0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 izer | authorize
17af0 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 r callback] is t
17b00 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 he name.**
17b10 20 20 20 20 6f 66 20 74 68 65 20 64 61 74 61 62 of the datab
17b20 61 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d ase (example: "m
17b30 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 74 ain", "temp", et
17b40 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c c.) if applicabl
17b50 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 34 e..**.** {F12554
17b60 7d 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 } The 6th parame
17b70 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 ter to the.**
17b80 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
17b90 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
17ba0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
17bb0 62 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d back] is the nam
17bc0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 e.** of
17bd0 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 the inner-most
17be0 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 trigger or view
17bf0 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 that is responsi
17c00 62 6c 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 ble for.**
17c10 20 20 20 20 74 68 65 20 61 63 63 65 73 73 20 61 the access a
17c20 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 ttempt or NULL i
17c30 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 f this access at
17c40 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c tempt is directl
17c50 79 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 y from.**
17c60 20 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c top-level SQL
17c70 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a code..*/./*****
17c80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
17c90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
17ca0 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a ****** 3rd *****
17cb0 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a ******* 4th ****
17cc0 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 *******/.#define
17cd0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 SQLITE_CREATE_I
17ce0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 NDEX 1
17cf0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
17d00 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
17d10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
17d20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 SQLITE_CREATE_TA
17d30 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 BLE 2
17d40 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
17d50 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
17d60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
17d70 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
17d80 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 P_INDEX 3
17d90 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
17da0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
17db0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
17dc0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
17dd0 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f _TABLE 4 /
17de0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
17df0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
17e00 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
17e10 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
17e20 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a TRIGGER 5 /*
17e30 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
17e40 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
17e50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
17e60 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 TE_CREATE_TEMP_V
17e70 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 IEW 6 /*
17e80 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
17e90 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
17ea0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
17eb0 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 E_CREATE_TRIGGER
17ec0 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 7 /* T
17ed0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
17ee0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
17ef0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
17f00 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 _CREATE_VIEW
17f10 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 8 /* Vi
17f20 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
17f30 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
17f40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
17f50 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 DELETE
17f60 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 9 /* Tab
17f70 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
17f80 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
17f90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
17fa0 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 ROP_INDEX
17fb0 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 10 /* Inde
17fc0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
17fd0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
17fe0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
17ff0 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 OP_TABLE
18000 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 11 /* Table
18010 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
18020 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
18030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
18040 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 P_TEMP_INDEX
18050 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 12 /* Index
18060 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
18070 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
18080 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
18090 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 _TEMP_TABLE
180a0 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 13 /* Table N
180b0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
180c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
180d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
180e0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 TEMP_TRIGGER
180f0 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 14 /* Trigger
18100 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
18110 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
18120 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
18130 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 EMP_VIEW 1
18140 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 5 /* View Name
18150 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
18160 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
18170 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 e SQLITE_DROP_TR
18180 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 IGGER 16
18190 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
181a0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
181b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
181c0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 SQLITE_DROP_VIE
181d0 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 W 17
181e0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
181f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
18200 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
18210 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 SQLITE_INSERT
18220 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 18
18230 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
18240 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
18250 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
18260 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 QLITE_PRAGMA
18270 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 19
18280 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 /* Pragma Name
18290 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 1st arg or NU
182a0 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 LL */.#define SQ
182b0 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 LITE_READ
182c0 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 20 /
182d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
182e0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 Column Name
182f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
18300 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 ITE_SELECT
18310 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 21 /*
18320 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
18330 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
18340 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18350 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 TE_TRANSACTION
18360 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 22 /*
18370 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
18380 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
18390 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
183a0 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 E_UPDATE
183b0 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 23 /* T
183c0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 able Name C
183d0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a olumn Name *
183e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
183f0 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 _ATTACH
18400 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 24 /* Fi
18410 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 lename NU
18420 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
18430 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18440 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 DETACH
18450 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 25 /* Dat
18460 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c abase Name NUL
18470 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
18480 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
18490 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 LTER_TABLE
184a0 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 26 /* Data
184b0 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c base Name Tabl
184c0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
184d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
184e0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 INDEX
184f0 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 27 /* Index
18500 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
18510 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
18520 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 efine SQLITE_ANA
18530 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 LYZE
18540 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 28 /* Table
18550 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
18560 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
18570 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
18580 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 TE_VTABLE
18590 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 29 /* Table N
185a0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 ame Module
185b0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
185c0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
185d0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 VTABLE
185e0 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 30 /* Table Na
185f0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e me Module N
18600 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
18610 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 ne SQLITE_FUNCTI
18620 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 ON 3
18630 31 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 1 /* Function
18640 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 Name NULL
18650 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
18660 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 e SQLITE_COPY
18670 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
18680 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 /* No longer
18690 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 used */../*.** C
186a0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 API3REF: Tracing
186b0 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 And Profiling F
186c0 75 6e 63 74 69 6f 6e 73 20 7b 46 31 32 32 38 30 unctions {F12280
186d0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f }.**.** These ro
186e0 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 utines register
186f0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
18700 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 ns that can be u
18710 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 sed for.** traci
18720 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 ng and profiling
18730 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f the execution o
18740 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 f SQL statements
18750 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c ..**.** The call
18760 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 back function re
18770 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 gistered by sqli
18780 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 te3_trace() is i
18790 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 nvoked at.** var
187a0 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 ious times when
187b0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
187c0 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 is being run by
187d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
187e0 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 ]..** The callba
187f0 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54 46 ck returns a UTF
18800 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 -8 rendering of
18810 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
18820 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 t text.** as the
18830 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 statement first
18840 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e begins executin
18850 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 g. Additional c
18860 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a allbacks occur.*
18870 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 * as each trigge
18880 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 red subprogram i
18890 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 s entered. The
188a0 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 callbacks for tr
188b0 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 iggers.** contai
188c0 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f n a UTF-8 SQL co
188d0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 mment that ident
188e0 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 ifies the trigge
188f0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c r..**.** The cal
18900 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 lback function r
18910 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c egistered by sql
18920 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 ite3_profile() i
18930 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 s invoked.** as
18940 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 each SQL stateme
18950 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68 nt finishes. Th
18960 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 e profile callba
18970 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 ck contains.** t
18980 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 he original stat
18990 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 ement text and a
189a0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 n estimate of wa
189b0 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a ll-clock time.**
189c0 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 of how long tha
189d0 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b t statement took
189e0 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 to run..**.** T
189f0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 he sqlite3_profi
18a00 6c 65 28 29 20 41 50 49 20 69 73 20 63 75 72 72 le() API is curr
18a10 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 ently considered
18a20 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e experimental an
18a30 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63 74 20 d.** is subject
18a40 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d to change or rem
18a50 6f 76 61 6c 20 69 6e 20 61 20 66 75 74 75 72 65 oval in a future
18a60 20 72 65 6c 65 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 release..**.**
18a70 54 68 65 20 74 72 69 67 67 65 72 20 72 65 70 6f The trigger repo
18a80 72 74 69 6e 67 20 66 65 61 74 75 72 65 20 6f 66 rting feature of
18a90 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 the trace callb
18aa0 61 63 6b 20 69 73 20 63 6f 6e 73 69 64 65 72 65 ack is considere
18ab0 64 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 d.** experimenta
18ac0 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 l and is subject
18ad0 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65 to change or re
18ae0 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 moval in future
18af0 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 20 46 75 74 releases..** Fut
18b00 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
18b10 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 SQLite might als
18b20 6f 20 61 64 64 20 6e 65 77 20 74 72 61 63 65 20 o add new trace
18b30 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6e 76 6f callback.** invo
18b40 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 cations..**.** I
18b50 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
18b60 20 7b 46 31 32 32 38 31 7d 20 54 68 65 20 63 61 {F12281} The ca
18b70 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
18b80 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 registered by [s
18b90 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 qlite3_trace()]
18ba0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 is.** w
18bb0 68 65 6e 65 76 65 72 20 61 6e 20 53 51 4c 20 73 henever an SQL s
18bc0 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 tatement first b
18bd0 65 67 69 6e 73 20 74 6f 20 65 78 65 63 75 74 65 egins to execute
18be0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
18bf0 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 69 67 whenever a trig
18c00 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 20 66 ger subprogram f
18c10 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 72 irst begins to r
18c20 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 un..**.** {F1228
18c30 32 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 2} Each call to
18c40 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 [sqlite3_trace()
18c50 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 20 ] overrides the
18c60 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 previously.**
18c70 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 registere
18c80 64 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b d trace callback
18c90 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 33 7d ..**.** {F12283}
18ca0 20 41 20 4e 55 4c 4c 20 74 72 61 63 65 20 63 61 A NULL trace ca
18cb0 6c 6c 62 61 63 6b 20 64 69 73 61 62 6c 65 73 20 llback disables
18cc0 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b tracing..**.** {
18cd0 46 31 32 32 38 34 7d 20 54 68 65 20 66 69 72 73 F12284} The firs
18ce0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
18cf0 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b e trace callback
18d00 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a is a copy of.**
18d10 20 20 20 20 20 20 20 20 20 20 74 68 65 20 70 6f the po
18d20 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 inter which was
18d30 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 the 3rd argument
18d40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 to [sqlite3_tra
18d50 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 ce()]..**.** {F1
18d60 32 32 38 35 7d 20 54 68 65 20 73 65 63 6f 6e 64 2285} The second
18d70 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
18d80 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 trace callback
18d90 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 is a.**
18da0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
18db0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63 6f UTF-8 string co
18dc0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6f 72 69 ntaining the ori
18dd0 67 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20 20 20 ginal text.**
18de0 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 53 51 of the SQ
18df0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69 L statement as i
18e00 74 20 77 61 73 20 70 61 73 73 65 64 20 69 6e 74 t was passed int
18e10 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 o [sqlite3_prepa
18e20 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 re_v2()].**
18e30 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69 or the equi
18e40 76 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20 53 51 valent, or an SQ
18e50 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 61 L comment indica
18e60 74 69 6e 67 20 74 68 65 20 62 65 67 69 6e 6e 69 ting the beginni
18e70 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f ng.** o
18e80 66 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70 f a trigger subp
18e90 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 rogram..**.** {F
18ea0 31 32 32 38 37 7d 20 54 68 65 20 63 61 6c 6c 62 12287} The callb
18eb0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 ack function reg
18ec0 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69 istered by [sqli
18ed0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 69 te3_profile()] i
18ee0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 s invoked.**
18ef0 20 20 20 20 20 20 61 73 20 65 61 63 68 20 53 51 as each SQ
18f00 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 L statement fini
18f10 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 shes..**.** {F12
18f20 32 38 38 7d 20 54 68 65 20 66 69 72 73 74 20 70 288} The first p
18f30 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
18f40 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b profile callback
18f50 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a is a copy of.**
18f60 20 20 20 20 20 20 20 20 20 20 74 68 65 20 33 72 the 3r
18f70 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b d parameter to [
18f80 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 sqlite3_profile(
18f90 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 )]..**.** {F1228
18fa0 39 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 9} The second pa
18fb0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 rameter to the p
18fc0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 rofile callback
18fd0 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 is a.**
18fe0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
18ff0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 UTF-8 string th
19000 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 at contains the
19010 63 6f 6d 70 6c 65 74 65 20 74 65 78 74 20 6f 66 complete text of
19020 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
19030 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 SQL statement a
19040 73 20 69 74 20 77 61 73 20 70 72 6f 63 65 73 73 s it was process
19050 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 ed by [sqlite3_p
19060 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 repare_v2()].**
19070 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 or the
19080 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a equivalent..**.*
19090 2a 20 7b 46 31 32 32 39 30 7d 20 54 68 65 20 74 * {F12290} The t
190a0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
190b0 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 o the profile ca
190c0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 65 73 74 llback is an est
190d0 69 6d 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 imate.**
190e0 20 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 of the number
190f0 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f of nanoseconds o
19100 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d f wall-clock tim
19110 65 20 72 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a e required to.**
19120 20 20 20 20 20 20 20 20 20 20 72 75 6e 20 74 68 run th
19130 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
19140 66 72 6f 6d 20 73 74 61 72 74 20 74 6f 20 66 69 from start to fi
19150 6e 69 73 68 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 nish..*/.void *s
19160 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c qlite3_trace(sql
19170 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 ite3*, void(*xTr
19180 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 ace)(void*,const
19190 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b char*), void*);
191a0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 .void *sqlite3_p
191b0 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c rofile(sqlite3*,
191c0 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 . void(*xProfi
191d0 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 le)(void*,const
191e0 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 char*,sqlite3_ui
191f0 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a nt64), void*);..
19200 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
19210 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 Query Progress C
19220 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39 31 30 allbacks {F12910
19230 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 }.**.** This rou
19240 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 tine configures
19250 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
19260 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f ion - the.** pro
19270 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d gress callback -
19280 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 that is invoked
19290 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 periodically du
192a0 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e ring long.** run
192b0 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 ning calls to [s
192c0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 qlite3_exec()],
192d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
192e0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
192f0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 _get_table()].
19300 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 An example use f
19310 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 or this.** inter
19320 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 face is to keep
19330 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 a GUI updated du
19340 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 ring a large que
19350 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ry..**.** If the
19360 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 progress callba
19370 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ck returns non-z
19380 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 ero, the operati
19390 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 on is.** interru
193a0 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 pted. This feat
193b0 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ure can be used
193c0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a to implement a.*
193d0 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f * "Cancel" butto
193e0 6e 20 6f 6e 20 61 20 47 55 49 20 64 69 61 6c 6f n on a GUI dialo
193f0 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 g box..**.** INV
19400 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
19410 46 31 32 39 31 31 7d 20 54 68 65 20 63 61 6c 6c F12911} The call
19420 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 back function re
19430 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 gistered by sqli
19440 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e te3_progress_han
19450 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 dler().**
19460 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 is invoked pe
19470 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e riodically durin
19480 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 g long running c
19490 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 alls to.**
194a0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 [sqlite3_ste
194b0 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 p()]..**.** {F12
194c0 39 31 32 7d 20 54 68 65 20 70 72 6f 67 72 65 73 912} The progres
194d0 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e s callback is in
194e0 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 voked once for e
194f0 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c 0a 2a very N virtual.*
19500 2a 20 20 20 20 20 20 20 20 20 20 6d 61 63 68 69 * machi
19510 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 68 65 72 ne opcodes, wher
19520 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e e N is the secon
19530 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a d argument to.**
19540 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 the [s
19550 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f qlite3_progress_
19560 68 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c 6c 20 handler()] call
19570 74 68 61 74 20 72 65 67 69 73 74 65 72 65 64 0a that registered.
19580 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
19590 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 4e 20 callback. If N
195a0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 2c 20 is less than 1,
195b0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 sqlite3_progress
195c0 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 _handler().**
195d0 20 20 20 20 20 20 20 61 63 74 73 20 61 73 20 69 acts as i
195e0 66 20 61 20 4e 55 4c 4c 20 70 72 6f 67 72 65 73 f a NULL progres
195f0 73 20 68 61 6e 64 6c 65 72 20 68 61 64 20 62 65 s handler had be
19600 65 6e 20 73 70 65 63 69 66 69 65 64 2e 0a 2a 2a en specified..**
19610 0a 2a 2a 20 7b 46 31 32 39 31 33 7d 20 54 68 65 .** {F12913} The
19620 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 progress callba
19630 63 6b 20 69 74 73 65 6c 66 20 69 73 20 69 64 65 ck itself is ide
19640 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 74 ntified by the t
19650 68 69 72 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 hird.**
19660 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
19670 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 ite3_progress_ha
19680 6e 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b ndler()..**.** {
19690 46 31 32 39 31 34 7d 20 54 68 65 20 66 6f 75 72 F12914} The four
196a0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 th argument to s
196b0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f qlite3_progress_
196c0 68 61 6e 64 6c 65 72 28 29 20 69 73 20 61 0a 2a handler() is a.*
196d0 2a 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 * void
196e0 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 74 pointer passed t
196f0 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 o the progress c
19700 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 allback.**
19710 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 function eac
19720 68 20 74 69 6d 65 20 69 74 20 69 73 20 69 6e 76 h time it is inv
19730 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 oked..**.** {F12
19740 39 31 35 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 915} If a call t
19750 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
19760 29 5d 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65 )] results in fe
19770 77 65 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f 64 wer than N opcod
19780 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 es.** b
19790 65 69 6e 67 20 65 78 65 63 75 74 65 64 2c 20 74 eing executed, t
197a0 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 hen the progress
197b0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 callback is nev
197c0 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a er invoked..**.*
197d0 2a 20 7b 46 31 32 39 31 36 7d 20 45 76 65 72 79 * {F12916} Every
197e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
197f0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 3_progress_handl
19800 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 er()].**
19810 20 20 6f 76 65 72 77 72 69 74 65 73 20 61 6e 79 overwrites any
19820 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 previously regi
19830 73 74 65 72 65 64 20 70 72 6f 67 72 65 73 73 20 stered progress
19840 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b handler..**.** {
19850 46 31 32 39 31 37 7d 20 49 66 20 74 68 65 20 70 F12917} If the p
19860 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 rogress handler
19870 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c callback is NULL
19880 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65 73 then no progres
19890 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 s.** ha
198a0 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 ndler is invoked
198b0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 38 7d ..**.** {F12918}
198c0 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 If the progress
198d0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
198e0 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65 72 s a result other
198f0 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a than 0, then.**
19900 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62 65 the be
19910 68 61 76 69 6f 72 20 69 73 20 61 20 69 66 20 5b havior is a if [
19920 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
19930 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20 63 61 t()] had been ca
19940 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 lled..*/.void sq
19950 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 lite3_progress_h
19960 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c andler(sqlite3*,
19970 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 int, int(*)(voi
19980 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a d*), void*);../*
19990 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 .** CAPI3REF: Op
199a0 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 ening A New Data
199b0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 base Connection
199c0 7b 46 31 32 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 {F12700}.**.** T
199d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 hese routines op
199e0 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 en an SQLite dat
199f0 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 abase file whose
19a00 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62 name is given b
19a10 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d y the.** filenam
19a20 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 e argument. The
19a30 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
19a40 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 t is interpreted
19a50 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a as UTF-8 for.**
19a60 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
19a70 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e and sqlite3_open
19a80 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 _v2() and as UTF
19a90 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 -16 in the nativ
19aa0 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 e byte.** order
19ab0 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e for sqlite3_open
19ac0 31 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61 73 16(). A [databas
19ad0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 e connection] ha
19ae0 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a ndle is usually.
19af0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a ** returned in *
19b00 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e ppDb, even if an
19b10 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 error occurs.
19b20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 The only excepti
19b30 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 on is that.** if
19b40 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c SQLite is unabl
19b50 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 e to allocate me
19b60 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
19b70 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
19b80 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c t,.** a NULL wil
19b90 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 l be written int
19ba0 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 o *ppDb instead
19bb0 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 of a pointer to
19bc0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a the [sqlite3].**
19bd0 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65 20 object. If the
19be0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
19bf0 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 ed (and/or creat
19c00 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 ed) successfully
19c10 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 , then.** [SQLIT
19c20 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 E_OK] is returne
19c30 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e d. Otherwise an
19c40 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 [error code] is
19c50 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 0a returned. The.
19c60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d ** [sqlite3_errm
19c70 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 sg()] or [sqlite
19c80 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 3_errmsg16()] ro
19c90 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 utines can be us
19ca0 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 ed to obtain.**
19cb0 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 an English langu
19cc0 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 age description
19cd0 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a of the error..**
19ce0 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 .** The default
19cf0 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 encoding for the
19d00 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 database will b
19d10 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 e UTF-8 if.** sq
19d20 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 lite3_open() or
19d30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
19d40 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a ) is called and.
19d50 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 ** UTF-16 in the
19d60 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
19d70 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 er if sqlite3_op
19d80 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a en16() is used..
19d90 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 **.** Whether or
19da0 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 not an error oc
19db0 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 curs when it is
19dc0 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 opened, resource
19dd0 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 s.** associated
19de0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 with the [databa
19df0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 se connection] h
19e00 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 andle should be
19e10 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 released by.** p
19e20 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 assing it to [sq
19e30 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 lite3_close()] w
19e40 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e hen it is no lon
19e50 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a ger required..**
19e60 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
19e70 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 open_v2() interf
19e80 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 ace works like s
19e90 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a qlite3_open().**
19ea0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 except that it
19eb0 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 accepts two addi
19ec0 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 tional parameter
19ed0 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c s for additional
19ee0 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 control.** over
19ef0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 the new databas
19f00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 e connection. T
19f10 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 he flags paramet
19f20 65 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 er can take one
19f30 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 of.** the follow
19f40 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 ing three values
19f50 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d , optionally com
19f60 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a bined with the .
19f70 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
19f80 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 3a 0a 2a NOMUTEX] flag:.*
19f90 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 *.** <dl>.** <dt
19fa0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 >[SQLITE_OPEN_RE
19fb0 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 ADONLY]</dt>.**
19fc0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 <dd>The database
19fd0 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 is opened in re
19fe0 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 ad-only mode. I
19ff0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 f the database d
1a000 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 oes not.** alrea
1a010 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 dy exist, an err
1a020 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c or is returned.<
1a030 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b /dd>.**.** <dt>[
1a040 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
1a050 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c WRITE]</dt>.** <
1a060 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 dd>The database
1a070 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
1a080 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e ading and writin
1a090 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f g if possible, o
1a0a0 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c r reading.** onl
1a0b0 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 y if the file is
1a0c0 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 write protected
1a0d0 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e by the operatin
1a0e0 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 g system. In ei
1a0f0 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 ther.** case the
1a100 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 database must a
1a110 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 lready exist, ot
1a120 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 herwise an error
1a130 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 is returned.</d
1a140 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 d>.**.** <dt>[SQ
1a150 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
1a160 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f ITE] | [SQLITE_O
1a170 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e PEN_CREATE]</dt>
1a180 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 .** <dd>The data
1a190 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 base is opened f
1a1a0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 or reading and w
1a1b0 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 riting, and is c
1a1c0 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 reates it if.**
1a1d0 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 it does not alre
1a1e0 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 ady exist. This
1a1f0 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 is the behavior
1a200 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 that is always u
1a210 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 sed for.** sqlit
1a220 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
1a230 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c lite3_open16().<
1a240 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a /dd>.** </dl>.**
1a250 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 .** If the 3rd p
1a260 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
1a270 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
1a280 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a not one of the.
1a290 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 ** combinations
1a2a0 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f shown above or o
1a2b0 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e ne of the combin
1a2c0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f ations shown abo
1a2d0 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 ve combined.** w
1a2e0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
1a2f0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c OPEN_NOMUTEX] fl
1a300 61 67 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 ag, then the beh
1a310 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
1a320 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ed..**.** If the
1a330 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f [SQLITE_OPEN_NO
1a340 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 MUTEX] flag is s
1a350 65 74 2c 20 74 68 65 6e 20 6d 75 74 65 78 65 73 et, then mutexes
1a360 20 6f 6e 20 74 68 65 0a 2a 2a 20 6f 70 65 6e 65 on the.** opene
1a370 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e d [database conn
1a380 65 63 74 69 6f 6e 5d 20 61 72 65 20 64 69 73 61 ection] are disa
1a390 62 6c 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 bled and the app
1a3a0 6c 69 61 74 69 6f 6e 20 6d 75 73 74 0a 2a 2a 20 liation must.**
1a3b0 69 6e 73 75 72 65 20 74 68 61 74 20 61 63 63 65 insure that acce
1a3c0 73 73 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 ss to the [datab
1a3d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
1a3e0 61 6e 64 20 69 74 73 20 61 73 73 6f 63 69 61 74 and its associat
1a3f0 65 64 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 ed.** [prepared
1a400 73 74 61 74 65 6d 65 6e 74 73 5d 20 69 73 20 73 statements] is s
1a410 65 72 69 61 6c 69 7a 65 64 2e 20 20 54 68 65 20 erialized. The
1a420 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d [SQLITE_OPEN_NOM
1a430 55 54 45 58 5d 20 66 6c 61 67 0a 2a 2a 20 69 73 UTEX] flag.** is
1a440 20 74 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 the default beh
1a450 61 76 69 6f 72 20 69 73 20 53 51 4c 69 74 65 20 avior is SQLite
1a460 69 73 20 63 6f 6e 66 69 67 75 72 65 64 20 75 73 is configured us
1a470 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ing the.** [SQLI
1a480 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
1a490 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 HREAD] or [SQLIT
1a4a0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
1a4b0 48 52 45 41 44 5d 20 6f 70 74 69 6f 6e 73 0a 2a HREAD] options.*
1a4c0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f * to [sqlite3_co
1a4d0 6e 66 69 67 28 29 5d 2e 20 20 54 68 65 20 5b 53 nfig()]. The [S
1a4e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
1a4f0 45 58 5d 20 66 6c 61 67 20 6f 6e 6c 79 20 6d 61 EX] flag only ma
1a500 6b 65 73 20 61 0a 2a 2a 20 64 69 66 66 65 72 65 kes a.** differe
1a510 6e 63 65 20 77 68 65 6e 20 53 51 4c 69 74 65 20 nce when SQLite
1a520 69 73 20 69 6e 20 69 74 73 20 64 65 66 61 75 6c is in its defaul
1a530 74 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 t [SQLITE_CONFIG
1a540 5f 53 45 52 49 41 4c 49 5a 45 44 5d 20 6d 6f 64 _SERIALIZED] mod
1a550 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 e..**.** If the
1a560 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 filename is ":me
1a570 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 mory:", then a p
1a580 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 rivate, temporar
1a590 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 y in-memory data
1a5a0 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 base.** is creat
1a5b0 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 ed for the conne
1a5c0 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d ction. This in-
1a5d0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 memory database
1a5e0 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e will vanish when
1a5f0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
1a600 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 connection is c
1a610 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 losed. Future v
1a620 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
1a630 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 e might.** make
1a640 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 use of additiona
1a650 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 l special filena
1a660 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 mes that begin w
1a670 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 ith the ":" char
1a680 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 acter..** It is
1a690 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 recommended that
1a6a0 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 when a database
1a6b0 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c filename actual
1a6c0 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 ly does begin wi
1a6d0 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 th.** a ":" char
1a6e0 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 acter you should
1a6f0 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 prefix the file
1a700 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 name with a path
1a710 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 name such as.**
1a720 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d "./" to avoid am
1a730 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 biguity..**.** I
1a740 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 f the filename i
1a750 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e s an empty strin
1a760 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 g, then a privat
1a770 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 e, temporary.**
1a780 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 on-disk database
1a790 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 will be created
1a7a0 2e 20 20 54 68 69 73 20 70 72 69 76 61 74 65 20 . This private
1a7b0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
1a7c0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c .** automaticall
1a7d0 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f y deleted as soo
1a7e0 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 n as the databas
1a7f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
1a800 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 closed..**.** Th
1a810 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
1a820 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 er to sqlite3_op
1a830 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e en_v2() is the n
1a840 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 ame of the.** [s
1a850 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
1a860 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 ct that defines
1a870 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
1a880 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 stem interface t
1a890 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 hat.** the new d
1a8a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1a8b0 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 on should use.
1a8c0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
1a8d0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 rameter is.** a
1a8e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
1a8f0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 n the default [s
1a900 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
1a910 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a ct is used..**.*
1a920 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e * <b>Note to Win
1a930 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 dows users:</b>
1a940 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 The encoding us
1a950 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e ed for the filen
1a960 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 ame argument.**
1a970 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 of sqlite3_open(
1a980 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 ) and sqlite3_op
1a990 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 en_v2() must be
1a9a0 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 UTF-8, not whate
1a9b0 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 ver.** codepage
1a9c0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 is currently def
1a9d0 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 ined. Filenames
1a9e0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 containing inte
1a9f0 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 rnational.** cha
1aa00 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 racters must be
1aa10 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 converted to UTF
1aa20 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 -8 prior to pass
1aa30 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a ing them into.**
1aa40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
1aa50 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
1aa60 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 v2()..**.** INVA
1aa70 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 RIANTS:.**.** {F
1aa80 31 32 37 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 12701} The [sqli
1aa90 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
1aaa0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c lite3_open16()],
1aab0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
1aac0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
1aad0 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 2()] interfaces
1aae0 63 72 65 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 create a new.**
1aaf0 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 [databa
1ab00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
1ab10 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a ssociated with.*
1ab20 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 64 * the d
1ab30 61 74 61 62 61 73 65 20 66 69 6c 65 20 67 69 76 atabase file giv
1ab40 65 6e 20 69 6e 20 74 68 65 69 72 20 66 69 72 73 en in their firs
1ab50 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a t parameter..**.
1ab60 2a 2a 20 7b 46 31 32 37 30 32 7d 20 54 68 65 20 ** {F12702} The
1ab70 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
1ab80 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 t is interpreted
1ab90 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 as UTF-8.**
1aba0 20 20 20 20 20 20 66 6f 72 20 5b 73 71 6c 69 74 for [sqlit
1abb0 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b e3_open()] and [
1abc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1abd0 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 )] and as UTF-16
1abe0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 .** in
1abf0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 the native byte
1ac00 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 order for [sqlit
1ac10 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a e3_open16()]..**
1ac20 0a 2a 2a 20 7b 46 31 32 37 30 33 7d 20 41 20 73 .** {F12703} A s
1ac30 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 uccessful invoca
1ac40 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
1ac50 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
1ac60 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a e3_open16()],.**
1ac70 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 or [sq
1ac80 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
1ac90 20 77 72 69 74 65 73 20 61 20 70 6f 69 6e 74 65 writes a pointe
1aca0 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 r to a new.**
1acb0 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 [database
1acc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 connection] int
1acd0 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b o *ppDb..**.** {
1ace0 46 31 32 37 30 34 7d 20 54 68 65 20 5b 73 71 6c F12704} The [sql
1acf0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
1ad00 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
1ad10 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 , and.**
1ad20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f [sqlite3_open_
1ad30 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 v2()] interfaces
1ad40 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
1ad50 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65 73 73 OK] upon success
1ad60 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 ,.** or
1ad70 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 an appropriate
1ad80 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 [error code] on
1ad90 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b failure..**.** {
1ada0 46 31 32 37 30 36 7d 20 54 68 65 20 64 65 66 61 F12706} The defa
1adb0 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e ult text encodin
1adc0 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 g for a new data
1add0 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69 base created usi
1ade0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ng.** [
1adf0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 sqlite3_open()]
1ae00 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e or [sqlite3_open
1ae10 5f 76 32 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 _v2()] will be U
1ae20 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 TF-8..**.** {F12
1ae30 37 30 37 7d 20 54 68 65 20 64 65 66 61 75 6c 74 707} The default
1ae40 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 text encoding f
1ae50 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 or a new databas
1ae60 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a e created using.
1ae70 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
1ae80 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77 ite3_open16()] w
1ae90 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a ill be UTF-16..*
1aea0 2a 0a 2a 2a 20 7b 46 31 32 37 30 39 7d 20 54 68 *.** {F12709} Th
1aeb0 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 e [sqlite3_open(
1aec0 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 F,D)] interface
1aed0 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f is equivalent to
1aee0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
1aef0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c lite3_open_v2(F,
1af00 44 2c 47 2c 30 29 5d 20 77 68 65 72 65 20 74 68 D,G,0)] where th
1af10 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 69 73 e G parameter is
1af20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 .** [SQ
1af30 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
1af40 49 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 ITE]|[SQLITE_OPE
1af50 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a N_CREATE]..**.**
1af60 20 7b 46 31 32 37 31 31 7d 20 49 66 20 74 68 65 {F12711} If the
1af70 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 G parameter to
1af80 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
1af90 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 (F,D,G,V)] conta
1afa0 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ins the.**
1afb0 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 bit value [S
1afc0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
1afd0 4e 4c 59 5d 20 74 68 65 6e 20 74 68 65 20 64 61 NLY] then the da
1afe0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
1aff0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 .** for
1b000 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a reading only..*
1b010 2a 0a 2a 2a 20 7b 46 31 32 37 31 32 7d 20 49 66 *.** {F12712} If
1b020 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 the G parameter
1b030 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 to [sqlite3_ope
1b040 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 n_v2(F,D,G,V)] c
1b050 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 ontains the.**
1b060 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 bit valu
1b070 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 e [SQLITE_OPEN_R
1b080 45 41 44 57 52 49 54 45 5d 20 74 68 65 6e 20 74 EADWRITE] then t
1b090 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
1b0a0 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 pened.**
1b0b0 20 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 reading and wr
1b0c0 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c iting if possibl
1b0d0 65 2c 20 6f 72 20 66 6f 72 20 72 65 61 64 69 6e e, or for readin
1b0e0 67 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a g only if the.**
1b0f0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 20 69 file i
1b100 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 s write protecte
1b110 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 d by the operati
1b120 6e 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a ng system..**.**
1b130 20 7b 46 31 32 37 31 33 7d 20 49 66 20 74 68 65 {F12713} If the
1b140 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 G parameter to
1b150 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 [sqlite3_open(v2
1b160 28 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 (F,D,G,V)] omits
1b170 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
1b180 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 bit value [SQLI
1b190 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 TE_OPEN_CREATE]
1b1a0 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 and the database
1b1b0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 does not.**
1b1c0 20 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79 previously
1b1d0 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 exist, an error
1b1e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
1b1f0 0a 2a 2a 20 7b 46 31 32 37 31 34 7d 20 49 66 20 .** {F12714} If
1b200 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 the G parameter
1b210 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
1b220 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f (v2(F,D,G,V)] co
1b230 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 ntains the.**
1b240 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 bit value
1b250 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
1b260 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 EATE] and the da
1b270 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a tabase does not.
1b280 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65 76 ** prev
1b290 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 74 68 iously exist, th
1b2a0 65 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 en an attempt is
1b2b0 20 6d 61 64 65 20 74 6f 20 63 72 65 61 74 65 20 made to create
1b2c0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 and.**
1b2d0 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 64 initialize the d
1b2e0 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b atabase..**.** {
1b2f0 46 31 32 37 31 37 7d 20 49 66 20 74 68 65 20 66 F12717} If the f
1b300 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
1b310 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 to [sqlite3_ope
1b320 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f n()], [sqlite3_o
1b330 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 pen16()],.**
1b340 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 or [sqlite
1b350 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 3_open_v2()] is
1b360 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e ":memory:", then
1b370 20 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 an private,.**
1b380 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 72 ephemer
1b390 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 al, in-memory da
1b3a0 74 61 62 61 73 65 20 69 73 20 63 72 65 61 74 65 tabase is create
1b3b0 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 d for the connec
1b3c0 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20 tion..**
1b3d0 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 <todo>Is SQLIT
1b3e0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 E_OPEN_CREATE|SQ
1b3f0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
1b400 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 ITE required.**
1b410 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 in sqli
1b420 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f te3_open_v2()?</
1b430 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 todo>.**.** {F12
1b440 37 31 39 7d 20 49 66 20 74 68 65 20 66 69 6c 65 719} If the file
1b450 6e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20 name is NULL or
1b460 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c an empty string,
1b470 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c then a private,
1b480 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 68 .** eph
1b490 65 6d 65 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 emeral on-disk d
1b4a0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 atabase will be
1b4b0 63 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 created..**
1b4c0 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 <todo>Is SQ
1b4d0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
1b4e0 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 |SQLITE_OPEN_REA
1b4f0 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64 0a DWRITE required.
1b500 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 ** in s
1b510 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
1b520 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b ?</todo>.**.** {
1b530 46 31 32 37 32 31 7d 20 54 68 65 20 5b 64 61 74 F12721} The [dat
1b540 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1b550 5d 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 ] created by [sq
1b560 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c lite3_open_v2(F,
1b570 44 2c 47 2c 56 29 5d 0a 2a 2a 20 20 20 20 20 20 D,G,V)].**
1b580 20 20 20 20 77 69 6c 6c 20 75 73 65 20 74 68 65 will use the
1b590 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
1b5a0 62 6a 65 63 74 20 69 64 65 6e 74 69 66 69 65 64 bject identified
1b5b0 20 62 79 20 74 68 65 20 56 20 70 61 72 61 6d 65 by the V parame
1b5c0 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ter,.**
1b5d0 20 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 or the default
1b5e0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
1b5f0 6a 65 63 74 20 69 66 20 56 20 69 73 20 61 20 4e ject if V is a N
1b600 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
1b610 2a 2a 20 7b 46 31 32 37 32 33 7d 20 54 77 6f 20 ** {F12723} Two
1b620 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1b630 74 69 6f 6e 73 5d 20 77 69 6c 6c 20 73 68 61 72 tions] will shar
1b640 65 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 e a common cache
1b650 20 69 66 20 62 6f 74 68 20 77 65 72 65 0a 2a 2a if both were.**
1b660 20 20 20 20 20 20 20 20 20 20 6f 70 65 6e 65 64 opened
1b670 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 56 with the same V
1b680 46 53 20 77 68 69 6c 65 20 5b 73 68 61 72 65 64 FS while [shared
1b690 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 77 61 73 cache mode] was
1b6a0 20 65 6e 61 62 6c 65 64 20 61 6e 64 0a 2a 2a 20 enabled and.**
1b6b0 20 20 20 20 20 20 20 20 20 69 66 20 62 6f 74 68 if both
1b6c0 20 66 69 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61 filenames compa
1b6d0 72 65 20 65 71 75 61 6c 20 75 73 69 6e 67 20 6d re equal using m
1b6e0 65 6d 63 6d 70 28 29 20 61 66 74 65 72 20 68 61 emcmp() after ha
1b6f0 76 69 6e 67 20 62 65 65 6e 0a 2a 2a 20 20 20 20 ving been.**
1b700 20 20 20 20 20 20 70 72 6f 63 65 73 73 65 64 20 processed
1b710 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
1b720 76 66 73 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e vfs | xFullPathn
1b730 61 6d 65 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 ame] method of t
1b740 68 65 20 56 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73 he VFS..*/.int s
1b750 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 qlite3_open(. c
1b760 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e onst char *filen
1b770 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 ame, /* Databa
1b780 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 se filename (UTF
1b790 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 -8) */. sqlite3
1b7a0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 **ppDb
1b7b0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
1b7c0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a db handle */.);.
1b7d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e int sqlite3_open
1b7e0 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 16(. const void
1b7f0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a *filename, /*
1b800 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 Database filena
1b810 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 me (UTF-16) */.
1b820 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 sqlite3 **ppDb
1b830 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a /* OUT:
1b840 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c SQLite db handl
1b850 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 e */.);.int sqli
1b860 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 te3_open_v2(. c
1b870 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e onst char *filen
1b880 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 ame, /* Databa
1b890 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 se filename (UTF
1b8a0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 -8) */. sqlite3
1b8b0 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 **ppDb,
1b8c0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
1b8d0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 db handle */. i
1b8e0 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 nt flags,
1b8f0 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 /* Flags
1b900 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
1b910 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 *zVfs /*
1b920 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 Name of VFS modu
1b930 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a le to use */.);.
1b940 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1b950 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 Error Codes And
1b960 20 4d 65 73 73 61 67 65 73 20 7b 46 31 32 38 30 Messages {F1280
1b970 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0}.**.** The sql
1b980 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 ite3_errcode() i
1b990 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
1b9a0 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 the numeric [re
1b9b0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a sult code] or.**
1b9c0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
1b9d0 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 t code] for the
1b9e0 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c most recent fail
1b9f0 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 ed sqlite3_* API
1ba00 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 call.** associa
1ba10 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 ted with a [data
1ba20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1ba30 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 . If a prior API
1ba40 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 call failed.**
1ba50 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 but the most rec
1ba60 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 ent API call suc
1ba70 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 ceeded, the retu
1ba80 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a rn value from.**
1ba90 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 sqlite3_errcode
1baa0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e () is undefined.
1bab0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
1bac0 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 e3_errmsg() and
1bad0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
1bae0 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 () return Englis
1baf0 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 h-language.** te
1bb00 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 xt that describe
1bb10 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 s the error, as
1bb20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
1bb30 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 UTF-16 respectiv
1bb40 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 ely..** Memory t
1bb50 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 o hold the error
1bb60 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 message string
1bb70 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 is managed inter
1bb80 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 nally..** The ap
1bb90 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e plication does n
1bba0 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 ot need to worry
1bbb0 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 about freeing t
1bbc0 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f he result..** Ho
1bbd0 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 wever, the error
1bbe0 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 string might be
1bbf0 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 overwritten or
1bc00 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a deallocated by.*
1bc10 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c * subsequent cal
1bc20 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 ls to other SQLi
1bc30 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e te interface fun
1bc40 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 ctions..**.** If
1bc50 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 an interface fa
1bc60 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f ils with SQLITE_
1bc70 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 MISUSE, that mea
1bc80 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 ns the interface
1bc90 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 .** was invoked
1bca0 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 incorrectly by t
1bcb0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 he application.
1bcc0 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 In that case, t
1bcd0 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 he.** error code
1bce0 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 and message may
1bcf0 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 or may not be s
1bd00 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 et..**.** INVARI
1bd10 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 ANTS:.**.** {F12
1bd20 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 801} The [sqlite
1bd30 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e 3_errcode(D)] in
1bd40 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
1bd50 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 the numeric.**
1bd60 20 20 20 20 20 20 20 20 5b 72 65 73 75 6c 74 20 [result
1bd70 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 code] or [extend
1bd80 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 ed result code]
1bd90 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 for the most rec
1bda0 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 ently.**
1bdb0 20 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 failed interfa
1bdc0 63 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 ce call associat
1bdd0 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 ed with the [dat
1bde0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1bdf0 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 ] D..**.** {F128
1be00 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 03} The [sqlite3
1be10 5f 65 72 72 6d 73 67 28 44 29 5d 20 61 6e 64 20 _errmsg(D)] and
1be20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 [sqlite3_errmsg1
1be30 36 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 6(D)].**
1be40 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 interfaces ret
1be50 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 urn English-lang
1be60 75 61 67 65 20 74 65 78 74 20 74 68 61 74 20 64 uage text that d
1be70 65 73 63 72 69 62 65 73 0a 2a 2a 20 20 20 20 20 escribes.**
1be80 20 20 20 20 20 74 68 65 20 65 72 72 6f 72 20 69 the error i
1be90 6e 20 74 68 65 20 6d 6f 73 74 6c 79 20 72 65 63 n the mostly rec
1bea0 65 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e 74 ently failed int
1beb0 65 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20 erface call,.**
1bec0 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 65 64 encoded
1bed0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 as either UTF-8
1bee0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 or UTF-16 respe
1bef0 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b ctively..**.** {
1bf00 46 31 32 38 30 37 7d 20 54 68 65 20 73 74 72 69 F12807} The stri
1bf10 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ngs returned by
1bf20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
1bf30 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
1bf40 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 errmsg16()].**
1bf50 20 20 20 20 20 20 20 20 61 72 65 20 76 61 6c 69 are vali
1bf60 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 d until the next
1bf70 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
1bf80 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 e call..**.** {F
1bf90 31 32 38 30 38 7d 20 43 61 6c 6c 73 20 74 6f 20 12808} Calls to
1bfa0 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74 68 61 API routines tha
1bfb0 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e 20 t do not return
1bfc0 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a an error code.**
1bfd0 20 20 20 20 20 20 20 20 20 20 28 65 78 61 6d 70 (examp
1bfe0 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 le: [sqlite3_dat
1bff0 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e a_count()]) do n
1c000 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 ot.** c
1c010 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72 20 hange the error
1c020 63 6f 64 65 20 6f 72 20 6d 65 73 73 61 67 65 20 code or message
1c030 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 returned by.**
1c040 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
1c050 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 _errcode()], [sq
1c060 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c lite3_errmsg()],
1c070 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 or [sqlite3_err
1c080 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 msg16()]..**.**
1c090 7b 46 31 32 38 30 39 7d 20 49 6e 74 65 72 66 61 {F12809} Interfa
1c0a0 63 65 73 20 74 68 61 74 20 61 72 65 20 6e 6f 74 ces that are not
1c0b0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
1c0c0 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 20 a specific.**
1c0d0 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 [databas
1c0e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 65 e connection] (e
1c0f0 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20 20 xamples:.**
1c100 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 70 [sqlite3_mp
1c110 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71 6c rintf()] or [sql
1c120 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 ite3_enable_shar
1c130 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20 20 ed_cache()].**
1c140 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74 20 63 do not c
1c150 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 hange the values
1c160 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
1c170 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
1c180 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 3_errcode()], [s
1c190 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
1c1a0 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 , or [sqlite3_er
1c1b0 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e rmsg16()]..*/.in
1c1c0 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 t sqlite3_errcod
1c1d0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a e(sqlite3 *db);.
1c1e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
1c1f0 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 te3_errmsg(sqlit
1c200 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 e3*);.const void
1c210 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 *sqlite3_errmsg
1c220 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 16(sqlite3*);../
1c230 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
1c240 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a QL Statement Obj
1c250 65 63 74 20 7b 46 31 33 30 30 30 7d 0a 2a 2a 20 ect {F13000}.**
1c260 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 KEYWORDS: {prepa
1c270 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b red statement} {
1c280 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1c290 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e nts}.**.** An in
1c2a0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
1c2b0 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 bject represents
1c2c0 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 a single SQL st
1c2d0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 atement..** This
1c2e0 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f object is vario
1c2f0 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 usly known as a
1c300 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d "prepared statem
1c310 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f ent" or a.** "co
1c320 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 mpiled SQL state
1c330 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 ment" or simply
1c340 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 as a "statement"
1c350 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 ..**.** The life
1c360 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 of a statement
1c370 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 object goes some
1c380 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a thing like this:
1c390 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c .**.** <ol>.** <
1c3a0 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f li> Create the o
1c3b0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c bject using [sql
1c3c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1c3d0 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a )] or a related.
1c3e0 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e ** function
1c3f0 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 ..** <li> Bind v
1c400 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 alues to [host p
1c410 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 arameters] using
1c420 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
1c430 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e d_*().** in
1c440 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 terfaces..** <li
1c450 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 > Run the SQL by
1c460 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
1c470 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 3_step()] one or
1c480 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 more times..**
1c490 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 <li> Reset the s
1c4a0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b tatement using [
1c4b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
1c4c0 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a then go back.**
1c4d0 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e to step 2.
1c4e0 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f Do this zero o
1c4f0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a r more times..**
1c500 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 <li> Destroy th
1c510 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b e object using [
1c520 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
1c530 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a ()]..** </ol>.**
1c540 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 .** Refer to doc
1c550 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e umentation on in
1c560 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 dividual methods
1c570 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 above for addit
1c580 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 ional.** informa
1c590 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 tion..*/.typedef
1c5a0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
1c5b0 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d stmt sqlite3_stm
1c5c0 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 t;../*.** CAPI3R
1c5d0 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d EF: Run-time Lim
1c5e0 69 74 73 20 7b 46 31 32 37 36 30 7d 0a 2a 2a 0a its {F12760}.**.
1c5f0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
1c600 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a e allows the siz
1c610 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e e of various con
1c620 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 structs to be li
1c630 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f mited.** on a co
1c640 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e nnection by conn
1c650 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 ection basis. T
1c660 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
1c670 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 er is the.** [da
1c680 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1c690 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 n] whose limit i
1c6a0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 s to be set or q
1c6b0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 ueried. The.**
1c6c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
1c6d0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b is one of the [
1c6e0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 limit categories
1c6f0 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a ] that define a.
1c700 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 ** class of cons
1c710 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a tructs to be siz
1c720 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 e limited. The
1c730 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
1c740 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 is the.** new li
1c750 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e mit for that con
1c760 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e struct. The fun
1c770 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
1c780 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a e old limit..**.
1c790 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20 6c 69 ** If the new li
1c7a0 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 mit is a negativ
1c7b0 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 e number, the li
1c7c0 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 mit is unchanged
1c7d0 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d ..** For the lim
1c7e0 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53 it category of S
1c7f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 QLITE_LIMIT_XYZ
1c800 74 68 65 72 65 20 69 73 20 61 20 68 61 72 64 20 there is a hard
1c810 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e 64 20 73 upper.** bound s
1c820 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d et by a compile-
1c830 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65 73 time C preproces
1c840 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 sor macro named
1c850 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a SQLITE_MAX_XYZ..
1c860 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f ** (The "_LIMIT_
1c870 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 " in the name is
1c880 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 changed to "_MA
1c890 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 X_".).** Attempt
1c8a0 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 s to increase a
1c8b0 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 limit above its
1c8c0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 hard upper bound
1c8d0 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 are.** silently
1c8e0 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 truncated to th
1c8f0 65 20 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d e hard upper lim
1c900 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 it..**.** Run ti
1c910 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e me limits are in
1c920 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 tended for use i
1c930 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 n applications t
1c940 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f hat manage.** bo
1c950 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 th their own int
1c960 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 ernal database a
1c970 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 nd also database
1c980 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 s that are contr
1c990 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 olled.** by untr
1c9a0 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 usted external s
1c9b0 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d ources. An exam
1c9c0 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 ple application
1c9d0 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 might be a.** we
1c9e0 62 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 bbrowser that ha
1c9f0 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 s its own databa
1ca00 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 ses for storing
1ca10 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 history and.** s
1ca20 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 eparate database
1ca30 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 s controlled by
1ca40 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 JavaScript appli
1ca50 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 cations download
1ca60 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e ed.** off the In
1ca70 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 ternet. The int
1ca80 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 ernal databases
1ca90 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 can be given the
1caa0 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 .** large, defau
1cab0 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 lt limits. Data
1cac0 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 bases managed by
1cad0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 external source
1cae0 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 s can.** be give
1caf0 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c n much smaller l
1cb00 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 imits designed t
1cb10 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 o prevent a deni
1cb20 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a al of service.**
1cb30 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f attack. Develo
1cb40 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 pers might also
1cb50 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 want to use the
1cb60 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
1cb70 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e horizer()].** in
1cb80 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 terface to furth
1cb90 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 er control untru
1cba0 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 sted SQL. The s
1cbb0 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ize of the datab
1cbc0 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 ase.** created b
1cbd0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 y an untrusted s
1cbe0 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e cript can be con
1cbf0 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 tained using the
1cc00 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f .** [max_page_co
1cc10 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a unt] [PRAGMA]..*
1cc20 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
1cc30 61 63 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 ace is currently
1cc40 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 considered expe
1cc50 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 rimental and is
1cc60 73 75 62 6a 65 63 74 0a 2a 2a 20 74 6f 20 63 68 subject.** to ch
1cc70 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 ange or removal
1cc80 77 69 74 68 6f 75 74 20 70 72 69 6f 72 20 6e 6f without prior no
1cc90 74 69 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 tice..**.** INVA
1cca0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 RIANTS:.**.** {F
1ccb0 31 32 37 36 32 7d 20 41 20 73 75 63 63 65 73 73 12762} A success
1ccc0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
1ccd0 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 ite3_limit(D,C,V
1cce0 29 5d 20 77 68 65 72 65 20 56 20 69 73 0a 2a 2a )] where V is.**
1ccf0 20 20 20 20 20 20 20 20 20 20 70 6f 73 69 74 69 positi
1cd00 76 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c ve changes the l
1cd10 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 imit on the size
1cd20 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20 of construct C
1cd30 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 in the.**
1cd40 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e [database con
1cd50 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 74 68 nection] D to th
1cd60 65 20 6c 65 73 73 65 72 20 6f 66 20 56 20 61 6e e lesser of V an
1cd70 64 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 d the hard upper
1cd80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6f 75 .** bou
1cd90 6e 64 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f nd on the size o
1cda0 66 20 43 20 74 68 61 74 20 69 73 20 73 65 74 20 f C that is set
1cdb0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e at compile-time.
1cdc0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36 36 7d 20 .**.** {F12766}
1cdd0 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c A successful cal
1cde0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 l to [sqlite3_li
1cdf0 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 mit(D,C,V)] wher
1ce00 65 20 56 20 69 73 20 6e 65 67 61 74 69 76 65 0a e V is negative.
1ce10 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 65 61 76 ** leav
1ce20 65 73 20 74 68 65 20 73 74 61 74 65 20 6f 66 20 es the state of
1ce30 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
1ce40 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 75 6e 63 68 nnection] D unch
1ce50 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 anged..**.** {F1
1ce60 32 37 36 39 7d 20 41 20 73 75 63 63 65 73 73 66 2769} A successf
1ce70 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ul call to [sqli
1ce80 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 te3_limit(D,C,V)
1ce90 5d 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a ] returns the.**
1cea0 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 value
1ceb0 6f 66 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 of the limit on
1cec0 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 the size of cons
1ced0 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a 2a truct C in the.*
1cee0 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 * [data
1cef0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1cf00 20 44 20 61 73 20 69 74 20 77 61 73 20 70 72 69 D as it was pri
1cf10 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 0a or to the call..
1cf20 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c */.int sqlite3_l
1cf30 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 imit(sqlite3*, i
1cf40 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 nt id, int newVa
1cf50 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
1cf60 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 REF: Run-Time Li
1cf70 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 20 7b mit Categories {
1cf80 46 31 32 37 39 30 7d 0a 2a 2a 20 4b 45 59 57 4f F12790}.** KEYWO
1cf90 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 RDS: {limit cate
1cfa0 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 gory} {limit cat
1cfb0 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 egories}.**.** T
1cfc0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 hese constants d
1cfd0 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 61 73 efine various as
1cfe0 70 65 63 74 73 20 6f 66 20 61 20 5b 64 61 74 61 pects of a [data
1cff0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1d000 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 .** that can be
1d010 6c 69 6d 69 74 65 64 20 69 6e 20 73 69 7a 65 20 limited in size
1d020 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c by calls to [sql
1d030 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a ite3_limit()]..*
1d040 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f * The meanings o
1d050 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 f the various li
1d060 6d 69 74 73 20 61 72 65 20 61 73 20 66 6f 6c 6c mits are as foll
1d070 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a ows:.**.** <dl>.
1d080 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ** <dt>SQLITE_LI
1d090 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a MIT_LENGTH</dt>.
1d0a0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
1d0b0 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 um size of any s
1d0c0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 tring or BLOB or
1d0d0 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a table row.<dd>.
1d0e0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
1d0f0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 _LIMIT_SQL_LENGT
1d100 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
1d110 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 e maximum length
1d120 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 of an SQL state
1d130 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ment.</dd>.**.**
1d140 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 <dt>SQLITE_LIMI
1d150 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a T_COLUMN</dt>.**
1d160 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
1d170 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
1d180 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 ns in a table de
1d190 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 finition or in t
1d1a0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 he.** result set
1d1b0 20 6f 66 20 61 20 53 45 4c 45 43 54 20 6f 72 20 of a SELECT or
1d1c0 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 the maximum numb
1d1d0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
1d1e0 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 an index.** or
1d1f0 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f in an ORDER BY o
1d200 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 r GROUP BY claus
1d210 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 e.</dd>.**.** <d
1d220 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 t>SQLITE_LIMIT_E
1d230 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a XPR_DEPTH</dt>.*
1d240 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
1d250 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 m depth of the p
1d260 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 arse tree on any
1d270 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 expression.</dd
1d280 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
1d290 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e TE_LIMIT_COMPOUN
1d2a0 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a D_SELECT</dt>.**
1d2b0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
1d2c0 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 number of terms
1d2d0 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 in a compound S
1d2e0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e ELECT statement.
1d2f0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
1d300 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 SQLITE_LIMIT_VDB
1d310 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 E_OP</dt>.** <dd
1d320 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
1d330 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 ber of instructi
1d340 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c ons in a virtual
1d350 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d machine program
1d360 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c .** used to impl
1d370 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 ement an SQL sta
1d380 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a tement.</dd>.**.
1d390 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ** <dt>SQLITE_LI
1d3a0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 MIT_FUNCTION_ARG
1d3b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
1d3c0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
1d3d0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 of arguments on
1d3e0 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e a function.</dd>
1d3f0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
1d400 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 E_LIMIT_ATTACHED
1d410 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
1d420 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
1d430 6f 66 20 61 74 74 61 63 68 65 64 20 64 61 74 61 of attached data
1d440 62 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a bases.</dd>.**.*
1d450 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d * <dt>SQLITE_LIM
1d460 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f IT_LIKE_PATTERN_
1d470 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c LENGTH</dt>.** <
1d480 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c dd>The maximum l
1d490 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 ength of the pat
1d4a0 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f tern argument to
1d4b0 20 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 the LIKE or.**
1d4c0 47 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c GLOB operators.<
1d4d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
1d4e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
1d4f0 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e ABLE_NUMBER</dt>
1d500 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
1d510 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 mum number of va
1d520 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 riables in an SQ
1d530 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 L statement that
1d540 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 can.** be bound
1d550 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a .</dd>.** </dl>.
1d560 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1d570 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 E_LIMIT_LENGTH
1d580 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1d590 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
1d5a0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e TE_LIMIT_SQL_LEN
1d5b0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 GTH
1d5c0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
1d5d0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e ITE_LIMIT_COLUMN
1d5e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1d5f0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
1d600 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
1d610 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 DEPTH
1d620 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
1d630 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 QLITE_LIMIT_COMP
1d640 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 OUND_SELECT
1d650 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 4.#define
1d660 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 SQLITE_LIMIT_VDB
1d670 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 E_OP
1d680 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 5.#define
1d690 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 SQLITE_LIMIT_FU
1d6a0 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 NCTION_ARG
1d6b0 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 6.#defin
1d6c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 e SQLITE_LIMIT_A
1d6d0 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 TTACHED
1d6e0 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 7.#defi
1d6f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
1d700 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e LIKE_PATTERN_LEN
1d710 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 GTH 8.#def
1d720 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
1d730 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
1d740 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 9../*
1d750 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
1d760 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 mpiling An SQL S
1d770 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 30 31 30 tatement {F13010
1d780 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
1d790 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f SQL statement co
1d7a0 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f mpiler}.**.** To
1d7b0 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 execute an SQL
1d7c0 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 query, it must f
1d7d0 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 irst be compiled
1d7e0 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 into a byte-cod
1d7f0 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 e.** program usi
1d800 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 ng one of these
1d810 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
1d820 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
1d830 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b nt, "db", is a [
1d840 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1d850 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 ion] obtained fr
1d860 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 63 61 om a.** prior ca
1d870 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f ll to [sqlite3_o
1d880 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
1d890 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 20 5b _open_v2()] or [
1d8a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
1d8b0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 ]..**.** The sec
1d8c0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a ond argument, "z
1d8d0 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 Sql", is the sta
1d8e0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d tement to be com
1d8f0 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a piled, encoded.*
1d900 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d * as either UTF-
1d910 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 8 or UTF-16. Th
1d920 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 e sqlite3_prepar
1d930 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f e() and sqlite3_
1d940 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 prepare_v2().**
1d950 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 interfaces use U
1d960 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 TF-8, and sqlite
1d970 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 3_prepare16() an
1d980 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
1d990 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 e16_v2().** use
1d9a0 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 UTF-16..**.** If
1d9b0 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d the nByte argum
1d9c0 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e ent is less than
1d9d0 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c zero, then zSql
1d9e0 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 is read up to t
1d9f0 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f he.** first zero
1da00 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 49 66 20 terminator. If
1da10 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 nByte is non-neg
1da20 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 ative, then it i
1da30 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a s the maximum.**
1da40 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 number of byte
1da50 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c s read from zSql
1da60 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73 . When nByte is
1da70 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 non-negative, t
1da80 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e he.** zSql strin
1da90 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 g ends at either
1daa0 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 the first '\000
1dab0 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 ' or '\u0000' ch
1dac0 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 aracter or.** th
1dad0 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c e nByte-th byte,
1dae0 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 whichever comes
1daf0 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 first. If the c
1db00 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 aller knows.** t
1db10 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 hat the supplied
1db20 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 string is nul-t
1db30 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 erminated, then
1db40 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c there is a small
1db50 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 .** performance
1db60 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 advantage to be
1db70 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e gained by passin
1db80 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d g an nByte param
1db90 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 eter that.** is
1dba0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d equal to the num
1dbb0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
1dbc0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
1dbd0 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 <i>including</i
1dbe0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 >.** the nul-ter
1dbf0 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a minator bytes..*
1dc00 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20 *.** *pzTail is
1dc10 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f made to point to
1dc20 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 20 the first byte
1dc30 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 past the end of
1dc40 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c the.** first SQL
1dc50 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 statement in zS
1dc60 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 ql. These routi
1dc70 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 nes only compile
1dc80 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 73 74 the first.** st
1dc90 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c atement in zSql,
1dca0 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c so *pzTail is l
1dcb0 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 eft pointing to
1dcc0 77 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20 what remains.**
1dcd0 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a uncompiled..**.*
1dce0 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 * *ppStmt is lef
1dcf0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 t pointing to a
1dd00 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 compiled [prepar
1dd10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
1dd20 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 at can be.** exe
1dd30 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c cuted using [sql
1dd40 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 49 ite3_step()]. I
1dd50 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 f there is an er
1dd60 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 ror, *ppStmt is
1dd70 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 set.** to NULL.
1dd80 20 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 If the input te
1dd90 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 xt contains no S
1dda0 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 QL (if the input
1ddb0 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 is an empty.**
1ddc0 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d string or a comm
1ddd0 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d ent) then *ppStm
1dde0 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c t is set to NULL
1ddf0 2e 0a 2a 2a 20 7b 41 31 33 30 31 38 7d 20 54 68 ..** {A13018} Th
1de00 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 e calling proced
1de10 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 ure is responsib
1de20 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 le for deleting
1de30 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 the compiled.**
1de40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 SQL statement us
1de50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
1de60 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 alize()] after i
1de70 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 t has finished w
1de80 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e ith it..**.** On
1de90 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 success, [SQLIT
1dea0 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 E_OK] is returne
1deb0 64 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 d, otherwise an
1dec0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 [error code] is
1ded0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
1dee0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 The sqlite3_prep
1def0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c are_v2() and sql
1df00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
1df10 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 2() interfaces a
1df20 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 re.** recommende
1df30 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 d for all new pr
1df40 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 ograms. The two
1df50 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 older interfaces
1df60 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a are retained.**
1df70 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 for backwards c
1df80 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 ompatibility, bu
1df90 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 t their use is d
1dfa0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 iscouraged..** I
1dfb0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 n the "v2" inter
1dfc0 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 faces, the prepa
1dfd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a red statement.**
1dfe0 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 that is returne
1dff0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f d (the [sqlite3_
1e000 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f stmt] object) co
1e010 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 ntains a copy of
1e020 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c the.** original
1e030 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 SQL text. This
1e040 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 causes the [sqli
1e050 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 te3_step()] inte
1e060 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 rface to.** beha
1e070 76 65 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79 ve a differently
1e080 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a in two ways:.**
1e090 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ol>.** <li>
1e0a0 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 .** If the datab
1e0b0 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 ase schema chang
1e0c0 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 es, instead of r
1e0d0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 eturning [SQLITE
1e0e0 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a _SCHEMA] as it.*
1e0f0 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f * always used to
1e100 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 do, [sqlite3_st
1e110 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d ep()] will autom
1e120 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 atically recompi
1e130 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 le the SQL.** st
1e140 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 atement and try
1e150 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e to run it again.
1e160 20 20 49 66 20 74 68 65 20 73 63 68 65 6d 61 20 If the schema
1e170 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a has changed in.*
1e180 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b * a way that mak
1e190 65 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 es the statement
1e1a0 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 no longer valid
1e1b0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
1e1c0 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a )] will still.**
1e1d0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
1e1e0 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e SCHEMA]. But un
1e1f0 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20 like the legacy
1e200 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 behavior, [SQLIT
1e210 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 E_SCHEMA] is.**
1e220 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f now a fatal erro
1e230 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c r. Calling [sql
1e240 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1e250 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f )] again will no
1e260 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 t make the.** er
1e270 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f ror go away. No
1e280 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33 te: use [sqlite3
1e290 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 _errmsg()] to fi
1e2a0 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f nd the text.** o
1e2b0 66 20 74 68 65 20 70 61 72 73 69 6e 67 20 65 72 f the parsing er
1e2c0 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73 ror that results
1e2d0 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 in an [SQLITE_S
1e2e0 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a CHEMA] return..*
1e2f0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c * </li>.**.** <l
1e300 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 i>.** When an er
1e310 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c ror occurs, [sql
1e320 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c ite3_step()] wil
1e330 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 l return one of
1e340 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 the detailed.**
1e350 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 [error codes] or
1e360 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 [extended error
1e370 20 63 6f 64 65 73 5d 2e 20 20 54 68 65 20 6c 65 codes]. The le
1e380 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 gacy behavior wa
1e390 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 s that.** [sqlit
1e3a0 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 e3_step()] would
1e3b0 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 only return a g
1e3c0 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 eneric [SQLITE_E
1e3d0 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 RROR] result cod
1e3e0 65 0a 2a 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75 e.** and you wou
1e3f0 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 ld have to make
1e400 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f a second call to
1e410 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
1e420 29 5d 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 )] in order.** t
1e430 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 o find the under
1e440 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 lying cause of t
1e450 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 he problem. With
1e460 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 the "v2" prepar
1e470 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c e.** interfaces,
1e480 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 the underlying
1e490 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 reason for the e
1e4a0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
1e4b0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a immediately..**
1e4c0 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a </li>.** </ol>.
1e4d0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
1e4e0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 31 7d :.**.** {F13011}
1e4f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 The [sqlite3_pr
1e500 65 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e epare(db,zSql,..
1e510 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 .)] and.**
1e520 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 [sqlite3_pre
1e530 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c pare_v2(db,zSql,
1e540 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73 ...)] interfaces
1e550 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a interpret the.*
1e560 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20 * text
1e570 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61 in their zSql pa
1e580 72 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 38 rameter as UTF-8
1e590 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 32 7d ..**.** {F13012}
1e5a0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 The [sqlite3_pr
1e5b0 65 70 61 72 65 31 36 28 64 62 2c 7a 53 71 6c 2c epare16(db,zSql,
1e5c0 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 ...)] and.**
1e5d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 [sqlite3_p
1e5e0 72 65 70 61 72 65 31 36 5f 76 32 28 64 62 2c 7a repare16_v2(db,z
1e5f0 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 Sql,...)] interf
1e600 61 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74 aces interpret t
1e610 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 he.** t
1e620 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71 ext in their zSq
1e630 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55 l parameter as U
1e640 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 TF-16 in the nat
1e650 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a ive byte order..
1e660 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 33 7d 20 49 **.** {F13013} I
1e670 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 f the nByte argu
1e680 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
1e690 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a _prepare_v2(db,z
1e6a0 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a Sql,nByte,...)].
1e6b0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 ** and
1e6c0 69 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20 its variants is
1e6d0 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 less than zero,
1e6e0 74 68 65 20 53 51 4c 20 74 65 78 74 20 69 73 0a the SQL text is.
1e6f0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 61 64 ** read
1e700 20 66 72 6f 6d 20 7a 53 71 6c 20 69 73 20 72 65 from zSql is re
1e710 61 64 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 ad up to the fir
1e720 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 st zero terminat
1e730 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 or..**.** {F1301
1e740 34 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 4} If the nByte
1e750 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c argument to [sql
1e760 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1e770 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e db,zSql,nByte,..
1e780 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 .)].**
1e790 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 and its variants
1e7a0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
1e7b0 2c 20 74 68 65 6e 20 61 74 20 6d 6f 73 74 20 6e , then at most n
1e7c0 42 79 74 65 73 20 62 79 74 65 73 20 6f 66 0a 2a Bytes bytes of.*
1e7d0 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 74 * SQL t
1e7e0 65 78 74 20 69 73 20 72 65 61 64 20 66 72 6f 6d ext is read from
1e7f0 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 zSql..**.** {F1
1e800 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69 74 65 3015} In [sqlite
1e810 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 3_prepare_v2(db,
1e820 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69 6c 29 zSql,N,P,pzTail)
1e830 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e ] and its varian
1e840 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 ts.** i
1e850 66 20 74 68 65 20 7a 53 71 6c 20 69 6e 70 75 74 f the zSql input
1e860 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6d text contains m
1e870 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 53 51 4c ore than one SQL
1e880 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 statement.**
1e890 20 20 20 20 20 20 20 61 6e 64 20 70 7a 54 61 69 and pzTai
1e8a0 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 l is not NULL, t
1e8b0 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d hen *pzTail is m
1e8c0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 ade to point to
1e8d0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
1e8e0 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20 first byte past
1e8f0 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 the end of the f
1e900 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 irst SQL stateme
1e910 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a 20 20 nt in zSql..**
1e920 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 57 68 <todo>Wh
1e930 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 69 6c 20 at does *pzTail
1e940 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 68 65 72 point to if ther
1e950 65 20 69 73 20 6f 6e 65 20 73 74 61 74 65 6d 65 e is one stateme
1e960 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a nt?</todo>.**.**
1e970 20 7b 46 31 33 30 31 36 7d 20 41 20 73 75 63 63 {F13016} A succ
1e980 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
1e990 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1e9a0 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70 70 53 v2(db,zSql,N,ppS
1e9b0 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 tmt,...)].**
1e9c0 20 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f 66 20 or one of
1e9d0 69 74 73 20 76 61 72 69 61 6e 74 73 20 77 72 69 its variants wri
1e9e0 74 65 73 20 69 6e 74 6f 20 2a 70 70 53 74 6d 74 tes into *ppStmt
1e9f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
1ea00 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 new.**
1ea10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1ea20 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e 74 65 ent] or a pointe
1ea30 72 20 74 6f 20 4e 55 4c 4c 20 69 66 20 7a 53 71 r to NULL if zSq
1ea40 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 l contains.**
1ea50 20 20 20 20 20 20 20 6e 6f 74 68 69 6e 67 20 6f nothing o
1ea60 74 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 ther than whites
1ea70 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 pace or comments
1ea80 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 39 7d ..**.** {F13019}
1ea90 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 The [sqlite3_pr
1eaa0 65 70 61 72 65 5f 76 32 28 29 5d 20 69 6e 74 65 epare_v2()] inte
1eab0 72 66 61 63 65 20 61 6e 64 20 69 74 73 20 76 61 rface and its va
1eac0 72 69 61 6e 74 73 20 72 65 74 75 72 6e 0a 2a 2a riants return.**
1ead0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 [SQLIT
1eae0 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61 70 70 72 E_OK] or an appr
1eaf0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 opriate [error c
1eb00 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69 6c 75 72 ode] upon failur
1eb10 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 32 31 e..**.** {F13021
1eb20 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 } Before [sqlite
1eb30 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71 3_prepare(db,zSq
1eb40 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d 74 2c 70 l,nByte,ppStmt,p
1eb50 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74 73 0a 2a zTail)] or its.*
1eb60 2a 20 20 20 20 20 20 20 20 20 20 76 61 72 69 61 * varia
1eb70 6e 74 73 20 72 65 74 75 72 6e 73 20 61 6e 20 65 nts returns an e
1eb80 72 72 6f 72 20 28 61 6e 79 20 76 61 6c 75 65 20 rror (any value
1eb90 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
1eba0 54 45 5f 4f 4b 5d 29 2c 0a 2a 2a 20 20 20 20 20 TE_OK]),.**
1ebb0 20 20 20 20 20 74 68 65 79 20 66 69 72 73 74 20 they first
1ebc0 73 65 74 20 2a 70 70 53 74 6d 74 20 74 6f 20 4e set *ppStmt to N
1ebd0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ULL..*/.int sqli
1ebe0 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 te3_prepare(. s
1ebf0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
1ec00 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
1ec10 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
1ec20 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
1ec30 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
1ec40 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 atement, UTF-8 e
1ec50 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
1ec60 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
1ec70 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
1ec80 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
1ec90 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
1eca0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
1ecb0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
1ecc0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
1ecd0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a . const char **
1ece0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
1ecf0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
1ed00 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
1ed10 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 zSql */.);.int s
1ed20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1ed30 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
1ed40 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
1ed50 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
1ed60 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
1ed70 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
1ed80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
1ed90 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a TF-8 encoded */.
1eda0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
1edb0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
1edc0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
1edd0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
1ede0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
1edf0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
1ee00 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
1ee10 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
1ee20 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 har **pzTail
1ee30 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
1ee40 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
1ee50 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
1ee60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 .int sqlite3_pre
1ee70 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 pare16(. sqlite
1ee80 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
1ee90 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
1eea0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
1eeb0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 void *zSql,
1eec0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
1eed0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 nt, UTF-16 encod
1eee0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
1eef0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
1ef00 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 /* Maximum lengt
1ef10 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
1ef20 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 es. */. sqlite3
1ef30 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
1ef40 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
1ef50 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
1ef60 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 onst void **pzTa
1ef70 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
1ef80 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
1ef90 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
1efa0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
1efb0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
1efc0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
1efd0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
1efe0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f tabase handle */
1eff0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a . const void *z
1f000 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 Sql, /* SQ
1f010 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 L statement, UTF
1f020 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 -16 encoded */.
1f030 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 int nByte,
1f040 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
1f050 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 mum length of zS
1f060 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a ql in bytes. */.
1f070 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a sqlite3_stmt *
1f080 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 *ppStmt, /* OUT
1f090 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 : Statement hand
1f0a0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
1f0b0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 id **pzTail
1f0c0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 /* OUT: Pointer
1f0d0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f to unused portio
1f0e0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a n of zSql */.);.
1f0f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46 3a 20 ./*.** CAPIREF:
1f100 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 Retrieving State
1f110 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33 31 30 30 ment SQL {F13100
1f120 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 }.**.** This int
1f130 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 erface can be us
1f140 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 ed to retrieve a
1f150 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 saved copy of t
1f160 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 he original.** S
1f170 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 QL text used to
1f180 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 create a [prepar
1f190 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 ed statement] if
1f1a0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 that statement
1f1b0 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 was.** compiled
1f1c0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 using either [sq
1f1d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1f1e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
1f1f0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e prepare16_v2()].
1f200 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
1f210 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 31 S:.**.** {F13101
1f220 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 } If the [prepar
1f230 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 ed statement] pa
1f240 73 73 65 64 20 61 73 20 74 68 65 20 61 72 67 75 ssed as the argu
1f250 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 ment to.**
1f260 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c [sqlite3_sql
1f270 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 ()] was compiled
1f280 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 using either [s
1f290 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1f2a0 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 2()] or.**
1f2b0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 [sqlite3_pre
1f2c0 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 74 68 pare16_v2()], th
1f2d0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 en [sqlite3_sql(
1f2e0 29 5d 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 )] returns.**
1f2f0 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 a pointer
1f300 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 to a zero-termi
1f310 6e 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e nated string con
1f320 74 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 taining a UTF-8
1f330 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 rendering.**
1f340 20 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69 of the ori
1f350 67 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d ginal SQL statem
1f360 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 ent..**.** {F131
1f370 30 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 02} If the [prep
1f380 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
1f390 70 61 73 73 65 64 20 61 73 20 74 68 65 20 61 72 passed as the ar
1f3a0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 gument to.**
1f3b0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 [sqlite3_s
1f3c0 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c ql()] was compil
1f3d0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 ed using either
1f3e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1f3f0 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 ()] or.**
1f400 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 [sqlite3_prep
1f410 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 5b are16()], then [
1f420 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 72 sqlite3_sql()] r
1f430 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
1f440 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 inter..**.** {F1
1f450 33 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e 67 3103} The string
1f460 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 returned by [sq
1f470 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d 20 69 73 lite3_sql(S)] is
1f480 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 valid until the
1f490 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
1f4a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1f4b0 5d 20 53 20 69 73 20 64 65 6c 65 74 65 64 20 75 ] S is deleted u
1f4c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 sing [sqlite3_fi
1f4d0 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 nalize(S)]..*/.c
1f4e0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
1f4f0 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 e3_sql(sqlite3_s
1f500 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
1f510 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 .** CAPI3REF: Dy
1f520 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 namically Typed
1f530 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b 46 31 Value Object {F1
1f540 35 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 5000}.** KEYWORD
1f550 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 S: {protected sq
1f560 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e lite3_value} {un
1f570 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
1f580 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 3_value}.**.** S
1f590 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 QLite uses the s
1f5a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
1f5b0 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 ect to represent
1f5c0 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 all values.** t
1f5d0 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 hat can be store
1f5e0 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 d in a database
1f5f0 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 table. SQLite us
1f600 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e es dynamic typin
1f610 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c g.** for the val
1f620 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56 ues it stores. V
1f630 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 alues stored in
1f640 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
1f650 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 jects.** can be
1f660 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 integers, floati
1f670 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c ng point values,
1f680 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c strings, BLOBs,
1f690 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 or NULL..**.**
1f6a0 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 An sqlite3_value
1f6b0 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 object may be e
1f6c0 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 ither "protected
1f6d0 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 " or "unprotecte
1f6e0 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 d"..** Some inte
1f6f0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 rfaces require a
1f700 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 protected sqlit
1f710 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 e3_value. Other
1f720 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 interfaces.** w
1f730 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 ill accept eithe
1f740 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 r a protected or
1f750 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 an unprotected
1f760 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a sqlite3_value..*
1f770 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 * Every interfac
1f780 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 e that accepts s
1f790 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 qlite3_value arg
1f7a0 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 uments specifies
1f7b0 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e .** whether or n
1f7c0 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 ot it requires a
1f7d0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 protected sqlit
1f7e0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 e3_value..**.**
1f7f0 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 The terms "prote
1f800 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f cted" and "unpro
1f810 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f tected" refer to
1f820 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a whether or not.
1f830 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 ** a mutex is he
1f840 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 ld. A internal
1f850 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f mutex is held fo
1f860 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a r a protected.**
1f870 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
1f880 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 bject but no mut
1f890 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 ex is held for a
1f8a0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a n unprotected.**
1f8b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
1f8c0 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 bject. If SQLit
1f8d0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f e is compiled to
1f8e0 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 be single-threa
1f8f0 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 ded.** (with [SQ
1f900 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
1f910 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 0] and with [sql
1f920 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 ite3_threadsafe(
1f930 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a )] returning 0).
1f940 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 ** or if SQLite
1f950 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 is run in one of
1f960 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d reduced mutex m
1f970 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 odes .** [SQLITE
1f980 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
1f990 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 READ] or [SQLITE
1f9a0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
1f9b0 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 EAD].** then the
1f9c0 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 re is no distinc
1f9d0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f tion between pro
1f9e0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f tected and unpro
1f9f0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
1fa00 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 3_value objects
1fa10 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 and they can be
1fa20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 used interchange
1fa30 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a ably. However,.
1fa40 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 ** for maximum c
1fa50 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 ode portability
1fa60 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 it is recommende
1fa70 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 d that applicati
1fa80 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b ons.** still mak
1fa90 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f e the distinctio
1faa0 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 n between betwee
1fab0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 n protected and
1fac0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 unprotected.** s
1fad0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
1fae0 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e ects even when n
1faf0 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 ot strictly requ
1fb00 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ired..**.** The
1fb10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
1fb20 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 jects that are p
1fb30 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 assed as paramet
1fb40 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 ers into the.**
1fb50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
1fb60 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 f [application-d
1fb70 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
1fb80 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 ions] are protec
1fb90 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ted..** The sqli
1fba0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
1fbb0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
1fbc0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
1fbd0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 value()] is unpr
1fbe0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 otected..** Unpr
1fbf0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
1fc00 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 value objects ma
1fc10 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 y only be used w
1fc20 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ith.** [sqlite3_
1fc30 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 result_value()]
1fc40 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e and [sqlite3_bin
1fc50 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 d_value()]..** T
1fc60 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
1fc70 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 e_blob | sqlite3
1fc80 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 _value_type()] f
1fc90 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 amily of.** inte
1fca0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 rfaces require p
1fcb0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
1fcc0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a _value objects..
1fcd0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
1fce0 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 t Mem sqlite3_va
1fcf0 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 lue;../*.** CAPI
1fd00 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 3REF: SQL Functi
1fd10 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 on Context Objec
1fd20 74 20 7b 46 31 36 30 30 31 7d 0a 2a 2a 0a 2a 2a t {F16001}.**.**
1fd30 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 The context in
1fd40 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e which an SQL fun
1fd50 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 ction executes i
1fd60 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a s stored in an.*
1fd70 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 * sqlite3_contex
1fd80 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 t object. A poi
1fd90 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 nter to an sqlit
1fda0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 e3_context objec
1fdb0 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 t.** is always f
1fdc0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
1fdd0 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 o [application-d
1fde0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
1fdf0 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 ions]..** The ap
1fe00 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
1fe10 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 d SQL function i
1fe20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
1fe30 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 ll pass this.**
1fe40 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 pointer through
1fe50 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 into calls to [s
1fe60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
1fe70 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 t | sqlite3_resu
1fe80 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 lt()],.** [sqlit
1fe90 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
1fea0 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 text()], [sqlite
1feb0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 3_user_data()],.
1fec0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ** [sqlite3_cont
1fed0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d ext_db_handle()]
1fee0 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 , [sqlite3_get_a
1fef0 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e uxdata()],.** an
1ff00 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 d/or [sqlite3_se
1ff10 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f t_auxdata()]..*/
1ff20 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
1ff30 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
1ff40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b sqlite3_context;
1ff50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1ff60 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 : Binding Values
1ff70 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 To Prepared Sta
1ff80 74 65 6d 65 6e 74 73 20 7b 46 31 33 35 30 30 7d tements {F13500}
1ff90 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 .** KEYWORDS: {h
1ffa0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b ost parameter} {
1ffb0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d host parameters}
1ffc0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
1ffd0 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 name}.** KEYWOR
1ffe0 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 DS: {SQL paramet
1fff0 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 er} {SQL paramet
20000 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 ers} {parameter
20010 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 binding}.**.** I
20020 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 n the SQL string
20030 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 s input to [sqli
20040 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
20050 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e ] and its varian
20060 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 ts,.** literals
20070 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 may be replaced
20080 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69 by a parameter i
20090 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 66 n one of these f
200a0 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e orms:.**.** <ul>
200b0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c .** <li> ?.** <
200c0 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 li> ?NNN.** <li
200d0 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 > :VVV.** <li>
200e0 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 @VVV.** <li> $
200f0 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a VVV.** </ul>.**.
20100 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65 ** In the parame
20110 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 ter forms shown
20120 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 above NNN is an
20130 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c integer literal,
20140 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69 73 20 61 .** and VVV is a
20150 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 n alpha-numeric
20160 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20 parameter name.
20170 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 The values of th
20180 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ese.** parameter
20190 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 s (also called "
201a0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e host parameter n
201b0 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 ames" or "SQL pa
201c0 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 rameters").** ca
201d0 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 n be set using t
201e0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
201f0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 *() routines def
20200 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a ined here..**.**
20210 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
20220 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ent to the sqlit
20230 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 e3_bind_*() rout
20240 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a ines is always.*
20250 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 * a pointer to t
20260 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
20270 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 ] object returne
20280 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 d from.** [sqlit
20290 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
202a0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 or its variants
202b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f ..**.** The seco
202c0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 nd argument is t
202d0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 he index of the
202e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f SQL parameter to
202f0 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 be set..** The
20300 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 leftmost SQL par
20310 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e ameter has an in
20320 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 dex of 1. When
20330 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a the same named.*
20340 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 * SQL parameter
20350 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 is used more tha
20360 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 n once, second a
20370 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a nd subsequent.**
20380 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 occurrences hav
20390 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 e the same index
203a0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 as the first oc
203b0 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 currence..** The
203c0 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 index for named
203d0 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 parameters can
203e0 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 be looked up usi
203f0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ng the.** [sqlit
20400 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
20410 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 r_index()] API i
20420 66 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 f desired. The
20430 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e index.** for "?N
20440 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 NN" parameters i
20450 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e s the value of N
20460 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 NN..** The NNN v
20470 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 alue must be bet
20480 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b ween 1 and the [
20490 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
204a0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 .** parameter [S
204b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
204c0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 ABLE_NUMBER] (de
204d0 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 fault value: 999
204e0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 )..**.** The thi
204f0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 rd argument is t
20500 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 he value to bind
20510 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 to the paramete
20520 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 r..**.** In thos
20530 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 e routines that
20540 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 have a fourth ar
20550 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 gument, its valu
20560 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 e is the.** numb
20570 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
20580 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 he parameter. T
20590 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 o be clear: the
205a0 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 value is the.**
205b0 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 number of <u>byt
205c0 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 es</u> in the va
205d0 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d lue, not the num
205e0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
205f0 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 s..** If the fou
20600 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
20610 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c negative, the l
20620 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 ength of the str
20630 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 ing is.** the nu
20640 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 mber of bytes up
20650 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 to the first ze
20660 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a ro terminator..*
20670 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 *.** The fifth a
20680 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
20690 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 e3_bind_blob(),
206a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
206b0 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 t(), and.** sqli
206c0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
206d0 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f ) is a destructo
206e0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 r used to dispos
206f0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 e of the BLOB or
20700 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 .** string after
20710 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 SQLite has fini
20720 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 49 66 shed with it. If
20730 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d the fifth argum
20740 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 ent is.** the sp
20750 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c ecial value [SQL
20760 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 ITE_STATIC], the
20770 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 n SQLite assumes
20780 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 that the.** inf
20790 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 ormation is in s
207a0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 tatic, unmanaged
207b0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 space and does
207c0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 not need to be f
207d0 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 reed..** If the
207e0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 fifth argument h
207f0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 as the value [SQ
20800 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c LITE_TRANSIENT],
20810 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 then.** SQLite
20820 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 makes its own pr
20830 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
20840 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 e data immediate
20850 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 ly, before.** th
20860 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
20870 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
20880 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ns..**.** The sq
20890 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 lite3_bind_zerob
208a0 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 lob() routine bi
208b0 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 nds a BLOB of le
208c0 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 ngth N that.** i
208d0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 s filled with ze
208e0 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f roes. A zeroblo
208f0 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 b uses a fixed a
20900 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a mount of memory.
20910 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 ** (just an inte
20920 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 ger to hold its
20930 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 size) while it i
20940 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 s being processe
20950 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 d..** Zeroblobs
20960 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 are intended to
20970 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f serve as placeho
20980 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 lders for BLOBs
20990 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 whose.** content
209a0 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 is later writte
209b0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 n using.** [sqli
209c0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 te3_blob_open |
209d0 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 incremental BLOB
209e0 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a I/O] routines..
209f0 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 76 61 ** A negative va
20a00 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f lue for the zero
20a10 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 blob results in
20a20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c a zero-length BL
20a30 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 OB..**.** The sq
20a40 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 lite3_bind_*() r
20a50 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 outines must be
20a60 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 called after.**
20a70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
20a80 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 _v2()] (and its
20a90 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 variants) or [sq
20aa0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 lite3_reset()] a
20ab0 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 nd.** before [sq
20ac0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a lite3_step()]..*
20ad0 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e * Bindings are n
20ae0 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 ot cleared by th
20af0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 e [sqlite3_reset
20b00 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 ()] routine..**
20b10 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 Unbound paramete
20b20 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 rs are interpret
20b30 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a ed as NULL..**.*
20b40 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
20b50 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
20b60 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f OK] on success o
20b70 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 r an error code
20b80 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 if.** anything g
20b90 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c oes wrong. [SQL
20ba0 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 ITE_RANGE] is re
20bb0 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 turned if the pa
20bc0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 rameter.** index
20bd0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
20be0 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d . [SQLITE_NOMEM
20bf0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 ] is returned if
20c00 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e malloc() fails.
20c10 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 .** [SQLITE_MISU
20c20 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 SE] might be ret
20c30 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 urned if these r
20c40 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c outines are call
20c50 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 ed on a.** virtu
20c60 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 al machine that
20c70 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 is the wrong sta
20c80 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 te or which has
20c90 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e already been fin
20ca0 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 alized..** Detec
20cb0 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 tion of misuse i
20cc0 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 s unreliable. A
20cd0 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 pplications shou
20ce0 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a ld not depend.**
20cf0 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 on SQLITE_MISUS
20d00 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 E returns. SQLI
20d10 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74 TE_MISUSE is int
20d20 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74 ended to indicat
20d30 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 e a.** a logic e
20d40 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c rror in the appl
20d50 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 ication. Future
20d60 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
20d70 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e ite might.** pan
20d80 69 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 ic rather than r
20d90 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 eturn SQLITE_MIS
20da0 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 USE..**.** See a
20db0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
20dc0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
20dd0 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nt()],.** [sqlit
20de0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
20df0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b r_name()], and [
20e00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
20e10 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
20e20 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
20e30 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 36 S:.**.** {F13506
20e40 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65 } The [SQL state
20e50 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72 ment compiler] r
20e60 65 63 6f 67 6e 69 7a 65 73 20 74 6f 6b 65 6e 73 ecognizes tokens
20e70 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 0a 2a 2a of the forms.**
20e80 20 20 20 20 20 20 20 20 20 20 22 3f 22 2c 20 22 "?", "
20e90 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c 20 22 ?NNN", "$VVV", "
20ea0 3a 56 56 56 22 2c 20 61 6e 64 20 22 40 56 56 56 :VVV", and "@VVV
20eb0 22 20 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74 " as SQL paramet
20ec0 65 72 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ers,.**
20ed0 20 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e where NNN is an
20ee0 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e y sequence of on
20ef0 65 20 6f 72 20 6d 6f 72 65 20 64 69 67 69 74 73 e or more digits
20f00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 .** and
20f10 20 77 68 65 72 65 20 56 56 56 20 69 73 20 61 6e where VVV is an
20f20 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e y sequence of on
20f30 65 20 6f 72 20 6d 6f 72 65 20 61 6c 70 68 61 6e e or more alphan
20f40 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 umeric.**
20f50 20 20 20 63 68 61 72 61 63 74 65 72 73 20 6f 72 characters or
20f60 20 22 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 "::" optionally
20f70 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20 73 followed by a s
20f80 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 tring containing
20f90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20 .** no
20fa0 73 70 61 63 65 73 20 61 6e 64 20 63 6f 6e 74 61 spaces and conta
20fb0 69 6e 65 64 20 77 69 74 68 69 6e 20 70 61 72 65 ined within pare
20fc0 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b ntheses..**.** {
20fd0 46 31 33 35 30 39 7d 20 54 68 65 20 69 6e 69 74 F13509} The init
20fe0 69 61 6c 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 ial value of an
20ff0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 SQL parameter is
21000 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 NULL..**.** {F1
21010 33 35 31 32 7d 20 54 68 65 20 69 6e 64 65 78 20 3512} The index
21020 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c 20 70 61 of an "?" SQL pa
21030 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6c rameter is one l
21040 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a arger than the.*
21050 2a 20 20 20 20 20 20 20 20 20 20 6c 61 72 67 65 * large
21060 73 74 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 st index of SQL
21070 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
21080 20 6c 65 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a left, or 1 if.*
21090 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 22 * the "
210a0 3f 22 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f ?" is the leftmo
210b0 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 st SQL parameter
210c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 35 7d ..**.** {F13515}
210d0 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e The index of an
210e0 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61 "?NNN" SQL para
210f0 6d 65 74 65 72 20 69 73 20 74 68 65 20 69 6e 74 meter is the int
21100 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 eger NNN..**.**
21110 7b 46 31 33 35 31 38 7d 20 54 68 65 20 69 6e 64 {F13518} The ind
21120 65 78 20 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c ex of an ":VVV",
21130 20 22 24 56 56 56 22 2c 20 6f 72 20 22 40 56 56 "$VVV", or "@VV
21140 56 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 V" SQL parameter
21150 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 is.**
21160 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 the same as the
21170 69 6e 64 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73 index of leftmos
21180 74 20 6f 63 63 75 72 72 65 6e 63 65 73 20 6f 66 t occurrences of
21190 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 the same.**
211a0 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2c parameter,
211b0 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61 or one more tha
211c0 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e n the largest in
211d0 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 dex over all.**
211e0 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 paramet
211f0 65 72 73 20 74 6f 20 74 68 65 20 6c 65 66 74 20 ers to the left
21200 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20 66 if this is the f
21210 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 0a irst occurrence.
21220 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 ** of t
21230 68 69 73 20 70 61 72 61 6d 65 74 65 72 2c 20 6f his parameter, o
21240 72 20 31 20 69 66 20 74 68 69 73 20 69 73 20 74 r 1 if this is t
21250 68 65 20 6c 65 66 74 6d 6f 73 74 20 70 61 72 61 he leftmost para
21260 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 meter..**.** {F1
21270 33 35 32 31 7d 20 54 68 65 20 5b 53 51 4c 20 73 3521} The [SQL s
21280 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 tatement compile
21290 72 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e r] fails with an
212a0 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 0a [SQLITE_RANGE].
212b0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f ** erro
212c0 72 20 69 66 20 74 68 65 20 69 6e 64 65 78 20 6f r if the index o
212d0 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 f an SQL paramet
212e0 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 er is less than
212f0 31 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 1.** or
21300 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 greater than th
21310 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 53 e compile-time S
21320 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 QLITE_MAX_VARIAB
21330 4c 45 5f 4e 55 4d 42 45 52 0a 2a 2a 20 20 20 20 LE_NUMBER.**
21340 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2e parameter.
21350 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 34 7d 20 .**.** {F13524}
21360 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 Calls to [sqlite
21370 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 3_bind_text | sq
21380 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 lite3_bind(S,N,V
21390 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 ,...)].**
213a0 20 20 20 61 73 73 6f 63 69 61 74 65 20 74 68 65 associate the
213b0 20 76 61 6c 75 65 20 56 20 77 69 74 68 20 61 6c value V with al
213c0 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 l SQL parameters
213d0 20 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 having an.**
213e0 20 20 20 20 20 20 20 69 6e 64 65 78 20 6f 66 20 index of
213f0 4e 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 N in the [prepar
21400 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e ed statement] S.
21410 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 37 7d 20 .**.** {F13527}
21420 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 Calls to [sqlite
21430 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 3_bind_text | sq
21440 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e lite3_bind(S,N,.
21450 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ..)].**
21460 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 override prior
21470 63 61 6c 6c 73 20 77 69 74 68 20 74 68 65 20 73 calls with the s
21480 61 6d 65 20 76 61 6c 75 65 73 20 6f 66 20 53 20 ame values of S
21490 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 and N..**.** {F1
214a0 33 35 33 30 7d 20 42 69 6e 64 69 6e 67 73 20 65 3530} Bindings e
214b0 73 74 61 62 6c 69 73 68 65 64 20 62 79 20 5b 73 stablished by [s
214c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
214d0 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 | sqlite3_bind(
214e0 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 S,...)].**
214f0 20 20 20 20 70 65 72 73 69 73 74 20 61 63 72 6f persist acro
21500 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c ss calls to [sql
21510 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a ite3_reset(S)]..
21520 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 33 7d 20 49 **.** {F13533} I
21530 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 n calls to [sqli
21540 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c te3_bind_blob(S,
21550 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 N,V,L,D)],.**
21560 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
21570 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c bind_text(S,N,V,
21580 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 L,D)], or.**
21590 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 [sqlite3_b
215a0 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 ind_text16(S,N,V
215b0 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 ,L,D)] SQLite bi
215c0 6e 64 73 20 74 68 65 20 66 69 72 73 74 20 4c 0a nds the first L.
215d0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 74 65 ** byte
215e0 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 s of the BLOB or
215f0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 string pointed
21600 74 6f 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a to by V, when L.
21610 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e ** is n
21620 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a on-negative..**.
21630 2a 2a 20 7b 46 31 33 35 33 36 7d 20 49 6e 20 63 ** {F13536} In c
21640 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
21650 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 _bind_text(S,N,V
21660 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 ,L,D)] or.**
21670 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 [sqlite3_b
21680 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 ind_text16(S,N,V
21690 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 ,L,D)] SQLite bi
216a0 6e 64 73 20 63 68 61 72 61 63 74 65 72 73 0a 2a nds characters.*
216b0 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 * from
216c0 56 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 V through the fi
216d0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 rst zero charact
216e0 65 72 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 er when L is neg
216f0 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 ative..**.** {F1
21700 33 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74 3539} In calls t
21710 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f o [sqlite3_bind_
21720 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d blob(S,N,V,L,D)]
21730 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 ,.** [s
21740 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
21750 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 (S,N,V,L,D)], or
21760 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
21770 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
21780 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 6(S,N,V,L,D)] wh
21790 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63 en D is the spec
217a0 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ial.**
217b0 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 constant [SQLITE
217c0 5f 53 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 _STATIC], SQLite
217d0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 assumes that th
217e0 65 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20 e value V.**
217f0 20 20 20 20 20 20 69 73 20 68 65 6c 64 20 69 6e is held in
21800 20 73 74 61 74 69 63 20 75 6e 6d 61 6e 61 67 65 static unmanage
21810 64 20 73 70 61 63 65 20 74 68 61 74 20 77 69 6c d space that wil
21820 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 l not change.**
21830 20 20 20 20 20 20 20 20 20 64 75 72 69 6e 67 20 during
21840 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 the lifetime of
21850 74 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a the binding..**.
21860 2a 2a 20 7b 46 31 33 35 34 32 7d 20 49 6e 20 63 ** {F13542} In c
21870 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
21880 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 _bind_blob(S,N,V
21890 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 ,L,D)],.**
218a0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e [sqlite3_bin
218b0 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 d_text(S,N,V,L,D
218c0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 )], or.**
218d0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 [sqlite3_bind
218e0 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c _text16(S,N,V,L,
218f0 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 D)] when D is th
21900 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 e special.**
21910 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b constant [
21920 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
21930 5d 2c 20 74 68 65 20 72 6f 75 74 69 6e 65 20 6d ], the routine m
21940 61 6b 65 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 akes a.**
21950 20 20 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 private copy
21960 6f 66 20 74 68 65 20 76 61 6c 75 65 20 56 20 62 of the value V b
21970 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 efore it returns
21980 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 35 7d ..**.** {F13545}
21990 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 In calls to [sq
219a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 lite3_bind_blob(
219b0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 S,N,V,L,D)],.**
219c0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
219d0 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 3_bind_text(S,N,
219e0 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 V,L,D)], or.**
219f0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
21a00 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e _bind_text16(S,N
21a10 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 ,V,L,D)] when D
21a20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a is a pointer to.
21a30 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 75 ** a fu
21a40 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69 nction, SQLite i
21a50 6e 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63 nvokes that func
21a60 74 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20 tion to destroy
21a70 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
21a80 76 61 6c 75 65 20 56 20 61 66 74 65 72 20 69 74 value V after it
21a90 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 has finished us
21aa0 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 56 2e ing the value V.
21ab0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 38 7d 20 .**.** {F13548}
21ac0 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c In calls to [sql
21ad0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c ite3_bind_zerobl
21ae0 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 ob(S,N,V,L)] the
21af0 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 value bound.**
21b00 20 20 20 20 20 20 20 20 20 69 73 20 61 20 42 4c is a BL
21b10 4f 42 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f OB of L bytes, o
21b20 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 r a zero-length
21b30 42 4c 4f 42 20 69 66 20 4c 20 69 73 20 6e 65 67 BLOB if L is neg
21b40 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 ative..**.** {F1
21b50 33 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74 3551} In calls t
21b60 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f o [sqlite3_bind_
21b70 76 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68 value(S,N,V)] th
21b80 65 20 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 e V argument may
21b90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 20 .** be
21ba0 65 69 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63 either a [protec
21bb0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
21bc0 65 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a e] object or an.
21bd0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70 ** [unp
21be0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
21bf0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a _value] object..
21c00 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
21c10 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 ind_blob(sqlite3
21c20 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
21c30 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c st void*, int n,
21c40 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
21c50 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
21c60 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 nd_double(sqlite
21c70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 3_stmt*, int, do
21c80 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 uble);.int sqlit
21c90 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 e3_bind_int(sqli
21ca0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
21cb0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 int);.int sqlite
21cc0 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 3_bind_int64(sql
21cd0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
21ce0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b sqlite3_int64);
21cf0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
21d00 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 d_null(sqlite3_s
21d10 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 tmt*, int);.int
21d20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
21d30 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
21d40 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 int, const char
21d50 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a *, int n, void(*
21d60 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 )(void*));.int s
21d70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
21d80 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
21d90 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 , int, const voi
21da0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
21db0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 (void*));.int sq
21dc0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 lite3_bind_value
21dd0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
21de0 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 int, const sqlit
21df0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 e3_value*);.int
21e00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 sqlite3_bind_zer
21e10 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 oblob(sqlite3_st
21e20 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 mt*, int, int n)
21e30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
21e40 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c F: Number Of SQL
21e50 20 50 61 72 61 6d 65 74 65 72 73 20 7b 46 31 33 Parameters {F13
21e60 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 600}.**.** This
21e70 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 routine can be u
21e80 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 sed to find the
21e90 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 number of [SQL p
21ea0 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e arameters].** in
21eb0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
21ec0 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 tement]. SQL pa
21ed0 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b rameters are tok
21ee0 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f ens of the.** fo
21ef0 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 rm "?", "?NNN",
21f00 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 ":AAA", "$AAA",
21f10 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 or "@AAA" that s
21f20 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 erve as.** place
21f30 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 holders for valu
21f40 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c es that are [sql
21f50 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c ite3_bind_blob |
21f60 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 bound].** to th
21f70 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 e parameters at
21f80 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a a later time..**
21f90 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
21fa0 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e actually return
21fb0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
21fc0 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 he largest (righ
21fd0 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 tmost).** parame
21fe0 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 ter. For all for
21ff0 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 ms except ?NNN,
22000 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 this will corres
22010 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e pond to the.** n
22020 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 umber of unique
22030 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 parameters. If
22040 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 parameters of th
22050 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c e ?NNN are used,
22060 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 .** there may be
22070 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 gaps in the lis
22080 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 t..**.** See als
22090 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
220a0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 _blob|sqlite3_bi
220b0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nd()],.** [sqlit
220c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
220d0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a r_name()], and.*
220e0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
220f0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
22100 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 )]..**.** INVARI
22110 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 ANTS:.**.** {F13
22120 36 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 601} The [sqlite
22130 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
22140 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 _count(S)] inter
22150 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 face returns.**
22160 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 61 72 the lar
22170 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 61 6c gest index of al
22180 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 l SQL parameters
22190 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 in the.**
221a0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 [prepared st
221b0 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30 atement] S, or 0
221c0 20 69 66 20 53 20 63 6f 6e 74 61 69 6e 73 20 6e if S contains n
221d0 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 o SQL parameters
221e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
221f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
22200 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 count(sqlite3_st
22210 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
22220 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 I3REF: Name Of A
22230 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20 Host Parameter
22240 7b 46 31 33 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 {F13620}.**.** T
22250 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
22260 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
22270 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
22280 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 n-th.** [SQL pa
22290 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b 70 rameter] in a [p
222a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
222b0 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d t]..** SQL param
222c0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 eters of the for
222d0 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 m "?NNN" or ":AA
222e0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 A" or "@AAA" or
222f0 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 "$AAA".** have a
22300 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 name which is t
22310 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 he string "?NNN"
22320 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 or ":AAA" or "@
22330 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a AAA" or "$AAA".*
22340 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a * respectively..
22350 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 ** In other word
22360 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 s, the initial "
22370 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 :" or "$" or "@"
22380 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e or "?".** is in
22390 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f cluded as part o
223a0 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 f the name..** P
223b0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 arameters of the
223c0 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 form "?" withou
223d0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e t a following in
223e0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 teger have no na
223f0 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c me.** and are al
22400 73 6f 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 so referred to a
22410 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 s "anonymous par
22420 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 ameters"..**.**
22430 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 The first host p
22440 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 arameter has an
22450 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 index of 1, not
22460 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 0..**.** If the
22470 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f value n is out o
22480 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 f range or if th
22490 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 e n-th parameter
224a0 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c is.** nameless,
224b0 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 then NULL is re
224c0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74 turned. The ret
224d0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a urned string is.
224e0 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 ** always in UTF
224f0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e -8 encoding even
22500 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 if the named pa
22510 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f rameter was.** o
22520 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 riginally specif
22530 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e ied as UTF-16 in
22540 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
22550 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 e16()] or.** [sq
22560 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
22570 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 v2()]..**.** See
22580 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
22590 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 bind_blob|sqlite
225a0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 3_bind()],.** [s
225b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
225c0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 meter_count()],
225d0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
225e0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
225f0 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 ndex()]..**.** I
22600 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
22610 20 7b 46 31 33 36 32 31 7d 20 54 68 65 20 5b 73 {F13621} The [s
22620 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
22630 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d meter_name(S,N)]
22640 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
22650 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 ns.** a
22660 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 UTF-8 rendering
22670 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 of the name of
22680 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 the SQL paramete
22690 72 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 r in.**
226a0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
226b0 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69 tatement] S havi
226c0 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a ng index N, or.*
226d0 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 * NULL
226e0 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53 if there is no S
226f0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 QL parameter wit
22700 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 h index N or if
22710 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
22720 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 parameter with i
22730 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f ndex N is an ano
22740 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 nymous parameter
22750 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 "?"..*/.const c
22760 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e har *sqlite3_bin
22770 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
22780 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
22790 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
227a0 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 I3REF: Index Of
227b0 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 A Parameter With
227c0 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 46 A Given Name {F
227d0 31 33 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 13640}.**.** Ret
227e0 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 urn the index of
227f0 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 an SQL paramete
22800 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 r given its name
22810 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 . The.** index
22820 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 value returned i
22830 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 s suitable for u
22840 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 se as the second
22850 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f .** parameter to
22860 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
22870 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 lob|sqlite3_bind
22880 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 ()]. A zero.**
22890 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e is returned if n
228a0 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d o matching param
228b0 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 eter is found.
228c0 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a The parameter.**
228d0 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 name must be gi
228e0 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 ven in UTF-8 eve
228f0 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 n if the origina
22900 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 l statement.** w
22910 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d as prepared from
22920 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 UTF-16 text usi
22930 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ng [sqlite3_prep
22940 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a are16_v2()]..**.
22950 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
22960 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
22970 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
22980 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
22990 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
229a0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 t()], and.** [sq
229b0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
229c0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a eter_index()]..*
229d0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
229e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 34 31 7d 20 .**.** {F13641}
229f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e The [sqlite3_bin
22a00 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
22a10 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 x(S,N)] interfac
22a20 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 e returns.**
22a30 20 20 20 20 20 20 74 68 65 20 69 6e 64 65 78 20 the index
22a40 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 of SQL parameter
22a50 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 in the [prepare
22a60 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 d statement].**
22a70 20 20 20 20 20 20 20 20 20 53 20 77 68 6f 73 65 S whose
22a80 20 6e 61 6d 65 20 6d 61 74 63 68 65 73 20 74 68 name matches th
22a90 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e e UTF-8 string N
22aa0 2c 20 6f 72 20 30 20 69 66 20 74 68 65 72 65 20 , or 0 if there
22ab0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e is.** n
22ac0 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20 o match..*/.int
22ad0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
22ae0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c ameter_index(sql
22af0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 ite3_stmt*, cons
22b00 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a t char *zName);.
22b10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
22b20 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 Reset All Bindi
22b30 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 ngs On A Prepare
22b40 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 d Statement {F13
22b50 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 660}.**.** Contr
22b60 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 ary to the intui
22b70 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 tion of many, [s
22b80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
22b90 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a does not reset.*
22ba0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 * the [sqlite3_b
22bb0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 ind_blob | bindi
22bc0 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 ngs] on a [prepa
22bd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
22be0 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 ** Use this rout
22bf0 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c ine to reset all
22c00 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 host parameters
22c10 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 to NULL..**.**
22c20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
22c30 2a 20 7b 46 31 33 36 36 31 7d 20 54 68 65 20 5b * {F13661} The [
22c40 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 sqlite3_clear_bi
22c50 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72 ndings(S)] inter
22c60 66 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c 20 face resets all
22c70 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 SQL.**
22c80 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e parameter bindin
22c90 67 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 gs in the [prepa
22ca0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
22cb0 20 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a back to NULL..*
22cc0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c /.int sqlite3_cl
22cd0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c ear_bindings(sql
22ce0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
22cf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 .** CAPI3REF: Nu
22d00 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 mber Of Columns
22d10 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 In A Result Set
22d20 7b 46 31 33 37 31 30 7d 0a 2a 2a 0a 2a 2a 20 52 {F13710}.**.** R
22d30 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 eturn the number
22d40 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 of columns in t
22d50 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 he result set re
22d60 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a turned by the.**
22d70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
22d80 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 ment]. This rout
22d90 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 ine returns 0 if
22da0 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c pStmt is an SQL
22db0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 .** statement th
22dc0 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 at does not retu
22dd0 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 rn data (for exa
22de0 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d mple an [UPDATE]
22df0 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 )..**.** INVARIA
22e00 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 NTS:.**.** {F137
22e10 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 11} The [sqlite3
22e20 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 _column_count(S)
22e30 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
22e40 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
22e50 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f f.** co
22e60 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 lumns in the res
22e70 75 6c 74 20 73 65 74 20 67 65 6e 65 72 61 74 65 ult set generate
22e80 64 20 62 79 20 74 68 65 20 5b 70 72 65 70 61 72 d by the [prepar
22e90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c ed statement] S,
22ea0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
22eb0 30 20 69 66 20 53 20 64 6f 65 73 20 6e 6f 74 20 0 if S does not
22ec0 67 65 6e 65 72 61 74 65 20 61 20 72 65 73 75 6c generate a resul
22ed0 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 t set..*/.int sq
22ee0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 lite3_column_cou
22ef0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 nt(sqlite3_stmt
22f00 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
22f10 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e CAPI3REF: Column
22f20 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 Names In A Resu
22f30 6c 74 20 53 65 74 20 7b 46 31 33 37 32 30 7d 0a lt Set {F13720}.
22f40 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
22f50 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 ines return the
22f60 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f name assigned to
22f70 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f a particular co
22f80 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 lumn.** in the r
22f90 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b esult set of a [
22fa0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
22fb0 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f t. The sqlite3_
22fc0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a column_name().**
22fd0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
22fe0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
22ff0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
23000 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a d UTF-8 string.*
23010 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f * and sqlite3_co
23020 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 lumn_name16() re
23030 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
23040 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
23050 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 ated.** UTF-16 s
23060 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72 73 tring. The firs
23070 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 t parameter is t
23080 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
23090 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 tement].** that
230a0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b implements the [
230b0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
230c0 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 t. The second pa
230d0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
230e0 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e * column number.
230f0 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 The leftmost c
23100 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 olumn is number
23110 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 0..**.** The ret
23120 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 urned string poi
23130 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e nter is valid un
23140 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b til either the [
23150 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
23160 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f nt].** is destro
23170 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f yed by [sqlite3_
23180 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 finalize()] or u
23190 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 ntil the next ca
231a0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ll to.** sqlite3
231b0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f _column_name() o
231c0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
231d0 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 _name16() on the
231e0 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a same column..**
231f0 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d .** If sqlite3_m
23200 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 alloc() fails du
23210 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 ring the process
23220 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f ing of either ro
23230 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 utine.** (for ex
23240 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 ample during a c
23250 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 onversion from U
23260 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 TF-8 to UTF-16)
23270 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 then a.** NULL p
23280 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e ointer is return
23290 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 ed..**.** The na
232a0 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 me of a result c
232b0 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c olumn is the val
232c0 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 ue of the "AS" c
232d0 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 lause for.** tha
232e0 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 t column, if the
232f0 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 re is an AS clau
23300 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 se. If there is
23310 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a no AS clause.**
23320 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f then the name o
23330 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 f the column is
23340 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 unspecified and
23350 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a may change from.
23360 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f ** one release o
23370 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 f SQLite to the
23380 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 next..**.** INVA
23390 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 RIANTS:.**.** {F
233a0 31 33 37 32 31 7d 20 41 20 73 75 63 63 65 73 73 13721} A success
233b0 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f ful invocation o
233c0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 f the [sqlite3_c
233d0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d olumn_name(S,N)]
233e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 .** int
233f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
23400 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e he name of the N
23410 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 th column (where
23420 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 0 is.**
23430 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 the leftmost c
23440 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 72 olumn) for the r
23450 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 esult set of the
23460 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
23470 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
23480 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 ] S as a zero-te
23490 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
234a0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 tring..**.** {F1
234b0 33 37 32 33 7d 20 41 20 73 75 63 63 65 73 73 66 3723} A successf
234c0 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 ul invocation of
234d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
234e0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 lumn_name16(S,N)
234f0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e ].** in
23500 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
23510 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
23520 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 Nth column (wher
23530 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 e 0 is.**
23540 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 the leftmost
23550 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 column) for the
23560 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 result set of th
23570 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 e.** [p
23580 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
23590 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d 74 t] S as a zero-t
235a0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 erminated UTF-16
235b0 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 string.**
235c0 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76 in the nativ
235d0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a e byte order..**
235e0 0a 2a 2a 20 7b 46 31 33 37 32 34 7d 20 54 68 65 .** {F13724} The
235f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
23600 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73 71 _name()] and [sq
23610 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
23620 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 e16()].**
23630 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 interfaces re
23640 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e turn a NULL poin
23650 74 65 72 20 69 66 20 74 68 65 79 20 61 72 65 20 ter if they are
23660 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20 20 unable to.**
23670 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 20 6d allocate m
23680 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
23690 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 74 75 72 eir normal retur
236a0 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a n strings..**.**
236b0 20 7b 46 31 33 37 32 35 7d 20 49 66 20 74 68 65 {F13725} If the
236c0 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 N parameter to
236d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
236e0 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a name(S,N)] or.**
236f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
23700 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
23710 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f 66 (S,N)] is out of
23720 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74 68 65 range, then the
23730 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 .** int
23740 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61 erfaces return a
23750 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
23760 2a 0a 2a 2a 20 7b 46 31 33 37 32 36 7d 20 54 68 *.** {F13726} Th
23770 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e e strings return
23780 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 ed by [sqlite3_c
23790 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d olumn_name(S,N)]
237a0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
237b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
237c0 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 61 72 _name16(S,N)] ar
237d0 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 e valid until th
237e0 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 e next.**
237f0 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 call to eithe
23800 72 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 74 r routine with t
23810 68 65 20 73 61 6d 65 20 53 20 61 6e 64 20 4e 20 he same S and N
23820 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 parameters.**
23830 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 or until
23840 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
23850 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e e(S)] is called.
23860 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 37 7d 20 .**.** {F13727}
23870 57 68 65 6e 20 61 20 72 65 73 75 6c 74 20 63 6f When a result co
23880 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c 45 43 lumn of a [SELEC
23890 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6e T] statement con
238a0 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 tains.**
238b0 20 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2c 20 an AS clause,
238c0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 61 74 the name of that
238d0 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 69 column is the i
238e0 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20 20 20 20 dentifier.**
238f0 20 20 20 20 20 20 74 6f 20 74 68 65 20 72 69 67 to the rig
23900 68 74 20 6f 66 20 74 68 65 20 41 53 20 6b 65 79 ht of the AS key
23910 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 word..*/.const c
23920 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
23930 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 umn_name(sqlite3
23940 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a _stmt*, int N);.
23950 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
23960 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 te3_column_name1
23970 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
23980 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 int N);../*.**
23990 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 CAPI3REF: Source
239a0 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 Of Data In A Qu
239b0 65 72 79 20 52 65 73 75 6c 74 20 7b 46 31 33 37 ery Result {F137
239c0 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 40}.**.** These
239d0 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 routines provide
239e0 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 a means to dete
239f0 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d rmine what colum
23a00 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 n of what.** tab
23a10 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 le in which data
23a20 62 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 base a result of
23a30 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 a [SELECT] stat
23a40 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d ement comes from
23a50 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 ..** The name of
23a60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 the database or
23a70 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e table or column
23a80 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 can be returned
23a90 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 as.** either a
23aa0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 UTF-8 or UTF-16
23ab0 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 string. The _da
23ac0 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 tabase_ routines
23ad0 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 return.** the d
23ae0 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 atabase name, th
23af0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e e _table_ routin
23b00 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 es return the ta
23b10 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a ble name, and.**
23b20 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 the origin_ rou
23b30 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 tines return the
23b40 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a column name..**
23b50 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 The returned st
23b60 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e ring is valid un
23b70 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 til the [prepare
23b80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 d statement] is
23b90 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 destroyed.** usi
23ba0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
23bb0 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c lize()] or until
23bc0 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d the same inform
23bd0 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 ation is request
23be0 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 ed.** again in a
23bf0 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 different encod
23c00 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e ing..**.** The n
23c10 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 ames returned ar
23c20 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 e the original u
23c30 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 n-aliased names
23c40 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 of the.** databa
23c50 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 se, table, and c
23c60 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 olumn..**.** The
23c70 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
23c80 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 to the following
23c90 20 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 calls is a [pre
23ca0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
23cb0 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 ..** These funct
23cc0 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f ions return info
23cd0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 rmation about th
23ce0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 e Nth column ret
23cf0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 urned by.** the
23d00 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 statement, where
23d10 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 N is the second
23d20 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 function argume
23d30 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 nt..**.** If the
23d40 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 Nth column retu
23d50 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 rned by the stat
23d60 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 ement is an expr
23d70 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 ession or.** sub
23d80 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 query and is not
23d90 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c a column value,
23da0 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 then all of the
23db0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 se functions ret
23dc0 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 urn.** NULL. Th
23dd0 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 ese routine migh
23de0 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 t also return NU
23df0 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 LL if a memory a
23e00 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a llocation error.
23e10 2a 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 ** occurs. Othe
23e20 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 rwise, they retu
23e30 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 rn the name of t
23e40 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 he attached data
23e50 62 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 base, table.** a
23e60 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 nd column that q
23e70 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 uery result colu
23e80 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 mn was extracted
23e90 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 from..**.** As
23ea0 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 with all other S
23eb0 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 QLite APIs, thos
23ec0 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 e postfixed with
23ed0 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 "16" return.**
23ee0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 UTF-16 encoded s
23ef0 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 trings, the othe
23f00 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 r functions retu
23f10 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a rn UTF-8. {END}.
23f20 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 **.** These APIs
23f30 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 are only availa
23f40 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 ble if the libra
23f50 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 ry was compiled
23f60 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c with the.** [SQL
23f70 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d ITE_ENABLE_COLUM
23f80 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 N_METADATA] C-pr
23f90 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f eprocessor symbo
23fa0 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a l defined..**.**
23fb0 20 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 {A13751}.** If
23fc0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 two or more thre
23fd0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 ads call one or
23fe0 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f more of these ro
23ff0 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 utines against t
24000 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 he same.** prepa
24010 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e red statement an
24020 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 d column at the
24030 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 same time then t
24040 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a he results are.*
24050 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a * undefined..**.
24060 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
24070 2a 0a 2a 2a 20 7b 46 31 33 37 34 31 7d 20 54 68 *.** {F13741} Th
24080 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d e [sqlite3_colum
24090 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 n_database_name(
240a0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 S,N)] interface
240b0 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a returns either.*
240c0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 * the U
240d0 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e TF-8 zero-termin
240e0 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 ated name of the
240f0 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 77 database from w
24100 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 hich the.**
24110 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 Nth result
24120 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 column of the [p
24130 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
24140 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65 t] S is extracte
24150 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f d,.** o
24160 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 r NULL if the Nt
24170 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 h column of S is
24180 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 a general expre
24190 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ssion.**
241a0 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 or if unable t
241b0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 o allocate memor
241c0 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e y to store the n
241d0 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 ame..**.** {F137
241e0 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 42} The [sqlite3
241f0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
24200 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e _name16(S,N)] in
24210 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
24220 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 either.**
24230 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 the UTF-16 na
24240 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
24250 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
24260 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 name of the data
24270 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 base.**
24280 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 from which the
24290 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d Nth result colum
242a0 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 n of the [prepar
242b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
242c0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 is.** e
242d0 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c xtracted, or NUL
242e0 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c L if the Nth col
242f0 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 umn of S is a ge
24300 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e neral expression
24310 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
24320 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c if unable to all
24330 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 ocate memory to
24340 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a store the name..
24350 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 33 7d 20 54 **.** {F13743} T
24360 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 he [sqlite3_colu
24370 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53 2c mn_table_name(S,
24380 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 N)] interface re
24390 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 turns either.**
243a0 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 the UTF
243b0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 -8 zero-terminat
243c0 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 ed name of the t
243d0 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68 20 able from which
243e0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
243f0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d Nth result colum
24400 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 n of the [prepar
24410 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
24420 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a is extracted,.**
24430 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c or NUL
24440 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c L if the Nth col
24450 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 umn of S is a ge
24460 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e neral expression
24470 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
24480 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c if unable to all
24490 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 ocate memory to
244a0 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a store the name..
244b0 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 34 7d 20 54 **.** {F13744} T
244c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 he [sqlite3_colu
244d0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 mn_table_name16(
244e0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 S,N)] interface
244f0 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a returns either.*
24500 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 * the U
24510 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 TF-16 native byt
24520 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 e order zero-ter
24530 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 minated name of
24540 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 the table.**
24550 20 20 20 20 20 20 66 72 6f 6d 20 77 68 69 63 68 from which
24560 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 the Nth result
24570 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 column of the [p
24580 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
24590 74 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 t] S is.**
245a0 20 20 20 20 65 78 74 72 61 63 74 65 64 2c 20 6f extracted, o
245b0 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 r NULL if the Nt
245c0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 h column of S is
245d0 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 a general expre
245e0 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ssion.**
245f0 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 or if unable t
24600 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 o allocate memor
24610 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e y to store the n
24620 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 ame..**.** {F137
24630 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 45} The [sqlite3
24640 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e _column_origin_n
24650 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 ame(S,N)] interf
24660 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 ace returns eith
24670 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 er.** t
24680 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 he UTF-8 zero-te
24690 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 rminated name of
246a0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d the table colum
246b0 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 n from which the
246c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 .** Nth
246d0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f result column o
246e0 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 f the [prepared
246f0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 statement] S is
24700 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 extracted,.**
24710 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 or NULL i
24720 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e f the Nth column
24730 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 of S is a gener
24740 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a al expression.**
24750 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 or if
24760 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
24770 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f te memory to sto
24780 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a re the name..**.
24790 2a 2a 20 7b 46 31 33 37 34 36 7d 20 54 68 65 20 ** {F13746} The
247a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
247b0 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c origin_name16(S,
247c0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 N)] interface re
247d0 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 turns either.**
247e0 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 the UTF
247f0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 -16 native byte
24800 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 order zero-termi
24810 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 nated name of th
24820 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 e table.**
24830 20 20 20 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 column from
24840 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65 which the Nth re
24850 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 sult column of t
24860 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
24870 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
24880 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 nt] S is extract
24890 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 ed, or NULL if t
248a0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 0a 2a 2a he Nth column.**
248b0 20 20 20 20 20 20 20 20 20 20 6f 66 20 53 20 69 of S i
248c0 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 s a general expr
248d0 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 ession or if una
248e0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 ble to allocate
248f0 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 memory.**
24900 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 to store the
24910 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 name..**.** {F13
24920 37 34 38 7d 20 54 68 65 20 72 65 74 75 72 6e 20 748} The return
24930 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 values from.**
24940 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
24950 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
24960 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d _name | column m
24970 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 etadata interfac
24980 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 es].**
24990 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 74 68 are valid for th
249a0 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 e lifetime of th
249b0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
249c0 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 ement].**
249d0 20 20 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 or until the
249e0 65 6e 63 6f 64 69 6e 67 20 69 73 20 63 68 61 6e encoding is chan
249f0 67 65 64 20 62 79 20 61 6e 6f 74 68 65 72 20 6d ged by another m
24a00 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 etadata.**
24a10 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 interface ca
24a20 6c 6c 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 ll for the same
24a30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
24a40 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a nt and column..*
24a50 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 *.** LIMITATIONS
24a60 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d :.**.** {A13751}
24a70 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 If two or more
24a80 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 threads call one
24a90 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 or more.**
24aa0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f [sqlite3_co
24ab0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
24ac0 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 me | column meta
24ad0 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d data interfaces]
24ae0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 .** for
24af0 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 the same [prepa
24b00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 red statement] a
24b10 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e nd result column
24b20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 20 .** at
24b30 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 the same time th
24b40 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 en the results a
24b50 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f re undefined..*/
24b60 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
24b70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 ite3_column_data
24b80 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 base_name(sqlite
24b90 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
24ba0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
24bb0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 3_column_databas
24bc0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 e_name16(sqlite3
24bd0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
24be0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
24bf0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 _column_table_na
24c00 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
24c10 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
24c20 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
24c30 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 n_table_name16(s
24c40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
24c50 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 );.const char *s
24c60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 qlite3_column_or
24c70 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 igin_name(sqlite
24c80 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
24c90 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
24ca0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 3_column_origin_
24cb0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
24cc0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a tmt*,int);../*.*
24cd0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c * CAPI3REF: Decl
24ce0 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 ared Datatype Of
24cf0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 A Query Result
24d00 7b 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 {F13760}.**.** T
24d10 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
24d20 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 er is a [prepare
24d30 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
24d40 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 If this stateme
24d50 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d nt is a [SELECT]
24d60 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 statement and t
24d70 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 he Nth column of
24d80 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 the.** returned
24d90 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 result set of t
24da0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 hat [SELECT] is
24db0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 a table column (
24dc0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 not an.** expres
24dd0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 sion or subquery
24de0 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 ) then the decla
24df0 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 red type of the
24e00 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 table.** column
24e10 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66 is returned. If
24e20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
24e30 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
24e40 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 t is an.** expre
24e50 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 ssion or subquer
24e60 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 y, then a NULL p
24e70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e ointer is return
24e80 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 ed..** The retur
24e90 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c ned string is al
24ea0 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 ways UTF-8 encod
24eb0 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 ed. {END}.**.**
24ec0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 For example, giv
24ed0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
24ee0 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 schema:.**.** CR
24ef0 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 EATE TABLE t1(c1
24f00 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a VARIANT);.**.**
24f10 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 and the followi
24f20 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 ng statement to
24f30 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a be compiled:.**.
24f40 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 ** SELECT c1 + 1
24f50 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a , c1 FROM t1;.**
24f60 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
24f70 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 would return th
24f80 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e e string "VARIAN
24f90 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e T" for the secon
24fa0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 d result.** colu
24fb0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 mn (i==1), and a
24fc0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f NULL pointer fo
24fd0 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 r the first resu
24fe0 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 lt column (i==0)
24ff0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 ..**.** SQLite u
25000 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d ses dynamic run-
25010 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f time typing. So
25020 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 just because a
25030 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 column.** is dec
25040 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e lared to contain
25050 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 a particular ty
25060 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e pe does not mean
25070 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 that the.** dat
25080 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 a stored in that
25090 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 column is of th
250a0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e e declared type.
250b0 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 SQLite is.** s
250c0 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 trongly typed, b
250d0 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 ut the typing is
250e0 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 dynamic not sta
250f0 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 tic. Type.** is
25100 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
25110 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 individual valu
25120 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 es, not with the
25130 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 containers.** u
25140 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 sed to hold thos
25150 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 e values..**.**
25160 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
25170 2a 20 7b 46 31 33 37 36 31 7d 20 20 41 20 73 75 * {F13761} A su
25180 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
25190 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
251a0 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 _decltype(S,N)]
251b0 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 returns a.**
251c0 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d zero-term
251d0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
251e0 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 ing containing t
251f0 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 he declared data
25200 74 79 70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 type.**
25210 20 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 of the table c
25220 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 olumn that appea
25230 72 73 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f rs as the Nth co
25240 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 0a 2a lumn (numbered.*
25250 2a 20 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d * from
25260 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 0) of the resul
25270 74 20 73 65 74 20 74 6f 20 74 68 65 20 5b 70 72 t set to the [pr
25280 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
25290 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 ] S..**.** {F137
252a0 36 32 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 62} A successfu
252b0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
252c0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
252d0 70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 pe16(S,N)].**
252e0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 returns
252f0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
25300 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 d UTF-16 native
25310 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e byte order strin
25320 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 g.** c
25330 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65 ontaining the de
25340 63 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 20 clared datatype
25350 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c of the table col
25360 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 umn that appears
25370 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 .** as
25380 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
25390 28 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 (numbered from 0
253a0 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 ) of the result
253b0 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 set to the.**
253c0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 [prepare
253d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a d statement] S..
253e0 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 33 7d 20 20 **.** {F13763}
253f0 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 If N is less tha
25400 6e 20 30 20 6f 72 20 4e 20 69 73 20 67 72 65 61 n 0 or N is grea
25410 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 ter than or equa
25420 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 l to.**
25430 20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 the number of
25440 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 5b columns in the [
25450 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
25460 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 nt] S,.**
25470 20 20 20 20 6f 72 20 69 66 20 74 68 65 20 4e 74 or if the Nt
25480 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 h column of S is
25490 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f an expression o
254a0 72 20 73 75 62 71 75 65 72 79 20 72 61 74 68 65 r subquery rathe
254b0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 r.** t
254c0 68 61 6e 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 han a table colu
254d0 6d 6e 2c 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f mn, or if a memo
254e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 ry allocation fa
254f0 69 6c 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 ilure.**
25500 20 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 occurs during
25510 20 65 6e 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72 encoding conver
25520 73 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20 sions, then.**
25530 20 20 20 20 20 20 20 20 20 63 61 6c 6c 73 20 74 calls t
25540 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d o [sqlite3_colum
25550 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d n_decltype(S,N)]
25560 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
25570 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
25580 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 _decltype16(S,N)
25590 5d 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a ] return NULL..*
255a0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 /.const char *sq
255b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 lite3_column_dec
255c0 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 ltype(sqlite3_st
255d0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
255e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
255f0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 lumn_decltype16(
25600 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
25610 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
25620 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e REF: Evaluate An
25630 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b SQL Statement {
25640 46 31 33 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 66 F13200}.**.** Af
25650 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 ter a [prepared
25660 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 statement] has b
25670 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 een prepared usi
25680 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 ng either.** [sq
25690 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
256a0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
256b0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 prepare16_v2()]
256c0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 or one of the le
256d0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 gacy.** interfac
256e0 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 es [sqlite3_prep
256f0 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 are()] or [sqlit
25700 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c e3_prepare16()],
25710 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a this function.*
25720 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 * must be called
25730 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
25740 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 es to evaluate t
25750 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a he statement..**
25760 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 .** The details
25770 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 of the behavior
25780 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 of the sqlite3_s
25790 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 tep() interface
257a0 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 depend.** on whe
257b0 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 ther the stateme
257c0 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 nt was prepared
257d0 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 using the newer
257e0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a "v2" interface.*
257f0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
25800 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
25810 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
25820 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 v2()] or the old
25830 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 er legacy.** int
25840 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f erface [sqlite3_
25850 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b prepare()] and [
25860 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
25870 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 6()]. The use o
25880 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 f the.** new "v2
25890 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 " interface is r
258a0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e ecommended for n
258b0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ew applications
258c0 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a but the legacy.*
258d0 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c * interface will
258e0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 continue to be
258f0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a supported..**.**
25900 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 In the legacy i
25910 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 nterface, the re
25920 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 turn value will
25930 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 be either [SQLIT
25940 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c E_BUSY],.** [SQL
25950 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 ITE_DONE], [SQLI
25960 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 TE_ROW], [SQLITE
25970 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c _ERROR], or [SQL
25980 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 ITE_MISUSE]..**
25990 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e With the "v2" in
259a0 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 terface, any of
259b0 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c the other [resul
259c0 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b t codes] or.** [
259d0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
259e0 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 codes] might be
259f0 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c returned as well
25a00 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ..**.** [SQLITE_
25a10 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 BUSY] means that
25a20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e the database en
25a30 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 gine was unable
25a40 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a to acquire the.*
25a50 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 * database locks
25a60 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 it needs to do
25a70 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 its job. If the
25a80 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 statement is a
25a90 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f [COMMIT].** or o
25aa0 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 ccurs outside of
25ab0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 an explicit tra
25ac0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 nsaction, then y
25ad0 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 ou can retry the
25ae0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 .** statement.
25af0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 If the statement
25b00 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 is not a [COMMI
25b10 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 T] and occurs wi
25b20 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 thin a.** explic
25b30 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 it transaction t
25b40 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 hen you should r
25b50 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e ollback the tran
25b60 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a saction before.*
25b70 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a * continuing..**
25b80 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 .** [SQLITE_DONE
25b90 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
25ba0 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 statement has f
25bb0 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e inished executin
25bc0 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c g.** successfull
25bd0 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 y. sqlite3_step
25be0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 () should not be
25bf0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e called again on
25c00 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a this virtual.**
25c10 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 machine without
25c20 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b first calling [
25c30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
25c40 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 to reset the vi
25c50 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 rtual.** machine
25c60 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 back to its ini
25c70 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a tial state..**.*
25c80 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 * If the SQL sta
25c90 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 tement being exe
25ca0 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e cuted returns an
25cb0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 y data, then [SQ
25cc0 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 LITE_ROW].** is
25cd0 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 returned each ti
25ce0 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 me a new row of
25cf0 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f data is ready fo
25d00 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 r processing by
25d10 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 the.** caller. T
25d20 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 he values may be
25d30 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 accessed using
25d40 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 the [column acce
25d50 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a ss functions]..*
25d60 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
25d70 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e is called again
25d80 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 to retrieve the
25d90 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 next row of dat
25da0 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 a..**.** [SQLITE
25db0 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 _ERROR] means th
25dc0 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 at a run-time er
25dd0 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 ror (such as a c
25de0 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f onstraint.** vio
25df0 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 lation) has occu
25e00 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 rred. sqlite3_s
25e10 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 tep() should not
25e20 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e be called again
25e30 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d on.** the VM. M
25e40 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 ore information
25e50 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 may be found by
25e60 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
25e70 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 _errmsg()]..** W
25e80 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 ith the legacy i
25e90 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 nterface, a more
25ea0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 specific error
25eb0 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c code (for exampl
25ec0 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e e,.** [SQLITE_IN
25ed0 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 TERRUPT], [SQLIT
25ee0 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 E_SCHEMA], [SQLI
25ef0 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 TE_CORRUPT], and
25f00 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 so forth).** ca
25f10 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 n be obtained by
25f20 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
25f30 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 3_reset()] on th
25f40 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
25f50 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 tatement]. In t
25f60 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
25f70 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 e,.** the more s
25f80 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f pecific error co
25f90 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 de is returned d
25fa0 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 irectly by sqlit
25fb0 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a e3_step()..**.**
25fc0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
25fd0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
25fe0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 this routine was
25ff0 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 called inapprop
26000 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 riately..** Perh
26010 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 aps it was calle
26020 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 d on a [prepared
26030 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
26040 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 has.** already
26050 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 been [sqlite3_fi
26060 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a nalize | finaliz
26070 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 ed] or on one th
26080 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f at had.** previo
26090 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 usly returned [S
260a0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 QLITE_ERROR] or
260b0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 [SQLITE_DONE].
260c0 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 Or it could.** b
260d0 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 e the case that
260e0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
260f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
26100 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 being used by tw
26110 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 o or.** more thr
26120 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 eads at the same
26130 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e moment in time.
26140 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 .**.** <b>Goofy
26150 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a Interface Alert:
26160 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 </b> In the lega
26170 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 cy interface, th
26180 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 e sqlite3_step()
26190 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 .** API always r
261a0 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 eturns a generic
261b0 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 error code, [SQ
261c0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c LITE_ERROR], fol
261d0 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 lowing any.** er
261e0 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b ror other than [
261f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 SQLITE_BUSY] and
26200 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
26210 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c . You must call
26220 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
26230 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 et()] or [sqlite
26240 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 3_finalize()] in
26250 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f order to find o
26260 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 ne of the.** spe
26270 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 cific [error cod
26280 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 es] that better
26290 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 describes the er
262a0 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 ror..** We admit
262b0 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 that this is a
262c0 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 goofy design. T
262d0 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 he problem has b
262e0 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 een fixed.** wit
262f0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 h the "v2" inter
26300 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 face. If you pr
26310 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 epare all of you
26320 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 r SQL statements
26330 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 .** using either
26340 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
26350 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 e_v2()] or [sqli
26360 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
26370 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f ()] instead.** o
26380 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 f the legacy [sq
26390 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
263a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 and [sqlite3_pr
263b0 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 epare16()] inter
263c0 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 faces,.** then t
263d0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 he more specific
263e0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 [error codes] a
263f0 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 re returned dire
26400 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 ctly.** by sqlit
26410 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 e3_step(). The
26420 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 use of the "v2"
26430 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 interface is rec
26440 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 ommended..**.**
26450 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
26460 2a 20 7b 46 31 33 32 30 32 7d 20 20 49 66 20 74 * {F13202} If t
26470 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
26480 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 61 tement] S is rea
26490 64 79 20 74 6f 20 62 65 20 72 75 6e 2c 20 74 68 dy to be run, th
264a0 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 en.**
264b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
264c0 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61 74 20 ] advances that
264d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
264e0 6e 74 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 nt until.**
264f0 20 20 20 20 20 20 63 6f 6d 70 6c 65 74 69 6f 6e completion
26500 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69 73 20 or until it is
26510 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 20 ready to return
26520 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 another row of t
26530 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 he.**
26540 72 65 73 75 6c 74 20 73 65 74 2c 20 6f 72 20 75 result set, or u
26550 6e 74 69 6c 20 61 6e 20 5b 73 71 6c 69 74 65 33 ntil an [sqlite3
26560 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 _interrupt | int
26570 65 72 72 75 70 74 5d 0a 2a 2a 20 20 20 20 20 20 errupt].**
26580 20 20 20 20 20 6f 72 20 61 20 72 75 6e 2d 74 69 or a run-ti
26590 6d 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e me error occurs.
265a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 34 7d 20 .**.** {F15304}
265b0 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 When a call to
265c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
265d0 5d 20 63 61 75 73 65 73 20 74 68 65 20 5b 70 72 ] causes the [pr
265e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
265f0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 53 ].** S
26600 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c to run to compl
26610 65 74 69 6f 6e 2c 20 74 68 65 20 66 75 6e 63 74 etion, the funct
26620 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ion returns [SQL
26630 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a ITE_DONE]..**.**
26640 20 7b 46 31 35 33 30 36 7d 20 20 57 68 65 6e 20 {F15306} When
26650 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 a call to [sqlit
26660 65 33 5f 73 74 65 70 28 53 29 5d 20 73 74 6f 70 e3_step(S)] stop
26670 73 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 s because it is
26680 72 65 61 64 79 20 74 6f 0a 2a 2a 20 20 20 20 20 ready to.**
26690 20 20 20 20 20 20 72 65 74 75 72 6e 20 61 6e 6f return ano
266a0 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 20 ther row of the
266b0 72 65 73 75 6c 74 20 73 65 74 2c 20 69 74 20 72 result set, it r
266c0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 eturns [SQLITE_R
266d0 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 OW]..**.** {F153
266e0 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20 74 08} If a call t
266f0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
26700 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 S)] encounters a
26710 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b n.** [
26720 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
26730 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 6f t | interrupt] o
26740 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 r a run-time err
26750 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or,.**
26760 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 61 it returns an a
26770 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 ppropriate error
26780 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e 6f code that is no
26790 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 t one of.**
267a0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b [SQLITE_OK
267b0 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c ], [SQLITE_ROW],
267c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 or [SQLITE_DONE
267d0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 31 30 ]..**.** {F15310
267e0 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 } If an [sqlite
267f0 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 3_interrupt | in
26800 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75 terrupt] or a ru
26810 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 n-time error.**
26820 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 occurs
26830 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 during a call t
26840 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
26850 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 S)].**
26860 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72 65 64 for a [prepared
26870 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 63 72 statement] S cr
26880 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 eated using.**
26890 20 20 20 20 20 20 20 20 20 6c 65 67 61 63 79 20 legacy
268a0 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 interfaces [sqli
268b0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f te3_prepare()] o
268c0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b r.** [
268d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
268e0 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6()], then the f
268f0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
26900 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 either.**
26910 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f [SQLITE_ERRO
26920 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 R], [SQLITE_BUSY
26930 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 ], or [SQLITE_MI
26940 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 SUSE]..*/.int sq
26950 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 lite3_step(sqlit
26960 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
26970 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
26980 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
26990 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b 46 a result set {F
269a0 31 33 37 37 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 13770}.**.** Ret
269b0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
269c0 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 of values in the
269d0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 current row of
269e0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a the result set..
269f0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
26a00 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 31 7d :.**.** {F13771}
26a10 20 20 41 66 74 65 72 20 61 20 63 61 6c 6c 20 74 After a call t
26a20 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
26a30 53 29 5d 20 74 68 61 74 20 72 65 74 75 72 6e 73 S)] that returns
26a40 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 0a 2a [SQLITE_ROW],.*
26a50 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 * the
26a60 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f [sqlite3_data_co
26a70 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 20 unt(S)] routine
26a80 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 will return the
26a90 73 61 6d 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 same value.**
26aa0 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20 5b as the [
26ab0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
26ac0 6f 75 6e 74 28 53 29 5d 20 66 75 6e 63 74 69 6f ount(S)] functio
26ad0 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 32 n..**.** {F13772
26ae0 7d 20 20 41 66 74 65 72 20 5b 73 71 6c 69 74 65 } After [sqlite
26af0 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 72 3_step(S)] has r
26b00 65 74 75 72 6e 65 64 20 61 6e 79 20 76 61 6c 75 eturned any valu
26b10 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 e other than.**
26b20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 [SQLIT
26b30 45 5f 52 4f 57 5d 20 6f 72 20 62 65 66 6f 72 65 E_ROW] or before
26b40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
26b50 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c )] has been call
26b60 65 64 20 6f 6e 20 74 68 65 0a 2a 2a 20 20 20 20 ed on the.**
26b70 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 [prepared
26b80 20 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72 20 statement] for
26b90 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 the first time s
26ba0 69 6e 63 65 20 69 74 20 77 61 73 0a 2a 2a 20 20 ince it was.**
26bb0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
26bc0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 3_prepare | prep
26bd0 61 72 65 64 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ared] or [sqlite
26be0 33 5f 72 65 73 65 74 20 7c 20 72 65 73 65 74 5d 3_reset | reset]
26bf0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 ,.** t
26c00 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 he [sqlite3_data
26c10 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 _count(S)] routi
26c20 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e ne returns zero.
26c30 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
26c40 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 data_count(sqlit
26c50 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
26c60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
26c70 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 : Fundamental Da
26c80 74 61 74 79 70 65 73 20 7b 46 31 30 32 36 35 7d tatypes {F10265}
26c90 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 .** KEYWORDS: SQ
26ca0 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 LITE_TEXT.**.**
26cb0 7b 46 31 30 32 36 36 7d 20 45 76 65 72 79 20 76 {F10266} Every v
26cc0 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 alue in SQLite h
26cd0 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 as one of five f
26ce0 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 undamental datat
26cf0 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ypes:.**.** <ul>
26d00 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 .** <li> 64-bit
26d10 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a signed integer.*
26d20 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 * <li> 64-bit IE
26d30 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e EE floating poin
26d40 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e t number.** <li>
26d50 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 string.** <li>
26d60 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c BLOB.** <li> NUL
26d70 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d L.** </ul> {END}
26d80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
26d90 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 stants are codes
26da0 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f for each of tho
26db0 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 se types..**.**
26dc0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 Note that the SQ
26dd0 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 LITE_TEXT consta
26de0 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 nt was also used
26df0 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 in SQLite versi
26e00 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f on 2.** for a co
26e10 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 mpletely differe
26e20 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 nt meaning. Sof
26e30 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 tware that links
26e40 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a against both.**
26e50 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
26e60 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 2 and SQLite ver
26e70 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 sion 3 should us
26e80 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 e SQLITE3_TEXT,
26e90 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 not.** SQLITE_TE
26ea0 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 XT..*/.#define S
26eb0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 QLITE_INTEGER 1
26ec0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
26ed0 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 FLOAT 2.#defi
26ee0 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 ne SQLITE_BLOB
26ef0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
26f00 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 ITE_NULL 5.#
26f10 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 ifdef SQLITE_TEX
26f20 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 T.# undef SQLITE
26f30 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 _TEXT.#else.# de
26f40 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 fine SQLITE_TEXT
26f50 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 3.#endif.#d
26f60 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 efine SQLITE3_TE
26f70 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 XT 3../*.**
26f80 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 CAPI3REF: Result
26f90 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 Values From A Q
26fa0 75 65 72 79 20 7b 46 31 33 38 30 30 7d 0a 2a 2a uery {F13800}.**
26fb0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 KEYWORDS: {colu
26fc0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 mn access functi
26fd0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ons}.**.** These
26fe0 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 routines form t
26ff0 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 he "result set q
27000 75 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e uery" interface.
27010 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
27020 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 tines return inf
27030 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 ormation about a
27040 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f single column o
27050 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a f the current.**
27060 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 result row of a
27070 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 query. In ever
27080 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 y case the first
27090 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 argument is a p
270a0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ointer.** to the
270b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
270c0 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 ment] that is be
270d0 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 ing evaluated (t
270e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
270f0 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 *].** that was r
27100 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 eturned from [sq
27110 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
27120 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 ()] or one of it
27130 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 s variants).** a
27140 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 nd the second ar
27150 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e gument is the in
27160 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d dex of the colum
27170 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f n for which info
27180 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c rmation.** shoul
27190 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 d be returned.
271a0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c The leftmost col
271b0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c umn of the resul
271c0 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e t set has the in
271d0 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 dex 0..**.** If
271e0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
271f0 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 t does not curre
27200 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 ntly point to a
27210 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 valid row, or if
27220 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 the.** column i
27230 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 ndex is out of r
27240 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 ange, the result
27250 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
27260 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
27270 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c may only be cal
27280 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 led when the mos
27290 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
272a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
272b0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 p()] has returne
272c0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 d [SQLITE_ROW] a
272d0 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 nd neither.** [s
272e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
272f0 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e nor [sqlite3_fin
27300 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 alize()] have be
27310 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 en called subseq
27320 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e uently..** If an
27330 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 y of these routi
27340 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 nes are called a
27350 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 fter [sqlite3_re
27360 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 set()] or.** [sq
27370 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
27380 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 ] or after [sqli
27390 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 te3_step()] has
273a0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 returned.** some
273b0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e thing other than
273c0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 [SQLITE_ROW], t
273d0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 he results are u
273e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 ndefined..** If
273f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
27400 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 or [sqlite3_res
27410 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 et()] or [sqlite
27420 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 3_finalize()].**
27430 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d are called from
27440 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 a different thr
27450 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 ead while any of
27460 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a these routines.
27470 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 ** are pending,
27480 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 then the results
27490 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
274a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
274b0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 3_column_type()
274c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
274d0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 the.** [SQLITE_I
274e0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 NTEGER | datatyp
274f0 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 e code] for the
27500 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 initial data typ
27510 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 e.** of the resu
27520 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 lt column. The
27530 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 returned value i
27540 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 s one of [SQLITE
27550 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 _INTEGER],.** [S
27560 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 QLITE_FLOAT], [S
27570 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 QLITE_TEXT], [SQ
27580 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b LITE_BLOB], or [
27590 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 SQLITE_NULL]. T
275a0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 he value.** retu
275b0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
275c0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 column_type() is
275d0 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c only meaningful
275e0 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 if no type.** c
275f0 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 onversions have
27600 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 occurred as desc
27610 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 ribed below. Af
27620 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 ter a type conve
27630 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 rsion,.** the va
27640 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
27650 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
27660 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e ype() is undefin
27670 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 ed. Future.** v
27680 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
27690 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 e may change the
276a0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c behavior of sql
276b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
276c0 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 ().** following
276d0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f a type conversio
276e0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 n..**.** If the
276f0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 result is a BLOB
27700 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 or UTF-8 string
27710 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 then the sqlite
27720 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
27730 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 .** routine retu
27740 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
27750 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 f bytes in that
27760 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a BLOB or string..
27770 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 ** If the result
27780 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 is a UTF-16 str
27790 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 ing, then sqlite
277a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
277b0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 converts.** the
277c0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 string to UTF-8
277d0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e and then return
277e0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
277f0 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 bytes..** If the
27800 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d result is a num
27810 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 eric value then
27820 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
27830 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b ytes() uses.** [
27840 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
27850 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 ()] to convert t
27860 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 hat value to a U
27870 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 TF-8 string and
27880 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e returns.** the n
27890 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
278a0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a n that string..*
278b0 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 * The value retu
278c0 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e rned does not in
278d0 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 clude the zero t
278e0 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 erminator at the
278f0 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 end.** of the s
27900 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 tring. For clar
27910 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 ity: the value r
27920 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e eturned is the n
27930 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 umber of.** byte
27940 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c s in the string,
27950 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 not the number
27960 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a of characters..*
27970 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 *.** Strings ret
27980 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
27990 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 _column_text() a
279a0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
279b0 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 n_text16(),.** e
279c0 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 ven empty string
279d0 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 s, are always ze
279e0 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 ro terminated.
279f0 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 The return.** va
27a00 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 lue from sqlite3
27a10 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 _column_blob() f
27a20 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 or a zero-length
27a30 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 BLOB is an arbi
27a40 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 trary.** pointer
27a50 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 , possibly even
27a60 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
27a70 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
27a80 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
27a90 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 () routine is si
27aa0 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 milar to sqlite3
27ab0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a _column_bytes().
27ac0 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 ** but leaves th
27ad0 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d e result in UTF-
27ae0 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 16 in native byt
27af0 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 e order instead
27b00 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 of UTF-8..** The
27b10 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
27b20 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 is not included
27b30 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a in this count..
27b40 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 **.** The object
27b50 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 returned by [sq
27b60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
27b70 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b ue()] is an.** [
27b80 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
27b90 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
27ba0 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 t. An unprotect
27bb0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
27bc0 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f object.** may o
27bd0 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 nly be used with
27be0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 [sqlite3_bind_v
27bf0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c alue()] and [sql
27c00 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
27c10 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 e()]..** If the
27c20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
27c30 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
27c40 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a ct returned by.*
27c50 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
27c60 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 n_value()] is us
27c70 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 ed in any other
27c80 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 way, including c
27c90 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 alls.** to routi
27ca0 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 nes like [sqlite
27cb0 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 3_value_int()],
27cc0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
27cd0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 ext()],.** or [s
27ce0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 qlite3_value_byt
27cf0 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 es()], then the
27d00 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 behavior is unde
27d10 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 fined..**.** The
27d20 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 se routines atte
27d30 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 mpt to convert t
27d40 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 he value where a
27d50 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 ppropriate. For
27d60 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 .** example, if
27d70 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 the internal rep
27d80 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 resentation is F
27d90 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 LOAT and a text
27da0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 result.** is req
27db0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 uested, [sqlite3
27dc0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 _snprintf()] is
27dd0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 used internally
27de0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a to perform the.*
27df0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 * conversion aut
27e00 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 omatically. The
27e10 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 following table
27e20 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e details the con
27e30 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 versions.** that
27e40 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a are applied:.**
27e50 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
27e60 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 .** <table borde
27e70 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 r="1">.** <tr><t
27e80 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 h> Internal<br>T
27e90 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 ype <th> Request
27ea0 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 ed<br>Type <th>
27eb0 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a Conversion.**.*
27ec0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
27ed0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
27ee0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
27ef0 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 s 0.** <tr><td>
27f00 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 NULL <td> F
27f10 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 LOAT <td> Res
27f20 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 ult is 0.0.** <t
27f30 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
27f40 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
27f50 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 td> Result is NU
27f60 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 LL pointer.** <t
27f70 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
27f80 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
27f90 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 td> Result is NU
27fa0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 LL pointer.** <t
27fb0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 r><td> INTEGER
27fc0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
27fd0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d td> Convert from
27fe0 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 integer to floa
27ff0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e t.** <tr><td> IN
28000 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 TEGER <td> TE
28010 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 XT <td> ASCII
28020 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 rendering of th
28030 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 e integer.** <tr
28040 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c ><td> INTEGER <
28050 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
28060 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 d> Same as INTEG
28070 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e ER->TEXT.** <tr>
28080 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 <td> FLOAT <t
28090 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
280a0 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 > Convert from f
280b0 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a loat to integer.
280c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f ** <tr><td> FLO
280d0 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 AT <td> TEXT
280e0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 <td> ASCII r
280f0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 endering of the
28100 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 float.** <tr><td
28110 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
28120 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 BLOB <td> S
28130 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 ame as FLOAT->TE
28140 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 XT.** <tr><td>
28150 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 TEXT <td> INT
28160 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 EGER <td> Use
28170 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 atoi().** <tr><t
28180 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
28190 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
281a0 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 Use atof().** <t
281b0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
281c0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
281d0 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a td> No change.**
281e0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 <tr><td> BLOB
281f0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 <td> INTEGER
28200 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 <td> Convert t
28210 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 o TEXT then use
28220 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 atoi().** <tr><t
28230 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e d> BLOB <td>
28240 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
28250 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 Convert to TEXT
28260 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a then use atof().
28270 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f ** <tr><td> BLO
28280 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 B <td> TEXT
28290 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a <td> Add a z
282a0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 ero terminator i
282b0 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 f needed.** </ta
282c0 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 ble>.** </blockq
282d0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 uote>.**.** The
282e0 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 table above make
282f0 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 s reference to s
28300 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
28310 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 y functions atoi
28320 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 ().** and atof()
28330 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e . SQLite does n
28340 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 ot really use th
28350 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 ese functions.
28360 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 It has its.** ow
28370 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 n equivalent int
28380 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 ernal routines.
28390 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 The atoi() and
283a0 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 atof() names are
283b0 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 .** used in the
283c0 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 table for brevit
283d0 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 y and because th
283e0 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 ey are familiar
283f0 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f to most.** C pro
28400 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 grammers..**.**
28410 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 Note that when t
28420 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 ype conversions
28430 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 occur, pointers
28440 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f returned by prio
28450 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 r.** calls to sq
28460 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
28470 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c b(), sqlite3_col
28480 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f umn_text(), and/
28490 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f or.** sqlite3_co
284a0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 lumn_text16() ma
284b0 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 y be invalidated
284c0 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 ..** Type conver
284d0 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 sions and pointe
284e0 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 r invalidations
284f0 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 might occur.** i
28500 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 n the following
28510 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c cases:.**.** <ul
28520 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e >.** <li> The in
28530 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 itial content is
28540 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 a BLOB and sqli
28550 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
28560 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c ) or.** sql
28570 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
28580 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 16() is called.
28590 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 A zero-terminat
285a0 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 or might.**
285b0 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 need to be adde
285c0 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e d to the string.
285d0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 </li>.** <li> Th
285e0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
285f0 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 t is UTF-8 text
28600 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
28610 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a mn_bytes16() or.
28620 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f ** sqlite3_
28630 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
28640 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 is called. The
28650 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 content must be
28660 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 converted.**
28670 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 to UTF-16.</li
28680 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e >.** <li> The in
28690 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 itial content is
286a0 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 UTF-16 text and
286b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
286c0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 bytes() or.**
286d0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d sqlite3_colum
286e0 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c n_text() is call
286f0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 ed. The content
28700 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 must be convert
28710 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 ed.** to UT
28720 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 F-8.</li>.** </u
28730 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 l>.**.** Convers
28740 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 ions between UTF
28750 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 -16be and UTF-16
28760 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f le are always do
28770 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 ne in place and
28780 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 do.** not invali
28790 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 date a prior poi
287a0 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 nter, though of
287b0 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 course the conte
287c0 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 nt of the buffer
287d0 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 .** that the pri
287e0 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 or pointer point
287f0 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 s to will have b
28800 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f een modified. O
28810 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 ther kinds.** of
28820 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 conversion are
28830 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 done in place wh
28840 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c en it is possibl
28850 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 e, but sometimes
28860 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 they.** are not
28870 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e possible and in
28880 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 those cases pri
28890 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 or pointers are
288a0 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a invalidated..**.
288b0 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e ** The safest an
288c0 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d d easiest to rem
288d0 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 ember policy is
288e0 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 to invoke these
288f0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f routines.** in o
28900 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
28910 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 ing ways:.**.**
28920 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c <ul>.** <li>sql
28930 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
28940 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 () followed by s
28950 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
28960 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c tes()</li>.** <
28970 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d li>sqlite3_colum
28980 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 n_blob() followe
28990 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
289a0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e umn_bytes()</li>
289b0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 .** <li>sqlite3
289c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
289d0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c followed by sql
289e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
289f0 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f s16()</li>.** </
28a00 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 ul>.**.** In oth
28a10 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 er words, you sh
28a20 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 ould call sqlite
28a30 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 3_column_text(),
28a40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
28a50 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 mn_blob(), or sq
28a60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
28a70 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 t16() first to f
28a80 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a orce the result.
28a90 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 ** into the desi
28aa0 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e red format, then
28ab0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
28ac0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f column_bytes() o
28ad0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c r.** sqlite3_col
28ae0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f umn_bytes16() to
28af0 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f find the size o
28b00 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 f the result. D
28b10 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a o not mix calls.
28b20 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ** to sqlite3_co
28b30 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 lumn_text() or s
28b40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
28b50 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 ob() with calls
28b60 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f to.** sqlite3_co
28b70 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 lumn_bytes16(),
28b80 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 and do not mix c
28b90 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
28ba0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a column_text16().
28bb0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f ** with calls to
28bc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
28bd0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 bytes()..**.** T
28be0 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 he pointers retu
28bf0 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 rned are valid u
28c00 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 ntil a type conv
28c10 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 ersion occurs as
28c20 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 .** described ab
28c30 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 ove, or until [s
28c40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f qlite3_step()] o
28c50 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
28c60 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
28c70 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 e3_finalize()] i
28c80 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d s called. The m
28c90 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 emory space used
28ca0 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 to hold strings
28cb0 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 .** and BLOBs is
28cc0 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 freed automatic
28cd0 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 ally. Do <b>not
28ce0 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f </b> pass the po
28cf0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a inters returned.
28d00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
28d10 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c mn_blob()], [sql
28d20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
28d30 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a ()], etc. into.*
28d40 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 * [sqlite3_free(
28d50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d )]..**.** If a m
28d60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
28d70 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 error occurs du
28d80 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 ring the evaluat
28d90 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 ion of any.** of
28da0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c these routines,
28db0 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 a default value
28dc0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 is returned. T
28dd0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 he default value
28de0 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 .** is either th
28df0 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 e integer 0, the
28e00 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
28e10 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 number 0.0, or a
28e20 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 NULL.** pointer
28e30 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 . Subsequent ca
28e40 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
28e50 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 errcode()] will
28e60 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 return.** [SQLIT
28e70 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 E_NOMEM]..**.**
28e80 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
28e90 2a 20 7b 46 31 33 38 30 33 7d 20 54 68 65 20 5b * {F13803} The [
28ea0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
28eb0 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 lob(S,N)] interf
28ec0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 ace converts the
28ed0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 .** Nth
28ee0 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 column in the c
28ef0 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 urrent row of th
28f00 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 e result set for
28f10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
28f20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
28f30 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 42 ment] S into a B
28f40 4c 4f 42 20 61 6e 64 20 74 68 65 6e 20 72 65 74 LOB and then ret
28f50 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 urns a.**
28f60 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 pointer to th
28f70 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 e converted valu
28f80 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 36 e..**.** {F13806
28f90 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
28fa0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29 olumn_bytes(S,N)
28fb0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
28fc0 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 rns the.**
28fd0 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 number of by
28fe0 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20 tes in the BLOB
28ff0 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 or string (exclu
29000 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 sive of the.**
29010 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 zero ter
29020 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 minator on the s
29030 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 tring) that was
29040 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a returned by the.
29050 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 ** most
29060 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 recent call to
29070 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
29080 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a blob(S,N)] or.**
29090 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
290a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 e3_column_text(S
290b0 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 ,N)]..**.** {F13
290c0 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 809} The [sqlite
290d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
290e0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 (S,N)] interface
290f0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 returns the.**
29100 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 number
29110 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 of bytes in the
29120 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 string (exclusiv
29130 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 e of the.**
29140 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e zero termin
29150 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 ator on the stri
29160 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 ng) that was ret
29170 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 urned by the.**
29180 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 most re
29190 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 cent call to [sq
291a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
291b0 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a t16(S,N)]..**.**
291c0 20 7b 46 31 33 38 31 32 7d 20 54 68 65 20 5b 73 {F13812} The [s
291d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f qlite3_column_do
291e0 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 uble(S,N)] inter
291f0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 face converts th
29200 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 e.** Nt
29210 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 h column in the
29220 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 current row of t
29230 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f he result set fo
29240 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 r the.**
29250 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 [prepared stat
29260 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 ement] S into a
29270 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 floating point v
29280 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 alue and.**
29290 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 returns a c
292a0 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 opy of that valu
292b0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 35 e..**.** {F13815
292c0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
292d0 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 olumn_int(S,N)]
292e0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 interface conver
292f0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ts the.**
29300 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e Nth column in
29310 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 the current row
29320 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
29330 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 et for the.**
29340 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 [prepared
29350 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e statement] S in
29360 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e to a 64-bit sign
29370 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a ed integer and.*
29380 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 * retur
29390 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20 ns the lower 32
293a0 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74 bits of that int
293b0 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 eger..**.** {F13
293c0 38 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 818} The [sqlite
293d0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 3_column_int64(S
293e0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 ,N)] interface c
293f0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 onverts the.**
29400 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 Nth colu
29410 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e mn in the curren
29420 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 t row of the res
29430 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a ult set for the.
29440 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 ** [pre
29450 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
29460 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 S into a 64-bit
29470 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 signed integer
29480 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 and.**
29490 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f returns a copy o
294a0 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a f that integer..
294b0 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 31 7d 20 54 **.** {F13821} T
294c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 he [sqlite3_colu
294d0 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69 6e mn_text(S,N)] in
294e0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 terface converts
294f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
29500 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 Nth column in t
29510 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f he current row o
29520 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
29530 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 for.**
29540 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
29550 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f tatement] S into
29560 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
29570 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 ed UTF-8.**
29580 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 string and
29590 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
295a0 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 r to that string
295b0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 34 7d ..**.** {F13824}
295c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f The [sqlite3_co
295d0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 lumn_text16(S,N)
295e0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 ] interface conv
295f0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 erts the.**
29600 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 Nth column
29610 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 in the current r
29620 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ow of the result
29630 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 set for the.**
29640 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 [prepar
29650 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
29660 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d into a zero-term
29670 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a inated 2-byte.**
29680 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 aligne
29690 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 d UTF-16 native
296a0 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e byte order strin
296b0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a g and returns.**
296c0 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e a poin
296d0 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 ter to that stri
296e0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 ng..**.** {F1382
296f0 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 7} The [sqlite3_
29700 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 column_type(S,N)
29710 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
29720 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 rns.**
29730 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e one of [SQLITE_N
29740 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e ULL], [SQLITE_IN
29750 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f TEGER], [SQLITE_
29760 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 FLOAT],.**
29770 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 [SQLITE_TEXT
29780 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c ], or [SQLITE_BL
29790 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 OB] as appropria
297a0 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 te for.**
297b0 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d the Nth colum
297c0 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 n in the current
297d0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 row of the resu
297e0 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 lt set for.**
297f0 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 the [prep
29800 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
29810 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 33 30 S..**.** {F13830
29820 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
29830 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 olumn_value(S,N)
29840 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
29850 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 rns a.**
29860 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 pointer to an
29870 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
29880 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
29890 63 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 ct for the.**
298a0 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d Nth colum
298b0 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 n in the current
298c0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 row of the resu
298d0 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 lt set for.**
298e0 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 the [prep
298f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
29900 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 S..*/.const void
29910 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
29920 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 _blob(sqlite3_st
29930 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
29940 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
29950 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 mn_bytes(sqlite3
29960 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
29970 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
29980 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 olumn_bytes16(sq
29990 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
299a0 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 iCol);.double s
299b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f qlite3_column_do
299c0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d uble(sqlite3_stm
299d0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 t*, int iCol);.i
299e0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
299f0 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 n_int(sqlite3_st
29a00 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
29a10 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
29a20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 lite3_column_int
29a30 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 64(sqlite3_stmt*
29a40 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e , int iCol);.con
29a50 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 st unsigned char
29a60 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
29a70 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 _text(sqlite3_st
29a80 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
29a90 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
29aa0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
29ab0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
29ac0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 int iCol);.int
29ad0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
29ae0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ype(sqlite3_stmt
29af0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 *, int iCol);.sq
29b00 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c lite3_value *sql
29b10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
29b20 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
29b30 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a int iCol);../*.
29b40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 ** CAPI3REF: Des
29b50 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 troy A Prepared
29b60 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
29b70 20 7b 46 31 33 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 {F13300}.**.**
29b80 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 The sqlite3_fina
29b90 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 lize() function
29ba0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c is called to del
29bb0 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 ete a [prepared
29bc0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 statement]..** I
29bd0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 f the statement
29be0 77 61 73 20 65 78 65 63 75 74 65 64 20 73 75 63 was executed suc
29bf0 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 cessfully or not
29c00 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c executed at all
29c10 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 , then.** SQLITE
29c20 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e _OK is returned.
29c30 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 If execution of
29c40 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 the statement f
29c50 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a ailed then an.**
29c60 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 [error code] or
29c70 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 [extended error
29c80 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
29c90 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 ed..**.** This r
29ca0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 outine can be ca
29cb0 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e lled at any poin
29cc0 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 t during the exe
29cd0 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a cution of the.**
29ce0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
29cf0 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76 ment]. If the v
29d00 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 irtual machine h
29d10 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 as not.** comple
29d20 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 ted execution wh
29d30 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 en this routine
29d40 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 is called, that
29d50 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 is like.** encou
29d60 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 ntering an error
29d70 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f or an [sqlite3_
29d80 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 interrupt | inte
29d90 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d rrupt]..** Incom
29da0 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 plete updates ma
29db0 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b y be rolled back
29dc0 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e and transaction
29dd0 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 s canceled,.** d
29de0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
29df0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 circumstances, a
29e00 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 nd the.** [error
29e10 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 code] returned
29e20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f will be [SQLITE_
29e30 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e ABORT]..**.** IN
29e40 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
29e50 7b 46 31 31 33 30 32 7d 20 54 68 65 20 5b 73 71 {F11302} The [sq
29e60 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 lite3_finalize(S
29e70 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73 )] interface des
29e80 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20 20 troys the.**
29e90 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 [prepared
29ea0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e 64 statement] S and
29eb0 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a releases all.**
29ec0 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 memory
29ed0 20 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75 72 and file resour
29ee0 63 65 73 20 68 65 6c 64 20 62 79 20 74 68 61 74 ces held by that
29ef0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b object..**.** {
29f00 46 31 31 33 30 34 7d 20 49 66 20 74 68 65 20 6d F11304} If the m
29f10 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 ost recent call
29f20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
29f30 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 (S)] for the.**
29f40 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 [prepar
29f50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
29f60 72 65 74 75 72 6e 65 64 20 61 6e 20 65 72 72 6f returned an erro
29f70 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 r,.** t
29f80 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e hen [sqlite3_fin
29f90 61 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 72 6e alize(S)] return
29fa0 73 20 74 68 61 74 20 73 61 6d 65 20 65 72 72 6f s that same erro
29fb0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 r..*/.int sqlite
29fc0 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 3_finalize(sqlit
29fd0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
29fe0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
29ff0 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 : Reset A Prepar
2a000 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a ed Statement Obj
2a010 65 63 74 20 7b 46 31 33 33 33 30 7d 0a 2a 2a 0a ect {F13330}.**.
2a020 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
2a030 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 eset() function
2a040 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 is called to res
2a050 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 et a [prepared s
2a060 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a tatement].** obj
2a070 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 ect back to its
2a080 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 initial state, r
2a090 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 eady to be re-ex
2a0a0 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 ecuted..** Any S
2a0b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 QL statement var
2a0c0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 iables that had
2a0d0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 values bound to
2a0e0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 them using.** th
2a0f0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
2a100 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 blob | sqlite3_b
2a110 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 ind_*() API] ret
2a120 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 ain their values
2a130 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 ..** Use [sqlite
2a140 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 3_clear_bindings
2a150 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 ()] to reset the
2a160 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a bindings..**.**
2a170 20 7b 46 31 31 33 33 32 7d 20 54 68 65 20 5b 73 {F11332} The [s
2a180 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
2a190 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 interface reset
2a1a0 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 s the [prepared
2a1b0 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 statement] S.**
2a1c0 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f back to
2a1d0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f the beginning o
2a1e0 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a f its program..*
2a1f0 2a 0a 2a 2a 20 7b 46 31 31 33 33 34 7d 20 49 66 *.** {F11334} If
2a200 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
2a210 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
2a220 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 3_step(S)] for t
2a230 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
2a240 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2a250 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b nt] S returned [
2a260 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b SQLITE_ROW] or [
2a270 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a SQLITE_DONE],.**
2a280 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 or if
2a290 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
2a2a0 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f ] has never befo
2a2b0 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f re been called o
2a2c0 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 n S,.**
2a2d0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 then [sqlite3_r
2a2e0 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 eset(S)] returns
2a2f0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a [SQLITE_OK]..**
2a300 0a 2a 2a 20 7b 46 31 31 33 33 36 7d 20 49 66 20 .** {F11336} If
2a310 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
2a320 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
2a330 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 _step(S)] for th
2a340 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 e.** [p
2a350 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2a360 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 t] S indicated a
2a370 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a n error, then.**
2a380 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
2a390 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 e3_reset(S)] ret
2a3a0 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 urns an appropri
2a3b0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ate [error code]
2a3c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 38 7d ..**.** {F11338}
2a3d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 The [sqlite3_re
2a3e0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 set(S)] interfac
2a3f0 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 e does not chang
2a400 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 e the values.**
2a410 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20 of any
2a420 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
2a430 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 ob|bindings] on
2a440 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
2a450 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 atement] S..*/.i
2a460 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 nt sqlite3_reset
2a470 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
2a480 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
2a490 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f PI3REF: Create O
2a4a0 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 r Redefine SQL F
2a4b0 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36 31 30 30 unctions {F16100
2a4c0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
2a4d0 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f function creatio
2a4e0 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b n routines}.** K
2a4f0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 EYWORDS: {applic
2a500 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
2a510 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b L function}.** K
2a520 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 EYWORDS: {applic
2a530 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
2a540 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a L functions}.**.
2a550 2a 2a 20 54 68 65 73 65 20 74 77 6f 20 66 75 6e ** These two fun
2a560 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 ctions (collecti
2a570 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 vely known as "f
2a580 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e unction creation
2a590 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 routines").** a
2a5a0 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 re used to add S
2a5b0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 QL functions or
2a5c0 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f aggregates or to
2a5d0 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 redefine the be
2a5e0 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 havior.** of exi
2a5f0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 sting SQL functi
2a600 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 ons or aggregate
2a610 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 s. The only dif
2a620 66 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 ference between
2a630 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 the.** two is th
2a640 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 at the second pa
2a650 72 61 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d rameter, the nam
2a660 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 e of the (scalar
2a670 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a ) function or.**
2a680 20 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 aggregate, is e
2a690 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 ncoded in UTF-8
2a6a0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 for sqlite3_crea
2a6b0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e te_function() an
2a6c0 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 d UTF-16.** for
2a6d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2a6e0 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a unction16()..**.
2a6f0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 ** The first par
2a700 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 ameter is the [d
2a710 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2a720 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 on] to which the
2a730 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e SQL.** function
2a740 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e is to be added.
2a750 20 20 49 66 20 61 20 73 69 6e 67 6c 65 20 70 72 If a single pr
2a760 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 ogram uses more
2a770 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 than one databas
2a780 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 e.** connection
2a790 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e internally, then
2a7a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d SQL functions m
2a7b0 75 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 ust be added ind
2a7c0 69 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 ividually to.**
2a7d0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f each database co
2a7e0 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 nnection..**.**
2a7f0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
2a800 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 eter is the name
2a810 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 of the SQL func
2a820 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 tion to be creat
2a830 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e ed or.** redefin
2a840 65 64 2e 20 20 54 68 65 20 6c 65 6e 67 74 68 20 ed. The length
2a850 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c of the name is l
2a860 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 imited to 255 by
2a870 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f tes, exclusive o
2a880 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 f.** the zero-te
2a890 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 rminator. Note
2a8a0 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 that the name le
2a8b0 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e ngth limit is in
2a8c0 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 bytes, not.** c
2a8d0 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20 haracters. Any
2a8e0 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 attempt to creat
2a8f0 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 e a function wit
2a900 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a h a longer name.
2a910 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 ** will result i
2a920 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d n [SQLITE_ERROR]
2a930 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e being returned.
2a940 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 .**.** The third
2a950 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
2a960 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 e number of argu
2a970 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 ments that the S
2a980 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a QL function or.*
2a990 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 * aggregate take
2a9a0 73 2e 20 49 66 20 74 68 69 73 20 70 61 72 61 6d s. If this param
2a9b0 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 eter is negative
2a9c0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 , then the SQL f
2a9d0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
2a9e0 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 gregate may take
2a9f0 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 any number of a
2aa00 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 rguments..**.**
2aa10 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d The fourth param
2aa20 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 eter, eTextRep,
2aa30 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a specifies what.*
2aa40 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c * [SQLITE_UTF8 |
2aa50 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 text encoding]
2aa60 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f this SQL functio
2aa70 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a n prefers for.**
2aa80 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e its parameters.
2aa90 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 Any SQL functi
2aaa0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
2aab0 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 n should be able
2aac0 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b to work.** work
2aad0 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 with UTF-8, UTF
2aae0 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 -16le, or UTF-16
2aaf0 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d be. But some im
2ab00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 plementations ma
2ab10 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 y be.** more eff
2ab20 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 icient with one
2ab30 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e encoding than an
2ab40 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c other. It is al
2ab50 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f lowed to.** invo
2ab60 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 ke sqlite3_creat
2ab70 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 e_function() or
2ab80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2ab90 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 unction16() mult
2aba0 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 iple.** times wi
2abb0 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 th the same func
2abc0 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 tion but with di
2abd0 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f fferent values o
2abe0 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 f eTextRep..** W
2abf0 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 hen multiple imp
2ac00 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 lementations of
2ac10 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
2ac20 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c n are available,
2ac30 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 SQLite.** will
2ac40 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 pick the one tha
2ac50 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c t involves the l
2ac60 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 east amount of d
2ac70 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a ata conversion..
2ac80 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f ** If there is o
2ac90 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 nly a single imp
2aca0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 lementation whic
2acb0 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 h does not care
2acc0 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 what text.** enc
2acd0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 oding is used, t
2ace0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 hen the fourth a
2acf0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 rgument should b
2ad00 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a e [SQLITE_ANY]..
2ad10 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 **.** The fifth
2ad20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 parameter is an
2ad30 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 arbitrary pointe
2ad40 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e r. The implemen
2ad50 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a tation of the.**
2ad60 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 function can ga
2ad70 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 in access to thi
2ad80 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 s pointer using
2ad90 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 [sqlite3_user_da
2ada0 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ta()]..**.** The
2adb0 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 seventh, eighth
2adc0 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d and ninth param
2add0 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 eters, xFunc, xS
2ade0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 tep and xFinal,
2adf0 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 are.** pointers
2ae00 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 to C-language fu
2ae10 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 nctions that imp
2ae20 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 lement the SQL f
2ae30 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
2ae40 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 gregate. A scala
2ae50 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 r SQL function r
2ae60 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 equires an imple
2ae70 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 mentation of the
2ae80 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 xFunc.** callba
2ae90 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f ck only, NULL po
2aea0 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 inters should be
2aeb0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 passed as the x
2aec0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a Step and xFinal.
2aed0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 ** parameters. A
2aee0 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 n aggregate SQL
2aef0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 function require
2af00 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 s an implementat
2af10 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 ion of xStep.**
2af20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e and xFinal and N
2af30 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 ULL should be pa
2af40 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 ssed for xFunc.
2af50 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 To delete an exi
2af60 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e sting.** SQL fun
2af70 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 ction or aggrega
2af80 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f te, pass NULL fo
2af90 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 r all three func
2afa0 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a tion callbacks..
2afb0 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d **.** It is perm
2afc0 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 itted to registe
2afd0 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 r multiple imple
2afe0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 mentations of th
2aff0 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 e same.** functi
2b000 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d ons with the sam
2b010 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 e name but with
2b020 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 either differing
2b030 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 numbers of.** a
2b040 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 rguments or diff
2b050 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 ering preferred
2b060 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 text encodings.
2b070 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 SQLite will use
2b080 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e .** the implemen
2b090 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 tation most clos
2b0a0 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 ely matches the
2b0b0 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 way in which the
2b0c0 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e .** SQL function
2b0d0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
2b0e0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
2b0f0 2a 20 7b 46 31 36 31 30 33 7d 20 54 68 65 20 5b * {F16103} The [
2b100 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2b110 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 69 6e 74 unction16()] int
2b120 65 72 66 61 63 65 20 62 65 68 61 76 65 73 20 65 erface behaves e
2b130 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 xactly.**
2b140 20 20 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 like [sqlite3
2b150 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2b160 28 29 5d 20 69 6e 20 65 76 65 72 79 20 77 61 79 ()] in every way
2b170 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 0a except that it.
2b180 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 ** inte
2b190 72 70 72 65 74 73 20 74 68 65 20 7a 46 75 6e 63 rprets the zFunc
2b1a0 74 69 6f 6e 4e 61 6d 65 20 61 72 67 75 6d 65 6e tionName argumen
2b1b0 74 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e t as zero-termin
2b1c0 61 74 65 64 20 55 54 46 2d 31 36 0a 2a 2a 20 20 ated UTF-16.**
2b1d0 20 20 20 20 20 20 20 20 6e 61 74 69 76 65 20 62 native b
2b1e0 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 yte order instea
2b1f0 64 20 6f 66 20 61 73 20 7a 65 72 6f 2d 74 65 72 d of as zero-ter
2b200 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a minated UTF-8..*
2b210 2a 0a 2a 2a 20 7b 46 31 36 31 30 36 7d 20 41 20 *.** {F16106} A
2b220 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 successful invoc
2b230 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 ation of.**
2b240 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 the [sqlite
2b250 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2b260 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 n(D,X,N,E,...)]
2b270 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
2b280 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ers.**
2b290 6f 72 20 72 65 70 6c 61 63 65 73 20 63 61 6c 6c or replaces call
2b2a0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69 back functions i
2b2b0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 n the [database
2b2c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a connection] D.**
2b2d0 20 20 20 20 20 20 20 20 20 20 75 73 65 64 20 74 used t
2b2e0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 o implement the
2b2f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d SQL function nam
2b300 65 64 20 58 20 77 69 74 68 20 4e 20 70 61 72 61 ed X with N para
2b310 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 meters.**
2b320 20 20 20 61 6e 64 20 68 61 76 69 6e 67 20 61 20 and having a
2b330 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 preferred text e
2b340 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a ncoding of E..**
2b350 0a 2a 2a 20 7b 46 31 36 31 30 39 7d 20 41 20 73 .** {F16109} A s
2b360 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
2b370 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 o [sqlite3_creat
2b380 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e e_function(D,X,N
2b390 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 ,E,P,F,S,L)].**
2b3a0 20 20 20 20 20 20 20 20 20 72 65 70 6c 61 63 65 replace
2b3b0 73 20 74 68 65 20 50 2c 20 46 2c 20 53 2c 20 61 s the P, F, S, a
2b3c0 6e 64 20 4c 20 76 61 6c 75 65 73 20 66 72 6f 6d nd L values from
2b3d0 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 any prior calls
2b3e0 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 with.**
2b3f0 20 20 74 68 65 20 73 61 6d 65 20 44 2c 20 58 2c the same D, X,
2b400 20 4e 2c 20 61 6e 64 20 45 20 76 61 6c 75 65 73 N, and E values
2b410 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31 32 7d ..**.** {F16112}
2b420 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 The [sqlite3_cr
2b430 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c eate_function(D,
2b440 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 X,...)] interfac
2b450 65 20 66 61 69 6c 73 20 77 69 74 68 0a 2a 2a 20 e fails with.**
2b460 20 20 20 20 20 20 20 20 20 61 20 72 65 74 75 72 a retur
2b470 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 n code of [SQLIT
2b480 45 5f 45 52 52 4f 52 5d 20 69 66 20 74 68 65 20 E_ERROR] if the
2b490 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d SQL function nam
2b4a0 65 20 58 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 e X is.**
2b4b0 20 20 20 6c 6f 6e 67 65 72 20 74 68 61 6e 20 32 longer than 2
2b4c0 35 35 20 62 79 74 65 73 20 65 78 63 6c 75 73 69 55 bytes exclusi
2b4d0 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 20 74 ve of the zero t
2b4e0 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a erminator..**.**
2b4f0 20 7b 46 31 36 31 31 38 7d 20 45 69 74 68 65 72 {F16118} Either
2b500 20 46 20 6d 75 73 74 20 62 65 20 4e 55 4c 4c 20 F must be NULL
2b510 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20 and S and L are
2b520 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 non-NULL or else
2b530 20 46 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 F.** i
2b540 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53 s non-NULL and S
2b550 20 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c 4c 2c and L are NULL,
2b560 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 20 20 otherwise.**
2b570 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
2b580 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
2b590 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 D,X,N,E,P,F,S,L)
2b5a0 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 ] returns [SQLIT
2b5b0 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 E_ERROR]..**.**
2b5c0 7b 46 31 36 31 32 31 7d 20 54 68 65 20 5b 73 71 {F16121} The [sq
2b5d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2b5e0 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e ction(D,...)] in
2b5f0 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 terface fails wi
2b600 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 th an.**
2b610 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 error code of
2b620 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 66 [SQLITE_BUSY] if
2b630 20 74 68 65 72 65 20 65 78 69 73 74 20 5b 70 72 there exist [pr
2b640 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2b650 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 s].** a
2b660 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
2b670 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
2b680 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a nection] D..**.*
2b690 2a 20 7b 46 31 36 31 32 34 7d 20 54 68 65 20 5b * {F16124} The [
2b6a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2b6b0 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e unction(D,X,N,..
2b6c0 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 .)] interface fa
2b6d0 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 ils with an.**
2b6e0 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f error co
2b6f0 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 de of [SQLITE_ER
2b700 52 4f 52 5d 20 69 66 20 70 61 72 61 6d 65 74 65 ROR] if paramete
2b710 72 20 4e 20 28 73 70 65 63 69 66 79 69 6e 67 20 r N (specifying
2b720 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 the number.**
2b730 20 20 20 20 20 20 20 6f 66 20 61 72 67 75 6d 65 of argume
2b740 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66 nts to the SQL f
2b750 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 72 65 unction being re
2b760 67 69 73 74 65 72 65 64 29 20 69 73 20 6c 65 73 gistered) is les
2b770 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 s.** th
2b780 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 an -1 or greater
2b790 20 74 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a than 127..**.**
2b7a0 20 7b 46 31 36 31 32 37 7d 20 57 68 65 6e 20 4e {F16127} When N
2b7b0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
2b7c0 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 , the [sqlite3_c
2b7d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 reate_function(D
2b7e0 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 ,X,N,...)].**
2b7f0 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 interface
2b800 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b causes callback
2b810 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 s to be invoked
2b820 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 for the SQL func
2b830 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 tion.**
2b840 20 6e 61 6d 65 64 20 58 20 77 68 65 6e 20 74 68 named X when th
2b850 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 e number of argu
2b860 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c ments to the SQL
2b870 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 function is.**
2b880 20 20 20 20 20 20 20 20 20 65 78 61 63 74 6c 79 exactly
2b890 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 N..**.** {F1613
2b8a0 30 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d 31 2c 0} When N is -1,
2b8b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 the [sqlite3_cr
2b8c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c eate_function(D,
2b8d0 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 X,N,...)].**
2b8e0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 interface
2b8f0 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 causes callbacks
2b900 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 to be invoked f
2b910 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 or the SQL funct
2b920 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ion.**
2b930 6e 61 6d 65 64 20 58 20 77 69 74 68 20 61 6e 79 named X with any
2b940 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d number of argum
2b950 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 ents..**.** {F16
2b960 31 33 33 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 133} When calls
2b970 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 to [sqlite3_crea
2b980 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c te_function(D,X,
2b990 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 N,...)].**
2b9a0 20 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 specify mult
2b9b0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 iple implementat
2b9c0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 ions of the same
2b9d0 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 function X.**
2b9e0 20 20 20 20 20 20 20 20 61 6e 64 20 77 68 65 6e and when
2b9f0 20 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 one implementat
2ba00 69 6f 6e 20 68 61 73 20 4e 3e 3d 30 20 61 6e 64 ion has N>=0 and
2ba10 20 74 68 65 20 6f 74 68 65 72 20 68 61 73 20 4e the other has N
2ba20 3d 28 2d 31 29 0a 2a 2a 20 20 20 20 20 20 20 20 =(-1).**
2ba30 20 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 the implementa
2ba40 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d tion with a non-
2ba50 7a 65 72 6f 20 4e 20 69 73 20 70 72 65 66 65 72 zero N is prefer
2ba60 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 red..**.** {F161
2ba70 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 36} When calls t
2ba80 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 o [sqlite3_creat
2ba90 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e e_function(D,X,N
2baa0 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 ,E,...)].**
2bab0 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c specify mul
2bac0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 tiple implementa
2bad0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
2bae0 65 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 e function X wit
2baf0 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 h.** th
2bb00 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 e same number of
2bb10 20 61 72 67 75 6d 65 6e 74 73 20 4e 20 62 75 74 arguments N but
2bb20 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 0a with different.
2bb30 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f ** enco
2bb40 64 69 6e 67 73 20 45 2c 20 74 68 65 6e 20 74 68 dings E, then th
2bb50 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2bb60 20 77 68 65 72 65 20 45 20 6d 61 74 63 68 65 73 where E matches
2bb70 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
2bb80 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 database encodi
2bb90 6e 67 20 69 73 20 70 72 65 66 65 72 72 65 64 2e ng is preferred.
2bba0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 39 7d 20 .**.** {F16139}
2bbb0 46 6f 72 20 61 6e 20 61 67 67 72 65 67 61 74 65 For an aggregate
2bbc0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 72 SQL function cr
2bbd0 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 eated using.**
2bbe0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
2bbf0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2bc00 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c 4c (D,X,N,E,P,0,S,L
2bc10 29 5d 20 74 68 65 20 66 69 6e 61 6c 69 7a 65 72 )] the finalizer
2bc20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e .** fun
2bc30 63 74 69 6f 6e 20 4c 20 77 69 6c 6c 20 61 6c 77 ction L will alw
2bc40 61 79 73 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 ays be invoked e
2bc50 78 61 63 74 6c 79 20 6f 6e 63 65 20 69 66 20 74 xactly once if t
2bc60 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 he.** s
2bc70 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 53 20 69 tep function S i
2bc80 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 s called one or
2bc90 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a more times..**.*
2bca0 2a 20 7b 46 31 36 31 34 32 7d 20 57 68 65 6e 20 * {F16142} When
2bcb0 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 65 SQLite invokes e
2bcc0 69 74 68 65 72 20 74 68 65 20 78 46 75 6e 63 20 ither the xFunc
2bcd0 6f 72 20 78 53 74 65 70 20 66 75 6e 63 74 69 6f or xStep functio
2bce0 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 n of.**
2bcf0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d an application-
2bd00 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
2bd10 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 tion or aggregat
2bd20 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 20 20 20 e created.**
2bd30 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 by [sqlite
2bd40 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2bd50 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 n()] or [sqlite3
2bd60 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2bd70 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 16()],.**
2bd80 20 20 20 74 68 65 6e 20 74 68 65 20 61 72 72 61 then the arra
2bd90 79 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 y of [sqlite3_va
2bda0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 20 70 61 73 lue] objects pas
2bdb0 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 sed as the.**
2bdc0 20 20 20 20 20 20 20 74 68 69 72 64 20 70 61 72 third par
2bdd0 61 6d 65 74 65 72 20 61 72 65 20 61 6c 77 61 79 ameter are alway
2bde0 73 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c s [protected sql
2bdf0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
2be00 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 cts..*/.int sqli
2be10 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2be20 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a ion(. sqlite3 *
2be30 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 db,. const char
2be40 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c *zFunctionName,
2be50 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 . int nArg,. i
2be60 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 nt eTextRep,. v
2be70 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 oid *pApp,. voi
2be80 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 d (*xFunc)(sqlit
2be90 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
2bea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
2beb0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 ,. void (*xStep
2bec0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
2bed0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
2bee0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
2bef0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 (*xFinal)(sqlite
2bf00 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 3_context*).);.i
2bf10 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
2bf20 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 e_function16(.
2bf30 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
2bf40 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 onst void *zFunc
2bf50 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 tionName,. int
2bf60 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 nArg,. int eTex
2bf70 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 tRep,. void *pA
2bf80 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 pp,. void (*xFu
2bf90 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
2bfa0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
2bfb0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
2bfc0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
2bfd0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
2bfe0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
2bff0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
2c000 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
2c010 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 xt*).);../*.** C
2c020 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e API3REF: Text En
2c030 63 6f 64 69 6e 67 73 20 7b 46 31 30 32 36 37 7d codings {F10267}
2c040 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
2c050 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 stant define int
2c060 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 eger codes that
2c070 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 represent the va
2c080 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e rious.** text en
2c090 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 codings supporte
2c0a0 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a d by SQLite..*/.
2c0b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
2c0c0 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a TF8 1.
2c0d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
2c0e0 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a TF16LE 2.
2c0f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
2c100 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a TF16BE 3.
2c110 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
2c120 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 TF16 4
2c130 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 /* Use native
2c140 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 byte order */.#
2c150 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e define SQLITE_AN
2c160 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 Y 5
2c170 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 /* sqlite3_cre
2c180 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c ate_function onl
2c190 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
2c1a0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 ITE_UTF16_ALIGNE
2c1b0 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 D 8 /* sqlit
2c1c0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
2c1d0 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a ion only */../*.
2c1e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 73 ** CAPI3REF: Obs
2c1f0 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e 73 0a olete Functions.
2c200 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 **.** These func
2c210 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20 6e 6f tions are all no
2c220 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49 6e 20 w obsolete. In
2c230 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 order to maintai
2c240 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 n.** backwards c
2c250 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 ompatibility wit
2c260 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 77 65 h older code, we
2c270 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73 75 70 continue to sup
2c280 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20 66 75 port.** these fu
2c290 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65 nctions. Howeve
2c2a0 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70 6d 65 r, new developme
2c2b0 6e 74 20 70 72 6f 6a 65 63 74 73 20 73 68 6f 75 nt projects shou
2c2c0 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 ld avoid.** the
2c2d0 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e use of these fun
2c2e0 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 ctions. To help
2c2f0 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c encourage peopl
2c300 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 e to avoid.** us
2c310 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 ing these functi
2c320 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 ons, we are not
2c330 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f going to tell yo
2c340 75 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a u want they do..
2c350 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 */.int sqlite3_a
2c360 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 ggregate_count(s
2c370 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
2c380 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 ;.int sqlite3_ex
2c390 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 pired(sqlite3_st
2c3a0 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 mt*);.int sqlite
2c3b0 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 3_transfer_bindi
2c3c0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ngs(sqlite3_stmt
2c3d0 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a *, sqlite3_stmt*
2c3e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 );.int sqlite3_g
2c3f0 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f lobal_recover(vo
2c400 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 id);.void sqlite
2c410 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 3_thread_cleanup
2c420 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 (void);.int sqli
2c430 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d te3_memory_alarm
2c440 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 (void(*)(void*,s
2c450 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 qlite3_int64,int
2c460 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f ),void*,sqlite3_
2c470 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int64);../*.** C
2c480 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 API3REF: Obtaini
2c490 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 ng SQL Function
2c4a0 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 Parameter Values
2c4b0 20 7b 46 31 35 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 {F15100}.**.**
2c4c0 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 The C-language i
2c4d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
2c4e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 SQL functions a
2c4f0 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 nd aggregates us
2c500 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f es.** this set o
2c510 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 f interface rout
2c520 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 ines to access t
2c530 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c he parameter val
2c540 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 ues on.** the fu
2c550 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 nction or aggreg
2c560 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ate..**.** The x
2c570 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 Func (for scalar
2c580 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 functions) or x
2c590 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 Step (for aggreg
2c5a0 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 ates) parameters
2c5b0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f .** to [sqlite3_
2c5c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
2c5d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
2c5e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
2c5f0 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 6()].** define c
2c600 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d allbacks that im
2c610 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 plement the SQL
2c620 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 functions and ag
2c630 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 gregates..** The
2c640 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
2c650 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b o these callback
2c660 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 s is an array of
2c670 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 pointers to.**
2c680 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
2c690 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
2c6a0 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 s. There is one
2c6b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
2c6c0 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 object for.** e
2c6d0 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f ach parameter to
2c6e0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
2c6f0 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e n. These routin
2c700 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a es are used to.*
2c710 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 * extract values
2c720 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 from the [sqlit
2c730 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
2c740 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 s..**.** These r
2c750 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c outines work onl
2c760 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 y with [protecte
2c770 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
2c780 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 objects..** Any
2c790 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 attempt to use
2c7a0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f these routines o
2c7b0 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 n an [unprotecte
2c7c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
2c7d0 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c .** object resul
2c7e0 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 ts in undefined
2c7f0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 behavior..**.**
2c800 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 These routines w
2c810 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 ork just like th
2c820 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
2c830 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 [column access f
2c840 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 unctions].** exc
2c850 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 ept that these
2c860 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 routines take a
2c870 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 single [protecte
2c880 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
2c890 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 object.** point
2c8a0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 er instead of a
2c8b0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 [sqlite3_stmt*]
2c8c0 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 pointer and an i
2c8d0 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 nteger column nu
2c8e0 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 mber..**.** The
2c8f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
2c900 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 xt16() interface
2c910 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d extracts a UTF-
2c920 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 16 string.** in
2c930 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d the native byte-
2c940 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 order of the hos
2c950 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 0a t machine. The.
2c960 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
2c970 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 _text16be() and
2c980 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
2c990 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 xt16le() interfa
2c9a0 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 ces.** extract U
2c9b0 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 TF-16 strings as
2c9c0 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 big-endian and
2c9d0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 little-endian re
2c9e0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a spectively..**.*
2c9f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 * The sqlite3_va
2ca00 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 lue_numeric_type
2ca10 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 () interface att
2ca20 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a empts to apply.*
2ca30 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 * numeric affini
2ca40 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e ty to the value.
2ca50 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 This means tha
2ca60 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a t an attempt is.
2ca70 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 ** made to conve
2ca80 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 rt the value to
2ca90 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c an integer or fl
2caa0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 oating point. I
2cab0 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 f.** such a conv
2cac0 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 ersion is possib
2cad0 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 le without loss
2cae0 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 of information (
2caf0 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 in other.** word
2cb00 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 s, if the value
2cb10 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 is a string that
2cb20 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 looks like a nu
2cb30 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 mber).** then th
2cb40 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 e conversion is
2cb50 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 performed. Othe
2cb60 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 rwise no convers
2cb70 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 ion occurs..** T
2cb80 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 he [SQLITE_INTEG
2cb90 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 ER | datatype] a
2cba0 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 fter conversion
2cbb0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
2cbc0 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 ** Please pay pa
2cbd0 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 rticular attenti
2cbe0 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 on to the fact t
2cbf0 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 hat the pointer
2cc00 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d returned.** from
2cc10 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2cc20 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 blob()], [sqlite
2cc30 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 3_value_text()],
2cc40 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
2cc50 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 value_text16()]
2cc60 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 can be invalidat
2cc70 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 ed by a subseque
2cc80 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 nt call to.** [s
2cc90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 qlite3_value_byt
2cca0 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f es()], [sqlite3_
2ccb0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d value_bytes16()]
2ccc0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 , [sqlite3_value
2ccd0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 _text()],.** or
2cce0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
2ccf0 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 ext16()]..**.**
2cd00 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d These routines m
2cd10 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 ust be called fr
2cd20 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 om the same thre
2cd30 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c ad as.** the SQL
2cd40 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 function that s
2cd50 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c upplied the [sql
2cd60 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 ite3_value*] par
2cd70 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 49 ameters..**.** I
2cd80 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
2cd90 20 7b 46 31 35 31 30 33 7d 20 54 68 65 20 5b 73 {F15103} The [s
2cda0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f qlite3_value_blo
2cdb0 62 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 b(V)] interface
2cdc0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 converts the.**
2cdd0 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 [protec
2cde0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2cdf0 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f e] object V into
2ce00 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e a BLOB and then
2ce10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 .** ret
2ce20 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
2ce30 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 o the converted
2ce40 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 value..**.** {F1
2ce50 35 31 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 5106} The [sqlit
2ce60 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 56 e3_value_bytes(V
2ce70 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
2ce80 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 urns the.**
2ce90 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 number of b
2cea0 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 ytes in the BLOB
2ceb0 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c or string (excl
2cec0 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 usive of the.**
2ced0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 zero te
2cee0 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 rminator on the
2cef0 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 string) that was
2cf00 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
2cf10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 .** mos
2cf20 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
2cf30 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2cf40 62 6c 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a 20 20 blob(V)] or.**
2cf50 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
2cf60 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 2e _value_text(V)].
2cf70 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 39 7d 20 .**.** {F15109}
2cf80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c The [sqlite3_val
2cf90 75 65 5f 62 79 74 65 73 31 36 28 56 29 5d 20 69 ue_bytes16(V)] i
2cfa0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
2cfb0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
2cfc0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2cfd0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28 in the string (
2cfe0 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 exclusive of the
2cff0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 .** zer
2d000 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 o terminator on
2d010 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 the string) that
2d020 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 was returned by
2d030 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
2d040 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c most recent cal
2d050 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 l to [sqlite3_va
2d060 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 2c 0a lue_text16(V)],.
2d070 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
2d080 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
2d090 36 62 65 28 56 29 5d 2c 20 6f 72 20 5b 73 71 6c 6be(V)], or [sql
2d0a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
2d0b0 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 6le(V)]..**.** {
2d0c0 46 31 35 31 31 32 7d 20 54 68 65 20 5b 73 71 6c F15112} The [sql
2d0d0 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c ite3_value_doubl
2d0e0 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 e(V)] interface
2d0f0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 converts the.**
2d100 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 [protec
2d110 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2d120 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f e] object V into
2d130 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e a floating poin
2d140 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 t value and.**
2d150 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 returns
2d160 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 a copy of that v
2d170 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 alue..**.** {F15
2d180 31 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 115} The [sqlite
2d190 33 5f 76 61 6c 75 65 5f 69 6e 74 28 56 29 5d 20 3_value_int(V)]
2d1a0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 interface conver
2d1b0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ts the.**
2d1c0 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 [protected sq
2d1d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2d1e0 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d ect V into a 64-
2d1f0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
2d200 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 er and.**
2d210 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c returns the l
2d220 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66 20 ower 32 bits of
2d230 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a that integer..**
2d240 0a 2a 2a 20 7b 46 31 35 31 31 38 7d 20 54 68 65 .** {F15118} The
2d250 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2d260 69 6e 74 36 34 28 56 29 5d 20 69 6e 74 65 72 66 int64(V)] interf
2d270 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 ace converts the
2d280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
2d290 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2d2a0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 value] object V
2d2b0 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 into a 64-bit si
2d2c0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 gned integer and
2d2d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 .** ret
2d2e0 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 urns a copy of t
2d2f0 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a hat integer..**.
2d300 2a 2a 20 7b 46 31 35 31 32 31 7d 20 54 68 65 20 ** {F15121} The
2d310 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
2d320 65 78 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63 ext(V)] interfac
2d330 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a e converts the.*
2d340 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 * [prot
2d350 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2d360 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e lue] object V in
2d370 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
2d380 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 ated UTF-8.**
2d390 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e string an
2d3a0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e d returns a poin
2d3b0 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 ter to that stri
2d3c0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 ng..**.** {F1512
2d3d0 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 4} The [sqlite3_
2d3e0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d value_text16(V)]
2d3f0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 interface conve
2d400 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 rts the.**
2d410 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 [protected s
2d420 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
2d430 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 ject V into a ze
2d440 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d ro-terminated 2-
2d450 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 byte.**
2d460 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 aligned UTF-16
2d470 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
2d480 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 r.** st
2d490 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 ring and returns
2d4a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
2d4b0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a at string..**.**
2d4c0 20 7b 46 31 35 31 32 37 7d 20 54 68 65 20 5b 73 {F15127} The [s
2d4d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
2d4e0 74 31 36 62 65 28 56 29 5d 20 69 6e 74 65 72 66 t16be(V)] interf
2d4f0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 ace converts the
2d500 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
2d510 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2d520 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 value] object V
2d530 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d into a zero-term
2d540 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a inated 2-byte.**
2d550 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 aligne
2d560 64 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 d UTF-16 big-end
2d570 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ian.**
2d580 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 string and retur
2d590 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
2d5a0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a that string..**.
2d5b0 2a 2a 20 7b 46 31 35 31 33 30 7d 20 54 68 65 20 ** {F15130} The
2d5c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
2d5d0 65 78 74 31 36 6c 65 28 56 29 5d 20 69 6e 74 65 ext16le(V)] inte
2d5e0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 rface converts t
2d5f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
2d600 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2d610 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
2d620 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 V into a zero-te
2d630 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a rminated 2-byte.
2d640 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 ** alig
2d650 6e 65 64 20 55 54 46 2d 31 36 20 6c 69 74 74 6c ned UTF-16 littl
2d660 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 e-endian.**
2d670 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 string and
2d680 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
2d690 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 r to that string
2d6a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 33 7d ..**.** {F15133}
2d6b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 The [sqlite3_va
2d6c0 6c 75 65 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 lue_type(V)] int
2d6d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a erface returns.*
2d6e0 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f * one o
2d6f0 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c f [SQLITE_NULL],
2d700 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 [SQLITE_INTEGER
2d710 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 ], [SQLITE_FLOAT
2d720 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ],.** [
2d730 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 SQLITE_TEXT], or
2d740 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 [SQLITE_BLOB] a
2d750 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f s appropriate fo
2d760 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 r.** th
2d770 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
2d780 5d 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a ] object V..**.*
2d790 2a 20 7b 46 31 35 31 33 36 7d 20 54 68 65 20 5b * {F15136} The [
2d7a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 sqlite3_value_nu
2d7b0 6d 65 72 69 63 5f 74 79 70 65 28 56 29 5d 20 69 meric_type(V)] i
2d7c0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 nterface convert
2d7d0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 s.** th
2d7e0 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c e [protected sql
2d7f0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
2d800 63 74 20 56 20 69 6e 74 6f 20 65 69 74 68 65 72 ct V into either
2d810 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 0a 2a an integer or.*
2d820 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 6c 6f * a flo
2d830 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 ating point valu
2d840 65 20 69 66 20 69 74 20 63 61 6e 20 64 6f 20 73 e if it can do s
2d850 6f 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f o without loss o
2d860 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e f.** in
2d870 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e 64 20 72 formation, and r
2d880 65 74 75 72 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 eturns one of [S
2d890 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 QLITE_NULL],.**
2d8a0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 [SQLITE
2d8b0 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 _INTEGER], [SQLI
2d8c0 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 TE_FLOAT], [SQLI
2d8d0 54 45 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 TE_TEXT], or.**
2d8e0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 [SQLITE
2d8f0 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 _BLOB] as approp
2d900 72 69 61 74 65 20 66 6f 72 20 74 68 65 0a 2a 2a riate for the.**
2d910 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 [prote
2d920 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2d930 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 61 66 74 ue] object V aft
2d940 65 72 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f er the conversio
2d950 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f n attempt..*/.co
2d960 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
2d970 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 3_value_blob(sql
2d980 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e ite3_value*);.in
2d990 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f t sqlite3_value_
2d9a0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 bytes(sqlite3_va
2d9b0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
2d9c0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 e3_value_bytes16
2d9d0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
2d9e0 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 ;.double sqlite3
2d9f0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 _value_double(sq
2da00 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
2da10 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
2da20 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c _int(sqlite3_val
2da30 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e ue*);.sqlite3_in
2da40 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 t64 sqlite3_valu
2da50 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f e_int64(sqlite3_
2da60 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 value*);.const u
2da70 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 nsigned char *sq
2da80 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
2da90 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
2daa0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
2dab0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
2dac0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 16(sqlite3_value
2dad0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a *);.const void *
2dae0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
2daf0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 xt16le(sqlite3_v
2db00 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f alue*);.const vo
2db10 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 id *sqlite3_valu
2db20 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 e_text16be(sqlit
2db30 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 e3_value*);.int
2db40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 sqlite3_value_ty
2db50 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 pe(sqlite3_value
2db60 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
2db70 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 value_numeric_ty
2db80 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 pe(sqlite3_value
2db90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
2dba0 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 REF: Obtain Aggr
2dbb0 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 egate Function C
2dbc0 6f 6e 74 65 78 74 20 7b 46 31 36 32 31 30 7d 0a ontext {F16210}.
2dbd0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d **.** The implem
2dbe0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 entation of aggr
2dbf0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 egate SQL functi
2dc00 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 ons use this rou
2dc10 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 tine to allocate
2dc20 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 .** a structure
2dc30 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 for storing thei
2dc40 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 r state..**.** T
2dc50 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 he first time th
2dc60 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 e sqlite3_aggreg
2dc70 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f ate_context() ro
2dc80 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 utine is called
2dc90 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69 63 75 for a.** particu
2dca0 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 lar aggregate, S
2dcb0 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 QLite allocates
2dcc0 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 nBytes of memory
2dcd0 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 , zeroes out tha
2dce0 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 t.** memory, and
2dcf0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
2dd00 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63 er to it. On sec
2dd10 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 ond and subseque
2dd20 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 nt calls to.** s
2dd30 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
2dd40 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 _context() for t
2dd50 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 he same aggregat
2dd60 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 e function index
2dd70 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 ,.** the same bu
2dd80 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 ffer is returned
2dd90 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 . The implementa
2dda0 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67 67 72 tion of the aggr
2ddb0 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a egate can use.**
2ddc0 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 62 75 the returned bu
2ddd0 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 ffer to accumula
2dde0 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 te data..**.** S
2ddf0 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 QLite automatica
2de00 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 61 6c lly frees the al
2de10 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72 20 77 located buffer w
2de20 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 hen the aggregat
2de30 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c e.** query concl
2de40 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 udes..**.** The
2de50 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
2de60 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 should be a copy
2de70 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 of the.** [sqli
2de80 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 te3_context | SQ
2de90 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 L function conte
2dea0 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 xt] that is the
2deb0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a first parameter.
2dec0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 ** to the callba
2ded0 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 ck routine that
2dee0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 implements the a
2def0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f ggregate functio
2df00 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f n..**.** This ro
2df10 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 utine must be ca
2df20 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 lled from the sa
2df30 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 me thread in whi
2df40 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 ch.** the aggreg
2df50 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ate SQL function
2df60 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a is running..**.
2df70 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
2df80 2a 0a 2a 2a 20 7b 46 31 36 32 31 31 7d 20 54 68 *.** {F16211} Th
2df90 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 e first invocati
2dfa0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61 on of [sqlite3_a
2dfb0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
2dfc0 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 (C,N)] for.**
2dfd0 20 20 20 20 20 20 20 61 20 70 61 72 74 69 63 75 a particu
2dfe0 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 lar instance of
2dff0 61 6e 20 61 67 67 72 65 67 61 74 65 20 66 75 6e an aggregate fun
2e000 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 ction (for a par
2e010 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20 ticular.**
2e020 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29 20 63 context C) c
2e030 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 auses SQLite to
2e040 61 6c 6c 6f 63 61 74 65 20 4e 20 62 79 74 65 73 allocate N bytes
2e050 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20 of memory,.**
2e060 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 68 61 zero tha
2e070 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 t memory, and re
2e080 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 turn a pointer t
2e090 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 o the allocated
2e0a0 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 memory..**.** {F
2e0b0 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f 16213} If a memo
2e0c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 ry allocation er
2e0d0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e ror occurs durin
2e0e0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 g.** [s
2e0f0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
2e100 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74 _context(C,N)] t
2e110 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e hen the function
2e120 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a returns 0..**.*
2e130 2a 20 7b 46 31 36 32 31 35 7d 20 53 65 63 6f 6e * {F16215} Secon
2e140 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 d and subsequent
2e150 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a invocations of.
2e160 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
2e170 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
2e180 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 ontext(C,N)] for
2e190 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 65 78 the same contex
2e1a0 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20 t pointer C.**
2e1b0 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65 20 74 ignore t
2e1c0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 61 he N parameter a
2e1d0 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e nd return a poin
2e1e0 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d 65 0a ter to the same.
2e1f0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c 6f 63 ** bloc
2e200 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74 75 k of memory retu
2e210 72 6e 65 64 20 62 79 20 74 68 65 20 66 69 72 73 rned by the firs
2e220 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a t invocation..**
2e230 0a 2a 2a 20 7b 46 31 36 32 31 37 7d 20 54 68 65 .** {F16217} The
2e240 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 memory allocate
2e250 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 61 67 d by [sqlite3_ag
2e260 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
2e270 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 C,N)] is.**
2e280 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c automatical
2e290 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68 65 20 ly freed on the
2e2a0 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 next call to [sq
2e2b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a lite3_reset()].*
2e2c0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 * or [s
2e2d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2e2e0 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 )] for the [prep
2e2f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2e300 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 containing.**
2e310 20 20 20 20 20 20 20 74 68 65 20 61 67 67 72 65 the aggre
2e320 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61 73 gate function as
2e330 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 63 6f sociated with co
2e340 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64 ntext C..*/.void
2e350 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 *sqlite3_aggreg
2e360 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 ate_context(sqli
2e370 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
2e380 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a t nBytes);../*.*
2e390 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 * CAPI3REF: User
2e3a0 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 Data For Functi
2e3b0 6f 6e 73 20 7b 46 31 36 32 34 30 7d 0a 2a 2a 0a ons {F16240}.**.
2e3c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 ** The sqlite3_u
2e3d0 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 ser_data() inter
2e3e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 face returns a c
2e3f0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f opy of.** the po
2e400 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 inter that was t
2e410 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 he pUserData par
2e420 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 ameter (the 5th
2e430 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 parameter).** of
2e440 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 the [sqlite3_cr
2e450 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
2e460 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
2e470 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2e480 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 16()] routines t
2e490 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a hat originally.*
2e4a0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 * registered the
2e4b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 application def
2e4c0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b ined function. {
2e4d0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 END}.**.** This
2e4e0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 routine must be
2e4f0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
2e500 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 same thread in w
2e510 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c hich.** the appl
2e520 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
2e530 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
2e540 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ing..**.** INVAR
2e550 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 IANTS:.**.** {F1
2e560 36 32 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 6243} The [sqlit
2e570 65 33 5f 75 73 65 72 5f 64 61 74 61 28 43 29 5d e3_user_data(C)]
2e580 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2e590 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 ns a copy of the
2e5a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 50 20 70 .** P p
2e5b0 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20 ointer from the
2e5c0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2e5d0 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 function(D,X,N,E
2e5e0 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 ,P,F,S,L)].**
2e5f0 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 or [sqlit
2e600 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2e610 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 on16(D,X,N,E,P,F
2e620 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 ,S,L)] call that
2e630 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 .** reg
2e640 69 73 74 65 72 65 64 20 74 68 65 20 53 51 4c 20 istered the SQL
2e650 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 function associa
2e660 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 ted with [sqlite
2e670 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 3_context] C..*/
2e680 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 .void *sqlite3_u
2e690 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 ser_data(sqlite3
2e6a0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a _context*);../*.
2e6b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 ** CAPI3REF: Dat
2e6c0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
2e6d0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b For Functions {
2e6e0 46 31 36 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 F16250}.**.** Th
2e6f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e sqlite3_contex
2e700 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e t_db_handle() in
2e710 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2e720 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 a copy of.** the
2e730 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
2e740 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2e750 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 tion] (the 1st p
2e760 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 arameter).** of
2e770 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 the [sqlite3_cre
2e780 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a ate_function()].
2e790 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
2e7a0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
2e7b0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 6()] routines th
2e7c0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a at originally.**
2e7d0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 registered the
2e7e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 application defi
2e7f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a ned function..**
2e800 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
2e810 2a 2a 0a 2a 2a 20 7b 46 31 36 32 35 33 7d 20 54 **.** {F16253} T
2e820 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 he [sqlite3_cont
2e830 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 43 29 ext_db_handle(C)
2e840 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
2e850 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 rns a copy of th
2e860 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 e.** D
2e870 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 pointer from the
2e880 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
2e890 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c _function(D,X,N,
2e8a0 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 E,P,F,S,L)].**
2e8b0 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 or [sqli
2e8c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2e8d0 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c ion16(D,X,N,E,P,
2e8e0 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 F,S,L)] call tha
2e8f0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 t.** re
2e900 67 69 73 74 65 72 65 64 20 74 68 65 20 53 51 4c gistered the SQL
2e910 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 function associ
2e920 61 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 ated with [sqlit
2e930 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a e3_context] C..*
2e940 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 /.sqlite3 *sqlit
2e950 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 e3_context_db_ha
2e960 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e ndle(sqlite3_con
2e970 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 text*);../*.** C
2e980 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f API3REF: Functio
2e990 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 n Auxiliary Data
2e9a0 20 7b 46 31 36 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 {F16270}.**.**
2e9b0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 The following tw
2e9c0 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 o functions may
2e9d0 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 be used by scala
2e9e0 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 r SQL functions
2e9f0 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 to.** associate
2ea00 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 metadata with ar
2ea10 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 gument values. I
2ea20 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 f the same value
2ea30 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a is passed to.**
2ea40 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 multiple invoca
2ea50 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
2ea60 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 e SQL function d
2ea70 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 uring query exec
2ea80 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 ution, under.**
2ea90 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 some circumstanc
2eaa0 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 es the associate
2eab0 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 d metadata may b
2eac0 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 e preserved. Thi
2ead0 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 s may.** be used
2eae0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 , for example, t
2eaf0 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d o add a regular-
2eb00 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 expression match
2eb10 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 ing scalar.** fu
2eb20 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 nction. The comp
2eb30 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 iled version of
2eb40 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 the regular expr
2eb50 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 ession is stored
2eb60 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 as.** metadata
2eb70 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
2eb80 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 the SQL value pa
2eb90 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 ssed as the regu
2eba0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a lar expression.*
2ebb0 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 * pattern. The
2ebc0 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 compiled regular
2ebd0 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 expression can
2ebe0 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c be reused on mul
2ebf0 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 tiple.** invocat
2ec00 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 ions of the same
2ec10 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 function so tha
2ec20 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 t the original p
2ec30 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a attern string.**
2ec40 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
2ec50 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 o be recompiled
2ec60 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 on each invocati
2ec70 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 on..**.** The sq
2ec80 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
2ec90 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 a() interface re
2eca0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
2ecb0 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a to the metadata.
2ecc0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 ** associated by
2ecd0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 the sqlite3_set
2ece0 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 _auxdata() funct
2ecf0 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 ion with the Nth
2ed00 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c argument.** val
2ed10 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 ue to the applic
2ed20 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
2ed30 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65 nction. If no me
2ed40 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 tadata has been
2ed50 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 ever.** been set
2ed60 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 for the Nth arg
2ed70 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e ument of the fun
2ed80 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 ction, or if the
2ed90 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a corresponding.*
2eda0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d * function param
2edb0 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 eter has changed
2edc0 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d since the meta-
2edd0 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a data was set,.**
2ede0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 then sqlite3_ge
2edf0 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75 t_auxdata() retu
2ee00 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
2ee10 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 er..**.** The sq
2ee20 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
2ee30 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 a() interface sa
2ee40 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 ves the metadata
2ee50 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 .** pointed to b
2ee60 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 y its 3rd parame
2ee70 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 ter as the metad
2ee80 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 ata for the N-th
2ee90 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 .** argument of
2eea0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
2eeb0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
2eec0 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a . Subsequent.**
2eed0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
2eee0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_get_auxdata()
2eef0 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 might return thi
2ef00 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 s data, if it ha
2ef10 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 s.** not been de
2ef20 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 69 stroyed..** If i
2ef30 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 t is not NULL, S
2ef40 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b QLite will invok
2ef50 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 e the destructor
2ef60 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 .** function giv
2ef70 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61 en by the 4th pa
2ef80 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
2ef90 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
2efa0 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 on.** the metad
2efb0 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 ata when the cor
2efc0 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 responding funct
2efd0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 ion parameter ch
2efe0 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e anges.** or when
2eff0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
2f000 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 nt completes, wh
2f010 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 ichever comes fi
2f020 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 rst..**.** SQLit
2f030 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c e is free to cal
2f040 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 l the destructor
2f050 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 and drop metada
2f060 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 ta on any.** par
2f070 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 ameter of any fu
2f080 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 nction at any ti
2f090 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75 me. The only gu
2f0a0 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a arantee is that.
2f0b0 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f ** the destructo
2f0c0 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 r will be called
2f0d0 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 before the meta
2f0e0 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e data is dropped.
2f0f0 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 .**.** In practi
2f100 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 ce, metadata is
2f110 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 preserved betwee
2f120 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 n function calls
2f130 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 for.** expressi
2f140 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e ons that are con
2f150 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 stant at compile
2f160 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c time. This incl
2f170 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 udes literal.**
2f180 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76 values and SQL v
2f190 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 ariables..**.**
2f1a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d These routines m
2f1b0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 ust be called fr
2f1c0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 om the same thre
2f1d0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 ad in which.** t
2f1e0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
2f1f0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a is running..**.*
2f200 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
2f210 0a 2a 2a 20 7b 46 31 36 32 37 32 7d 20 54 68 65 .** {F16272} The
2f220 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 [sqlite3_get_au
2f230 78 64 61 74 61 28 43 2c 4e 29 5d 20 69 6e 74 65 xdata(C,N)] inte
2f240 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
2f250 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 pointer.**
2f260 20 20 20 20 74 6f 20 6d 65 74 61 64 61 74 61 20 to metadata
2f270 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
2f280 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 the Nth paramete
2f290 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e r of the SQL fun
2f2a0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ction.**
2f2b0 20 20 77 68 6f 73 65 20 63 6f 6e 74 65 78 74 20 whose context
2f2c0 69 73 20 43 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 is C, or NULL if
2f2d0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 there is no met
2f2e0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 adata associated
2f2f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 .** wit
2f300 68 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 h that parameter
2f310 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 34 7d ..**.** {F16274}
2f320 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
2f330 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c t_auxdata(C,N,P,
2f340 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 73 D)] interface as
2f350 73 69 67 6e 73 20 61 20 6d 65 74 61 64 61 74 61 signs a metadata
2f360 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 .** poi
2f370 6e 74 65 72 20 50 20 74 6f 20 74 68 65 20 4e 74 nter P to the Nt
2f380 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 h parameter of t
2f390 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
2f3a0 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a with context C..
2f3b0 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 36 7d 20 53 **.** {F16276} S
2f3c0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b QLite will invok
2f3d0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 e the destructor
2f3e0 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65 D with a single
2f3f0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 argument.**
2f400 20 20 20 20 20 20 77 68 69 63 68 20 69 73 20 74 which is t
2f410 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f 69 6e he metadata poin
2f420 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e 67 20 ter P following
2f430 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 a call to.**
2f440 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 [sqlite3_s
2f450 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 et_auxdata(C,N,P
2f460 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 74 65 ,D)] when SQLite
2f470 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 0a ceases to hold.
2f480 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
2f490 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 metadata..**.**
2f4a0 7b 46 31 36 32 37 37 7d 20 53 51 4c 69 74 65 20 {F16277} SQLite
2f4b0 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 20 6d ceases to hold m
2f4c0 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e 20 53 etadata for an S
2f4d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 QL function para
2f4e0 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 meter.**
2f4f0 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c 75 65 when the value
2f500 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d 65 74 of that paramet
2f510 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a er changes..**.*
2f520 2a 20 7b 46 31 36 32 37 38 7d 20 57 68 65 6e 20 * {F16278} When
2f530 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 [sqlite3_set_aux
2f540 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 data(C,N,P,D)] i
2f550 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 64 s invoked, the d
2f560 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 20 20 estructor.**
2f570 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65 64 20 is called
2f580 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 6d 65 for any prior me
2f590 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 tadata associate
2f5a0 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 d with the same
2f5b0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 function.**
2f5c0 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 20 61 context C a
2f5d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e 2e 0a nd parameter N..
2f5e0 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 39 7d 20 53 **.** {F16279} S
2f5f0 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c 6c 20 QLite will call
2f600 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20 destructors for
2f610 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69 74 20 any metadata it
2f620 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20 is holding.**
2f630 20 20 20 20 20 20 20 69 6e 20 61 20 70 61 72 74 in a part
2f640 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72 65 64 icular [prepared
2f650 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 77 68 statement] S wh
2f660 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 en either.**
2f670 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 [sqlite3_r
2f680 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 71 6c eset(S)] or [sql
2f690 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 ite3_finalize(S)
2f6a0 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a ] is called..*/.
2f6b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 void *sqlite3_ge
2f6c0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 t_auxdata(sqlite
2f6d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 3_context*, int
2f6e0 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 N);.void sqlite3
2f6f0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c _set_auxdata(sql
2f700 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
2f710 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 nt N, void*, voi
2f720 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a d (*)(void*));..
2f730 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2f740 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e Constants Defin
2f750 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 ing Special Dest
2f760 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20 ructor Behavior
2f770 7b 46 31 30 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 {F10280}.**.** T
2f780 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c hese are special
2f790 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 values for the
2f7a0 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 destructor that
2f7b0 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 is passed in as
2f7c0 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 the.** final arg
2f7d0 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 ument to routine
2f7e0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f s like [sqlite3_
2f7f0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 result_blob()].
2f800 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 If the destruct
2f810 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 or.** argument i
2f820 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c s SQLITE_STATIC,
2f830 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 it means that t
2f840 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 he content point
2f850 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a er is constant.*
2f860 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 * and will never
2f870 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 change. It doe
2f880 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 s not need to be
2f890 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 destroyed. The
2f8a0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 .** SQLITE_TRANS
2f8b0 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 IENT value means
2f8c0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e that the conten
2f8d0 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 t will likely ch
2f8e0 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e ange in.** the n
2f8f0 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 ear future and t
2f900 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c hat SQLite shoul
2f910 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 d make its own p
2f920 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a rivate copy of.*
2f930 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 * the content be
2f940 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a fore returning..
2f950 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 **.** The typede
2f960 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 f is necessary t
2f970 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 o work around pr
2f980 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 oblems in certai
2f990 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 n.** C++ compile
2f9a0 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 rs. See ticket
2f9b0 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 #2191..*/.typede
2f9c0 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 f void (*sqlite3
2f9d0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 _destructor_type
2f9e0 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e )(void*);.#defin
2f9f0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 e SQLITE_STATIC
2fa00 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 ((sqlite3_d
2fa10 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 estructor_type)0
2fa20 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
2fa30 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 _TRANSIENT ((s
2fa40 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f qlite3_destructo
2fa50 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a r_type)-1)../*.*
2fa60 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 * CAPI3REF: Sett
2fa70 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f ing The Result O
2fa80 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f f An SQL Functio
2fa90 6e 20 7b 46 31 36 34 30 30 7d 0a 2a 2a 0a 2a 2a n {F16400}.**.**
2faa0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
2fab0 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 are used by the
2fac0 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 xFunc or xFinal
2fad0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a callbacks that.*
2fae0 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 * implement SQL
2faf0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 functions and ag
2fb00 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a gregates. See.*
2fb10 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 * [sqlite3_creat
2fb20 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e e_function()] an
2fb30 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
2fb40 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a e_function16()].
2fb50 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 ** for additiona
2fb60 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
2fb70 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
2fb80 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d ions work very m
2fb90 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 uch like the [pa
2fba0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d rameter binding]
2fbb0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 family of.** fu
2fbc0 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 nctions used to
2fbd0 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 bind values to h
2fbe0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 ost parameters i
2fbf0 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 n prepared state
2fc00 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 ments..** Refer
2fc10 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 to the [SQL para
2fc20 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 meter] documenta
2fc30 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f tion for additio
2fc40 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
2fc50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
2fc60 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 e3_result_blob()
2fc70 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
2fc80 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a the result from.
2fc90 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f ** an applicatio
2fca0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
2fcb0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f on to be the BLO
2fcc0 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 B whose content
2fcd0 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f is pointed.** to
2fce0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 by the second p
2fcf0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 arameter and whi
2fd00 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f ch is N bytes lo
2fd10 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 ng where N is th
2fd20 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d e.** third param
2fd30 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eter..**.** The
2fd40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a sqlite3_result_z
2fd50 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 eroblob() interf
2fd60 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 aces set the res
2fd70 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 ult of.** the ap
2fd80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2fd90 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
2fda0 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 a BLOB containi
2fdb0 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 ng all zero.** b
2fdc0 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 ytes and N bytes
2fdd0 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 in size, where
2fde0 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f N is the value o
2fdf0 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 f the 2nd parame
2fe00 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ter..**.** The s
2fe10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f qlite3_result_do
2fe20 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 uble() interface
2fe30 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 sets the result
2fe40 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c from.** an appl
2fe50 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
2fe60 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
2fe70 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
2fe80 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a value specified.
2fe90 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 ** by its 2nd ar
2fea0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 gument..**.** Th
2feb0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
2fec0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c _error() and sql
2fed0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
2fee0 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a r16() functions.
2fef0 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 ** cause the imp
2ff00 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e lemented SQL fun
2ff10 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 ction to throw a
2ff20 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 n exception..**
2ff30 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 SQLite uses the
2ff40 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 string pointed t
2ff50 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 o by the.** 2nd
2ff60 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c parameter of sql
2ff70 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
2ff80 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 r() or sqlite3_r
2ff90 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a esult_error16().
2ffa0 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f ** as the text o
2ffb0 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 f an error messa
2ffc0 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65 ge. SQLite inte
2ffd0 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 rprets the error
2ffe0 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 .** message stri
2fff0 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ng from sqlite3_
30000 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 result_error() a
30010 73 20 55 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a s UTF-8. SQLite.
30020 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 ** interprets th
30030 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 e string from sq
30040 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
30050 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 or16() as UTF-16
30060 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 in native.** by
30070 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68 te order. If th
30080 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
30090 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 r to sqlite3_res
300a0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f ult_error().** o
300b0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
300c0 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 _error16() is ne
300d0 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 gative then SQLi
300e0 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 te takes as the
300f0 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 error.** message
30100 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 all text up thr
30110 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a ough the first z
30120 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a ero character..*
30130 2a 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 * If the third p
30140 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
30150 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
30160 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 () or.** sqlite3
30170 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
30180 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 ) is non-negativ
30190 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 e then SQLite ta
301a0 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a kes that many.**
301b0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 bytes (not char
301c0 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 acters) from the
301d0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 2nd parameter a
301e0 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 s the error mess
301f0 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 age..** The sqli
30200 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
30210 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 () and sqlite3_r
30220 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a esult_error16().
30230 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 ** routines make
30240 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 a private copy
30250 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 of the error mes
30260 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 sage text before
30270 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e .** they return.
30280 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c Hence, the cal
30290 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 ling function ca
302a0 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a n deallocate or.
302b0 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 ** modify the te
302c0 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 xt after they re
302d0 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 turn without har
302e0 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 m..** The sqlite
302f0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 3_result_error_c
30300 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 ode() function c
30310 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 hanges the error
30320 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 code.** returne
30330 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 d by SQLite as a
30340 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 result of an er
30350 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f ror in a functio
30360 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a n. By default,.
30370 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 ** the error cod
30380 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f e is SQLITE_ERRO
30390 52 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e 74 R. A subsequent
303a0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
303b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a _result_error().
303c0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ** or sqlite3_re
303d0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 sult_error16() r
303e0 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 esets the error
303f0 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 code to SQLITE_E
30400 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 RROR..**.** The
30410 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
30420 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 oobig() interfac
30430 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 e causes SQLite
30440 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f to throw an erro
30450 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 r.** indicating
30460 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 that a string or
30470 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 BLOB is to long
30480 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a to represent..*
30490 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
304a0 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 _result_nomem()
304b0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 interface causes
304c0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 SQLite to throw
304d0 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 an error.** ind
304e0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d icating that a m
304f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
30500 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 failed..**.** T
30510 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
30520 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 t_int() interfac
30530 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 e sets the retur
30540 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 n value.** of th
30550 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
30560 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
30570 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 o be the 32-bit
30580 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a signed integer.*
30590 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e * value given in
305a0 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e the 2nd argumen
305b0 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 t..** The sqlite
305c0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 3_result_int64()
305d0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
305e0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
305f0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 .** of the appli
30600 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
30610 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 unction to be th
30620 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 e 64-bit signed
30630 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 integer.** value
30640 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e given in the 2n
30650 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a d argument..**.*
30660 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
30670 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 sult_null() inte
30680 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
30690 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f eturn value.** o
306a0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
306b0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
306c0 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a on to be NULL..*
306d0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
306e0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 _result_text(),
306f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
30700 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 ext16(),.** sqli
30710 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
30720 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 6le(), and sqlit
30730 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
30740 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a be() interfaces.
30750 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 ** set the retur
30760 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 n value of the a
30770 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
30780 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
30790 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 e.** a text stri
307a0 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 ng which is repr
307b0 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 esented as UTF-8
307c0 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 , UTF-16 native
307d0 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 byte order,.** U
307e0 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 TF-16 little end
307f0 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 ian, or UTF-16 b
30800 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 ig endian, respe
30810 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 ctively..** SQLi
30820 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 te takes the tex
30830 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 t result from th
30840 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 e application fr
30850 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 om.** the 2nd pa
30860 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 rameter of the s
30870 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
30880 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a xt* interfaces..
30890 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 ** If the 3rd pa
308a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
308b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
308c0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a xt* interfaces.*
308d0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 * is negative, t
308e0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 hen SQLite takes
308f0 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f result text fro
30900 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 m the 2nd parame
30910 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 ter.** through t
30920 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 he first zero ch
30930 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 aracter..** If t
30940 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 he 3rd parameter
30950 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
30960 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
30970 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f erfaces.** is no
30980 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e n-negative, then
30990 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 as many bytes (
309a0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 not characters)
309b0 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 of the text.** p
309c0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 ointed to by the
309d0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 2nd parameter a
309e0 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 re taken as the
309f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
30a00 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ned.** function
30a10 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 result..** If th
30a20 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
30a30 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
30a40 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
30a50 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c rfaces.** or sql
30a60 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
30a70 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 is a non-NULL p
30a80 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c ointer, then SQL
30a90 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a ite calls that.*
30aa0 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 * function as th
30ab0 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 e destructor on
30ac0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 the text or BLOB
30ad0 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 result when it
30ae0 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 has.** finished
30af0 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c using that resul
30b00 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 t..** If the 4th
30b10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
30b20 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
30b30 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
30b40 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f s or.** sqlite3_
30b50 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 result_blob is t
30b60 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 he special const
30b70 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 ant SQLITE_STATI
30b80 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a C, then SQLite.*
30b90 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 * assumes that t
30ba0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 he text or BLOB
30bb0 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e result is in con
30bc0 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 stant space and
30bd0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 does not.** copy
30be0 20 74 68 65 20 69 74 20 6f 72 20 63 61 6c 6c 20 the it or call
30bf0 61 20 64 65 73 74 72 75 63 74 6f 72 20 77 68 65 a destructor whe
30c00 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 n it has finishe
30c10 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 d using that res
30c20 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 ult..** If the 4
30c30 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
30c40 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
30c50 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
30c60 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 ces.** or sqlite
30c70 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 3_result_blob is
30c80 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e the special con
30c90 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 stant SQLITE_TRA
30ca0 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 NSIENT.** then S
30cb0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f QLite makes a co
30cc0 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 py of the result
30cd0 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 into space obta
30ce0 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f ined from.** fro
30cf0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
30d00 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 c()] before it r
30d10 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 eturns..**.** Th
30d20 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
30d30 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 _value() interfa
30d40 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 ce sets the resu
30d50 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 lt of.** the app
30d60 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
30d70 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
30d80 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 a copy the.** [u
30d90 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
30da0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
30db0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
30dc0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e e 2nd parameter.
30dd0 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 The.** sqlite3
30de0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
30df0 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 interface makes
30e00 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 a copy of the [s
30e10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
30e20 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 so that the [sq
30e30 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 lite3_value] spe
30e40 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 cified in the pa
30e50 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e rameter may chan
30e60 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c ge or.** be deal
30e70 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 located after sq
30e80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
30e90 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 ue() returns wit
30ea0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 hout harm..** A
30eb0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
30ec0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
30ed0 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 may always be u
30ee0 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 sed where an.**
30ef0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
30f00 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
30f10 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 ct is required,
30f20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e so either.** kin
30f30 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 d of [sqlite3_va
30f40 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 lue] object can
30f50 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 be used with thi
30f60 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a s interface..**.
30f70 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 ** If these rout
30f80 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
30f90 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 from within the
30fa0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
30fb0 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 .** than the one
30fc0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
30fd0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
30fe0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 ned function tha
30ff0 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 t received.** th
31000 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 e [sqlite3_conte
31010 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 xt] pointer, the
31020 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
31030 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e efined..**.** IN
31040 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
31050 7b 46 31 36 34 30 33 7d 20 54 68 65 20 64 65 66 {F16403} The def
31060 61 75 6c 74 20 72 65 74 75 72 6e 20 76 61 6c 75 ault return valu
31070 65 20 66 72 6f 6d 20 61 6e 79 20 53 51 4c 20 66 e from any SQL f
31080 75 6e 63 74 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e unction is NULL.
31090 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 36 7d 20 .**.** {F16406}
310a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
310b0 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 ult_blob(C,V,N,D
310c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 )] interface cha
310d0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 nges the.**
310e0 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 return valu
310f0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 e of function C
31100 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 74 68 61 to be a BLOB tha
31110 74 20 69 73 20 4e 20 62 79 74 65 73 0a 2a 2a 20 t is N bytes.**
31120 20 20 20 20 20 20 20 20 20 69 6e 20 6c 65 6e 67 in leng
31130 74 68 20 61 6e 64 20 77 69 74 68 20 63 6f 6e 74 th and with cont
31140 65 6e 74 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 ent pointed to b
31150 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 y V..**.** {F164
31160 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 09} The [sqlite3
31170 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 43 _result_double(C
31180 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 ,V)] interface c
31190 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 hanges the.**
311a0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 return va
311b0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 lue of function
311c0 43 20 74 6f 20 62 65 20 74 68 65 20 66 6c 6f 61 C to be the floa
311d0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 ting point value
311e0 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 V..**.** {F1641
311f0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 2} The [sqlite3_
31200 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 43 2c 56 result_error(C,V
31210 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 ,N)] interface c
31220 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 hanges the retur
31230 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 n.** va
31240 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 lue of function
31250 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 C to be an excep
31260 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 tion with error
31270 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 code.**
31280 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
31290 61 6e 64 20 61 20 55 54 46 2d 38 20 65 72 72 6f and a UTF-8 erro
312a0 72 20 6d 65 73 73 61 67 65 20 63 6f 70 69 65 64 r message copied
312b0 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 from V up to th
312c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 e.** fi
312d0 72 73 74 20 7a 65 72 6f 20 62 79 74 65 20 6f 72 rst zero byte or
312e0 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 20 61 until N bytes a
312f0 72 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 re read if N is
31300 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 positive..**.**
31310 7b 46 31 36 34 31 35 7d 20 54 68 65 20 5b 73 71 {F16415} The [sq
31320 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
31330 6f 72 31 36 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 or16(C,V,N)] int
31340 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 erface changes t
31350 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 he return.**
31360 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 value of f
31370 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 unction C to be
31380 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 an exception wit
31390 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 h error code.**
313a0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 [SQLITE
313b0 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 _ERROR] and a UT
313c0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 F-16 native byte
313d0 20 6f 72 64 65 72 20 65 72 72 6f 72 20 6d 65 73 order error mes
313e0 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 sage.**
313f0 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 copied from V u
31400 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a p to the first z
31410 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f ero terminator o
31420 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 0a r until N bytes.
31430 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 ** are
31440 72 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 read if N is pos
31450 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 itive..**.** {F1
31460 36 34 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 6418} The [sqlit
31470 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
31480 74 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74 65 72 toobig(C)] inter
31490 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 face changes the
314a0 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 return.**
314b0 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 value of the
314c0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 function C to b
314d0 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 e an exception w
314e0 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a ith error code.*
314f0 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 * [SQLI
31500 54 45 5f 54 4f 4f 42 49 47 5d 20 61 6e 64 20 61 TE_TOOBIG] and a
31510 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 n appropriate er
31520 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a ror message..**.
31530 2a 2a 20 7b 46 31 36 34 32 31 7d 20 54 68 65 20 ** {F16421} The
31540 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
31550 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 error_nomem(C)]
31560 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 interface change
31570 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 s the return.**
31580 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f value o
31590 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 f the function C
315a0 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 to be an except
315b0 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 ion with error c
315c0 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ode.**
315d0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 [SQLITE_NOMEM] a
315e0 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 nd an appropriat
315f0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e e error message.
31600 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 34 7d 20 .**.** {F16424}
31610 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
31620 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 43 ult_error_code(C
31630 2c 45 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 ,E)] interface c
31640 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 hanges the retur
31650 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 n.** va
31660 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 lue of the funct
31670 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 ion C to be an e
31680 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 xception with er
31690 72 6f 72 20 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 ror code E..**
316a0 20 20 20 20 20 20 20 20 54 68 65 20 65 72 72 6f The erro
316b0 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 69 r message text i
316c0 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a s unchanged..**.
316d0 2a 2a 20 7b 46 31 36 34 32 37 7d 20 54 68 65 20 ** {F16427} The
316e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
316f0 69 6e 74 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 int(C,V)] interf
31700 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a ace changes the.
31710 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
31720 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 rn value of func
31730 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 tion C to be the
31740 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 20 32-bit integer
31750 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b value V..**.** {
31760 46 31 36 34 33 30 7d 20 54 68 65 20 5b 73 71 6c F16430} The [sql
31770 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 ite3_result_int6
31780 34 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 4(C,V)] interfac
31790 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a e changes the.**
317a0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e return
317b0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 value of functi
317c0 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 36 on C to be the 6
317d0 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 4-bit integer va
317e0 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 lue V..**.** {F1
317f0 36 34 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 6433} The [sqlit
31800 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 e3_result_null(C
31810 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 )] interface cha
31820 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 nges the.**
31830 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 return valu
31840 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 e of function C
31850 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a to be NULL..**.*
31860 2a 20 7b 46 31 36 34 33 36 7d 20 54 68 65 20 5b * {F16436} The [
31870 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
31880 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e ext(C,V,N,D)] in
31890 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 terface changes
318a0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
318b0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
318c0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 function C to be
318d0 20 74 68 65 20 55 54 46 2d 38 20 73 74 72 69 6e the UTF-8 strin
318e0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 56 20 g.** V
318f0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 up to the first
31900 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 zero if N is neg
31910 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 ative.**
31920 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e or the first N
31930 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e bytes of V if N
31940 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
31950 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 39 7d ..**.** {F16439}
31960 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 The [sqlite3_re
31970 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c sult_text16(C,V,
31980 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 N,D)] interface
31990 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 changes the.**
319a0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 return v
319b0 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e alue of function
319c0 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 C to be the UTF
319d0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 -16 native byte
319e0 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 order.**
319f0 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f string V up to
31a00 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 the first zero
31a10 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 if N is negative
31a20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
31a30 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 the first N byte
31a40 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e s of V if N is n
31a50 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a on-negative..**.
31a60 2a 2a 20 7b 46 31 36 34 34 32 7d 20 54 68 65 20 ** {F16442} The
31a70 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
31a80 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 text16be(C,V,N,D
31a90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 )] interface cha
31aa0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 nges the.**
31ab0 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 return valu
31ac0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 e of function C
31ad0 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 36 to be the UTF-16
31ae0 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 big-endian.**
31af0 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 string V
31b00 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 up to the first
31b10 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 zero if N is ne
31b20 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 gative.**
31b30 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 or the first
31b40 4e 20 62 79 74 65 73 20 6f 72 20 56 20 69 66 20 N bytes or V if
31b50 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 N is non-negativ
31b60 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 35 e..**.** {F16445
31b70 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 } The [sqlite3_r
31b80 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 esult_text16le(C
31b90 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 ,V,N,D)] interfa
31ba0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a ce changes the.*
31bb0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 * retur
31bc0 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 n value of funct
31bd0 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 ion C to be the
31be0 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e UTF-16 little-en
31bf0 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 dian.**
31c00 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 string V up to
31c10 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 the first zero i
31c20 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a f N is negative.
31c30 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 ** or t
31c40 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 he first N bytes
31c50 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f of V if N is no
31c60 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a n-negative..**.*
31c70 2a 20 7b 46 31 36 34 34 38 7d 20 54 68 65 20 5b * {F16448} The [
31c80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
31c90 61 6c 75 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 alue(C,V)] inter
31ca0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 face changes the
31cb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 .** ret
31cc0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e urn value of fun
31cd0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 ction C to be th
31ce0 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 e [unprotected s
31cf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
31d00 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74 object
31d10 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 V..**.** {F1645
31d20 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 1} The [sqlite3_
31d30 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 result_zeroblob(
31d40 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 C,N)] interface
31d50 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 changes the.**
31d60 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 return v
31d70 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e alue of function
31d80 20 43 20 74 6f 20 62 65 20 61 6e 20 4e 2d 62 79 C to be an N-by
31d90 74 65 20 42 4c 4f 42 20 6f 66 20 61 6c 6c 20 7a te BLOB of all z
31da0 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 eros..**.** {F16
31db0 34 35 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 454} The [sqlite
31dc0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
31dd0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 ] and [sqlite3_r
31de0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 5d esult_error16()]
31df0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 .** int
31e00 65 72 66 61 63 65 73 20 6d 61 6b 65 20 61 20 63 erfaces make a c
31e10 6f 70 79 20 6f 66 20 74 68 65 69 72 20 65 72 72 opy of their err
31e20 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e or message strin
31e30 67 73 20 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 gs before.**
31e40 20 20 20 20 20 20 72 65 74 75 72 6e 69 6e 67 2e returning.
31e50 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 37 7d 20 .**.** {F16457}
31e60 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 If the D destruc
31e70 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f tor parameter to
31e80 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
31e90 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c _blob(C,V,N,D)],
31ea0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
31eb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
31ec0 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 t(C,V,N,D)], [sq
31ed0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
31ee0 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a t16(C,V,N,D)],.*
31ef0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
31f00 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
31f10 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 6be(C,V,N,D)], o
31f20 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 r.** [s
31f30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
31f40 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d xt16le(C,V,N,D)]
31f50 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 is the constant
31f60 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d [SQLITE_STATIC]
31f70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
31f80 6e 20 6e 6f 20 64 65 73 74 72 75 63 74 6f 72 20 n no destructor
31f90 69 73 20 65 76 65 72 20 63 61 6c 6c 65 64 20 6f is ever called o
31fa0 6e 20 74 68 65 20 70 6f 69 6e 74 65 72 20 56 20 n the pointer V
31fb0 61 6e 64 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20 and SQLite.**
31fc0 20 20 20 20 20 20 20 61 73 73 75 6d 65 73 20 74 assumes t
31fd0 68 61 74 20 56 20 69 73 20 69 6d 6d 75 74 61 62 hat V is immutab
31fe0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 le..**.** {F1646
31ff0 30 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 0} If the D dest
32000 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 ructor parameter
32010 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
32020 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 ult_blob(C,V,N,D
32030 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 )],.**
32040 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
32050 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 text(C,V,N,D)],
32060 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
32070 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d text16(C,V,N,D)]
32080 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 ,.** [s
32090 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
320a0 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d xt16be(C,V,N,D)]
320b0 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 , or.**
320c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
320d0 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c _text16le(C,V,N,
320e0 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74 D)] is the const
320f0 61 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ant.**
32100 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e [SQLITE_TRANSIEN
32110 54 5d 20 74 68 65 6e 20 74 68 65 20 69 6e 74 65 T] then the inte
32120 72 66 61 63 65 73 20 6d 61 6b 65 73 20 61 20 63 rfaces makes a c
32130 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 opy of the.**
32140 20 20 20 20 20 20 20 63 6f 6e 74 65 6e 74 20 6f content o
32150 66 20 56 20 61 6e 64 20 72 65 74 61 69 6e 73 20 f V and retains
32160 74 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 the copy..**.**
32170 7b 46 31 36 34 36 33 7d 20 49 66 20 74 68 65 20 {F16463} If the
32180 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 D destructor par
32190 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
321a0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 e3_result_blob(C
321b0 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 ,V,N,D)],.**
321c0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 [sqlite3_r
321d0 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e esult_text(C,V,N
321e0 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 ,D)], [sqlite3_r
321f0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 esult_text16(C,V
32200 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 ,N,D)],.**
32210 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 [sqlite3_res
32220 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 ult_text16be(C,V
32230 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 ,N,D)], or.**
32240 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
32250 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 result_text16le(
32260 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 73 6f 6d C,V,N,D)] is som
32270 65 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 e value other th
32280 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 an.** t
32290 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 he constants [SQ
322a0 4c 49 54 45 5f 53 54 41 54 49 43 5d 20 61 6e 64 LITE_STATIC] and
322b0 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 [SQLITE_TRANSIE
322c0 4e 54 5d 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 NT] then.**
322d0 20 20 20 20 20 53 51 4c 69 74 65 20 77 69 6c 6c SQLite will
322e0 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 invoke the dest
322f0 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 56 20 ructor D with V
32300 61 73 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 as its only argu
32310 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 ment.**
32320 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e when it has fin
32330 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 56 ished with the V
32340 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20 value..*/.void
32350 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
32360 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 lob(sqlite3_cont
32370 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ext*, const void
32380 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 *, int, void(*)(
32390 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 void*));.void sq
323a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 lite3_result_dou
323b0 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ble(sqlite3_cont
323c0 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 ext*, double);.v
323d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
323e0 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 lt_error(sqlite3
323f0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
32400 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f char*, int);.vo
32410 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
32420 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 t_error16(sqlite
32430 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
32440 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 t void*, int);.v
32450 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
32460 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 lt_error_toobig(
32470 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
32480 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
32490 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d result_error_nom
324a0 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 em(sqlite3_conte
324b0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 xt*);.void sqlit
324c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
324d0 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e code(sqlite3_con
324e0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 text*, int);.voi
324f0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
32500 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e _int(sqlite3_con
32510 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 text*, int);.voi
32520 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
32530 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 _int64(sqlite3_c
32540 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 ontext*, sqlite3
32550 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 _int64);.void sq
32560 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c lite3_result_nul
32570 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 l(sqlite3_contex
32580 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 t*);.void sqlite
32590 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 3_result_text(sq
325a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
325b0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 const char*, int
325c0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
325d0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
325e0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 result_text16(sq
325f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
32600 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
32610 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
32620 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
32630 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 result_text16le(
32640 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
32650 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
32660 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a nt,void(*)(void*
32670 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
32680 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 _result_text16be
32690 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
326a0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
326b0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 int,void(*)(void
326c0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 *));.void sqlite
326d0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 3_result_value(s
326e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
326f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 sqlite3_value*)
32700 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
32710 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 esult_zeroblob(s
32720 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
32730 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 int n);../*.**
32740 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 CAPI3REF: Define
32750 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 New Collating S
32760 65 71 75 65 6e 63 65 73 20 7b 46 31 36 36 30 30 equences {F16600
32770 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 }.**.** These fu
32780 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 nctions are used
32790 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c to add new coll
327a0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 ation sequences
327b0 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 to the.** [datab
327c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
327d0 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 specified as the
327e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e first argument.
327f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 .**.** The name
32800 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 of the new colla
32810 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 tion sequence is
32820 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20 specified as a
32830 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 UTF-8 string.**
32840 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 for sqlite3_crea
32850 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 te_collation() a
32860 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nd sqlite3_creat
32870 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 e_collation_v2()
32880 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 .** and a UTF-16
32890 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 string for sqli
328a0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
328b0 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c tion16(). In all
328c0 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 cases.** the na
328d0 6d 65 20 69 73 20 70 61 73 73 65 64 20 61 73 20 me is passed as
328e0 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 the second funct
328f0 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a ion argument..**
32900 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 .** The third ar
32910 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e gument may be on
32920 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e e of the constan
32930 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d ts [SQLITE_UTF8]
32940 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 ,.** [SQLITE_UTF
32950 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 16LE] or [SQLITE
32960 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 _UTF16BE], indic
32970 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 ating that the u
32980 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 ser-supplied.**
32990 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 routine expects
329a0 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 to be passed poi
329b0 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 nters to strings
329c0 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 encoded using U
329d0 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 TF-8,.** UTF-16
329e0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f little-endian, o
329f0 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 r UTF-16 big-end
32a00 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c ian, respectivel
32a10 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 y. The.** third
32a20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 argument might a
32a30 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 lso be [SQLITE_U
32a40 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f TF16_ALIGNED] to
32a50 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a indicate that.*
32a60 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78 * the routine ex
32a70 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 pects pointers t
32a80 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c o 16-bit word al
32a90 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a igned strings.**
32aa0 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68 of UTF-16 in th
32ab0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
32ac0 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 der of the host
32ad0 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 computer..**.**
32ae0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 A pointer to the
32af0 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 user supplied r
32b00 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 outine must be p
32b10 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66 assed as the fif
32b20 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 th.** argument.
32b30 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 If it is NULL,
32b40 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 this is the same
32b50 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 as deleting the
32b60 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 collation.** se
32b70 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 quence (so that
32b80 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 SQLite cannot ca
32b90 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a ll it anymore)..
32ba0 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 ** Each time the
32bb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 application sup
32bc0 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 plied function i
32bd0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 s invoked, it is
32be0 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 passed.** as it
32bf0 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 s first paramete
32c00 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 r a copy of the
32c10 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 void* passed as
32c20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d the fourth argum
32c30 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 ent.** to sqlite
32c40 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
32c50 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f on() or sqlite3_
32c60 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
32c70 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 16()..**.** The
32c80 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 remaining argume
32c90 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 nts to the appli
32ca0 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 cation-supplied
32cb0 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 routine are two
32cc0 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 strings,.** each
32cd0 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
32ce0 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 a (length, data)
32cf0 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 pair and encode
32d00 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e d in the encodin
32d10 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 g.** that was pa
32d20 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 ssed as the thir
32d30 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 d argument when
32d40 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 the collation se
32d50 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 quence was.** re
32d60 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 gistered. {END}
32d70 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
32d80 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 defined collati
32d90 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c on routine shoul
32da0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 d.** return nega
32db0 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f tive, zero or po
32dc0 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69 sitive if the fi
32dd0 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 rst string is le
32de0 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 ss than,.** equa
32df0 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 l to, or greater
32e00 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 than the second
32e10 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 string. i.e. (S
32e20 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 TRING1 - STRING2
32e30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )..**.** The sql
32e40 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
32e50 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 ation_v2() works
32e60 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 like sqlite3_cr
32e70 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 eate_collation()
32e80 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 .** except that
32e90 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 it takes an extr
32ea0 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 a argument which
32eb0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 is a destructor
32ec0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c for.** the coll
32ed0 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 ation. The dest
32ee0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 ructor is called
32ef0 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 when the collat
32f00 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f ion is.** destro
32f10 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 yed and is passe
32f20 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 d a copy of the
32f30 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
32f40 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a void* pointer.*
32f50 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 * of the sqlite3
32f60 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
32f70 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 n_v2()..** Colla
32f80 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f tions are destro
32f90 79 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 yed when they ar
32fa0 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 e overridden by
32fb0 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 later calls to t
32fc0 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 he.** collation
32fd0 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f creation functio
32fe0 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b ns or when the [
32ff0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
33000 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a ion] is closed.*
33010 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 * using [sqlite3
33020 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a _close()]..**.**
33030 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
33040 2a 2a 20 7b 46 31 36 36 30 33 7d 20 41 20 73 75 ** {F16603} A su
33050 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
33060 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
33070 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
33080 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c _collation_v2(B,
33090 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65 X,E,P,F,D)] inte
330a0 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 rface.**
330b0 20 20 72 65 67 69 73 74 65 72 73 20 66 75 6e 63 registers func
330c0 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20 63 6f tion F as the co
330d0 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f mparison functio
330e0 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 n used to.**
330f0 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20 implement
33100 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 74 collation X on t
33110 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
33120 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a nection] B for.*
33130 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 * datab
33140 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e 63 6f ases having enco
33150 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 ding E..**.** {F
33160 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20 75 6e 16604} SQLite un
33170 64 65 72 73 74 61 6e 64 73 20 74 68 65 20 58 20 derstands the X
33180 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
33190 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
331a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
331b0 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c on_v2(B,X,E,P,F,
331c0 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 D)] as a zero-te
331d0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 rminated.**
331e0 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e UTF-8 strin
331f0 67 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 g in which case
33200 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41 is ignored for A
33210 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73 20 SCII characters
33220 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 and.**
33230 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20 66 is significant f
33240 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61 or non-ASCII cha
33250 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b racters..**.** {
33260 46 31 36 36 30 36 7d 20 53 75 63 63 65 73 73 69 F16606} Successi
33270 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c ve calls to [sql
33280 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
33290 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 ation_v2(B,X,E,P
332a0 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 ,F,D)].**
332b0 20 20 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 with the same
332c0 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c 20 58 values for B, X
332d0 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72 69 64 , and E, overrid
332e0 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a e prior values.*
332f0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 50 2c * of P,
33300 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a F, and D..**.**
33310 20 7b 46 31 36 36 30 39 7d 20 49 66 20 74 68 65 {F16609} If the
33320 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 69 6e destructor D in
33330 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
33340 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c _collation_v2(B,
33350 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 X,E,P,F,D)].**
33360 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20 4e is not N
33370 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73 20 63 ULL then it is c
33380 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67 75 6d alled with argum
33390 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65 0a 2a ent P when the.*
333a0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 * colla
333b0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 ting function is
333c0 20 64 72 6f 70 70 65 64 20 62 79 20 53 51 4c 69 dropped by SQLi
333d0 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 te..**.** {F1661
333e0 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 2} A collating f
333f0 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 unction is dropp
33400 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 6f 76 ed when it is ov
33410 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 erloaded..**.**
33420 7b 46 31 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61 {F16615} A colla
33430 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 ting function is
33440 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 74 68 dropped when th
33450 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
33460 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ction.**
33470 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e is closed usin
33480 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 g [sqlite3_close
33490 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 ()]..**.** {F166
334a0 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65 72 20 18} The pointer
334b0 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 P in [sqlite3_cr
334c0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
334d0 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2(B,X,E,P,F,D)].
334e0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 70 ** is p
334f0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 assed through as
33500 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
33510 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6d 70 eter to the comp
33520 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 arison.**
33530 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f function F fo
33540 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 r all subsequent
33550 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 invocations of
33560 46 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 31 F..**.** {F16621
33570 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c } A call to [sql
33580 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
33590 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 ation(B,X,E,P,F)
335a0 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 ] is exactly.**
335b0 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d the sam
335c0 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b e as a call to [
335d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
335e0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77 ollation_v2()] w
335f0 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ith.**
33600 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 the same paramet
33610 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64 ers and a NULL d
33620 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a estructor..**.**
33630 20 7b 46 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77 {F16624} Follow
33640 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33 5f 63 ing a [sqlite3_c
33650 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
33660 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d v2(B,X,E,P,F,D)]
33670 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 ,.** SQ
33680 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 63 6f Lite uses the co
33690 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f mparison functio
336a0 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65 78 74 n F for all text
336b0 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 comparison.**
336c0 20 20 20 20 20 20 20 20 6f 70 65 72 61 74 69 6f operatio
336d0 6e 73 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 ns on the [datab
336e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
336f0 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73 B on text values
33700 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 that.**
33710 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74 use the collat
33720 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d ing sequence nam
33730 65 64 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 ed X..**.** {F16
33740 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 627} The [sqlite
33750 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
33760 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d on16(B,X,E,P,F)]
33770 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 0a works the same.
33780 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 5b ** as [
33790 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
337a0 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 ollation(B,X,E,P
337b0 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 ,F)] except that
337c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
337d0 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 collation name
337e0 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 X is understood
337f0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 as UTF-16 in nat
33800 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a ive byte order.*
33810 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 74 65 * inste
33820 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a ad of UTF-8..**.
33830 2a 2a 20 7b 46 31 36 36 33 30 7d 20 57 68 65 6e ** {F16630} When
33840 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72 multiple compar
33850 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61 ison functions a
33860 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 re available for
33870 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 the same.**
33880 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 collating
33890 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69 74 65 sequence, SQLite
338a0 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65 chooses the one
338b0 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e 63 6f whose text enco
338c0 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 ding.**
338d0 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 requires the le
338e0 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f ast amount of co
338f0 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68 nversion from th
33900 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 e default.**
33910 20 20 20 20 20 20 74 65 78 74 20 65 6e 63 6f 64 text encod
33920 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 ing of the datab
33930 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ase..*/.int sqli
33940 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
33950 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a tion(. sqlite3*
33960 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 , . const char
33970 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 *zName, . int e
33980 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 TextRep, . void
33990 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 *,. int(*xCompa
339a0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f re)(void*,int,co
339b0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f nst void*,int,co
339c0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e nst void*).);.in
339d0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
339e0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 _collation_v2(.
339f0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f sqlite3*, . co
33a00 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
33a10 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 . int eTextRep
33a20 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e , . void*,. in
33a30 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 t(*xCompare)(voi
33a40 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 d*,int,const voi
33a50 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 d*,int,const voi
33a60 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 d*),. void(*xDe
33a70 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b stroy)(void*).);
33a80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
33a90 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 ate_collation16(
33aa0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
33ab0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d const void *zNam
33ac0 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 e,. int eTextRe
33ad0 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 p, . void*,. i
33ae0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f nt(*xCompare)(vo
33af0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
33b00 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
33b10 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 id*).);../*.** C
33b20 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 API3REF: Collati
33b30 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 on Needed Callba
33b40 63 6b 73 20 7b 46 31 36 37 30 30 7d 0a 2a 2a 0a cks {F16700}.**.
33b50 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 ** To avoid havi
33b60 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 ng to register a
33b70 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 ll collation seq
33b80 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 uences before a
33b90 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 database.** can
33ba0 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c be used, a singl
33bb0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
33bc0 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 ion may be regis
33bd0 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a tered with the.*
33be0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
33bf0 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61 ection] to be ca
33c00 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e lled whenever an
33c10 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 undefined colla
33c20 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 tion.** sequence
33c30 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a is required..**
33c40 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 .** If the funct
33c50 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 ion is registere
33c60 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 d using the sqli
33c70 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
33c80 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 eded() API,.** t
33c90 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 hen it is passed
33ca0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e the names of un
33cb0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f defined collatio
33cc0 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 n sequences as s
33cd0 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 trings.** encode
33ce0 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 46 31 36 d in UTF-8. {F16
33cf0 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 703} If sqlite3_
33d00 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
33d10 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 16() is used,.**
33d20 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 the names are p
33d30 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 assed as UTF-16
33d40 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 in machine nativ
33d50 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a e byte order..**
33d60 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 A call to eithe
33d70 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 r function repla
33d80 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 ces any existing
33d90 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a callback..**.**
33da0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 When the callba
33db0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 ck is invoked, t
33dc0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
33dd0 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f t passed is a co
33de0 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 py.** of the sec
33df0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
33e00 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
33e10 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a n_needed() or.**
33e20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
33e30 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 on_needed16().
33e40 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
33e50 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 ent is the datab
33e60 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
33e70 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 n. The third ar
33e80 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 gument is one of
33e90 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 [SQLITE_UTF8],
33ea0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d [SQLITE_UTF16BE]
33eb0 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f ,.** or [SQLITE_
33ec0 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 UTF16LE], indica
33ed0 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 ting the most de
33ee0 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 sirable form of
33ef0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a the collation.**
33f00 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 sequence functi
33f10 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 on required. Th
33f20 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
33f30 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f er is the name o
33f40 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 f the.** require
33f50 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 d collation sequ
33f60 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ence..**.** The
33f70 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
33f80 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 n should registe
33f90 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f r the desired co
33fa0 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a llation using.**
33fb0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
33fc0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b _collation()], [
33fd0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
33fe0 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f ollation16()], o
33ff0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 r.** [sqlite3_cr
34000 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
34010 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 2()]..**.** INVA
34020 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 RIANTS:.**.** {F
34030 31 36 37 30 32 7d 20 41 20 73 75 63 63 65 73 73 16702} A success
34040 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
34050 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
34060 65 65 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a 2a eeded(D,P,F)].**
34070 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 or [sq
34080 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
34090 6e 65 65 64 65 64 31 36 28 44 2c 50 2c 46 29 5d needed16(D,P,F)]
340a0 20 63 61 75 73 65 73 0a 2a 2a 20 20 20 20 20 20 causes.**
340b0 20 20 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 the [databas
340c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 e connection] D
340d0 74 6f 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62 61 to invoke callba
340e0 63 6b 20 46 20 77 69 74 68 20 66 69 72 73 74 0a ck F with first.
340f0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 ** para
34100 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 meter P whenever
34110 20 69 74 20 6e 65 65 64 73 20 61 20 63 6f 6d 70 it needs a comp
34120 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 arison function
34130 66 6f 72 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 for a.**
34140 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 collating sequ
34150 65 6e 63 65 20 74 68 61 74 20 69 74 20 64 6f 65 ence that it doe
34160 73 20 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75 74 s not know about
34170 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 34 7d ..**.** {F16704}
34180 20 45 61 63 68 20 73 75 63 63 65 73 73 66 75 6c Each successful
34190 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
341a0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
341b0 65 64 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 ed()] or.**
341c0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f [sqlite3_co
341d0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 llation_needed16
341e0 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 ()] overrides th
341f0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 67 69 73 e callback regis
34200 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 tered.**
34210 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 on the same [d
34220 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
34230 6f 6e 5d 20 62 79 20 70 72 69 6f 72 20 63 61 6c on] by prior cal
34240 6c 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 ls to either.**
34250 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 interfa
34260 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 ce..**.** {F1670
34270 36 7d 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 6} The name of t
34280 68 65 20 72 65 71 75 65 73 74 65 64 20 63 6f 6c he requested col
34290 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 lating function
342a0 70 61 73 73 65 64 20 69 6e 20 74 68 65 0a 2a 2a passed in the.**
342b0 20 20 20 20 20 20 20 20 20 20 34 74 68 20 70 61 4th pa
342c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 rameter to the c
342d0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 20 55 54 allback is in UT
342e0 46 2d 38 20 69 66 20 74 68 65 20 63 61 6c 6c 62 F-8 if the callb
342f0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ack.**
34300 77 61 73 20 72 65 67 69 73 74 65 72 65 64 20 75 was registered u
34310 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f sing [sqlite3_co
34320 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 llation_needed()
34330 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 ] and.**
34340 20 20 69 73 20 69 6e 20 55 54 46 2d 31 36 20 6e is in UTF-16 n
34350 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
34360 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b if the callback
34370 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 was.**
34380 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e registered usin
34390 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 g [sqlite3_colla
343a0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d tion_needed16()]
343b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
343c0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 _collation_neede
343d0 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a d(. sqlite3*, .
343e0 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 void*, . void
343f0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 (*)(void*,sqlite
34400 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 3*,int eTextRep,
34410 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a const char*).);.
34420 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c int sqlite3_coll
34430 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a ation_needed16(.
34440 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 sqlite3*, . v
34450 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 oid*,. void(*)(
34460 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 void*,sqlite3*,i
34470 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 nt eTextRep,cons
34480 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a t void*).);../*.
34490 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b ** Specify the k
344a0 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 ey for an encryp
344b0 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 ted database. T
344c0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 his routine shou
344d0 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 ld be.** called
344e0 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 right after sqli
344f0 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a te3_open()..**.*
34500 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d * The code to im
34510 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 plement this API
34520 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c is not availabl
34530 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 e in the public
34540 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 release.** of SQ
34550 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c Lite..*/.int sql
34560 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 ite3_key(. sqli
34570 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
34580 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
34590 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b tabase to be rek
345a0 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 eyed */. const
345b0 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 void *pKey, int
345c0 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 nKey /* The
345d0 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a key */.);../*.**
345e0 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 Change the key
345f0 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 on an open datab
34600 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 ase. If the cur
34610 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 rent database is
34620 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 not.** encrypte
34630 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 d, this routine
34640 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e will encrypt it.
34650 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 If pNew==0 or
34660 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 nNew==0, the.**
34670 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 database is decr
34680 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ypted..**.** The
34690 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 code to impleme
346a0 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e nt this API is n
346b0 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 ot available in
346c0 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 the public relea
346d0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e se.** of SQLite.
346e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
346f0 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 rekey(. sqlite3
34700 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
34710 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
34720 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 ase to be rekeye
34730 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 d */. const voi
34740 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 d *pKey, int nKe
34750 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 y /* The new
34760 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a key */.);../*.*
34770 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 * CAPI3REF: Susp
34780 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f end Execution Fo
34790 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b r A Short Time {
347a0 46 31 30 35 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 F10530}.**.** Th
347b0 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 e sqlite3_sleep(
347c0 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 ) function cause
347d0 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 s the current th
347e0 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 read to suspend
347f0 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 execution.** for
34800 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 at least a numb
34810 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e er of millisecon
34820 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 ds specified in
34830 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a its parameter..*
34840 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 *.** If the oper
34850 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 ating system doe
34860 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c s not support sl
34870 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 eep requests wit
34880 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 h.** millisecond
34890 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e time resolution
348a0 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 , then the time
348b0 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 will be rounded
348c0 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 up to.** the nea
348d0 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 rest second. The
348e0 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 number of milli
348f0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 seconds of sleep
34900 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 actually.** req
34910 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 uested from the
34920 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
34930 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
34940 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 .** SQLite imple
34950 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 ments this inter
34960 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 face by calling
34970 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 the xSleep().**
34980 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 method of the de
34990 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 fault [sqlite3_v
349a0 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a fs] object..**.*
349b0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
349c0 0a 2a 2a 20 7b 46 31 30 35 33 33 7d 20 54 68 65 .** {F10533} The
349d0 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 [sqlite3_sleep(
349e0 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 6e M)] interface in
349f0 76 6f 6b 65 73 20 74 68 65 20 78 53 6c 65 65 70 vokes the xSleep
34a00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 74 .** met
34a10 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 hod of the defau
34a20 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c lt [sqlite3_vfs|
34a30 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f VFS] in order to
34a40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 73 .** sus
34a50 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 20 6f pend execution o
34a60 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 f the current th
34a70 72 65 61 64 20 66 6f 72 20 61 74 20 6c 65 61 73 read for at leas
34a80 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d 20 t.** M
34a90 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a milliseconds..**
34aa0 0a 2a 2a 20 7b 46 31 30 35 33 36 7d 20 54 68 65 .** {F10536} The
34ab0 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 [sqlite3_sleep(
34ac0 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 M)] interface re
34ad0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
34ae0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 of.**
34af0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 milliseconds of
34b00 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 72 sleep actually r
34b10 65 71 75 65 73 74 65 64 20 6f 66 20 74 68 65 20 equested of the
34b20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20 operating.**
34b30 20 20 20 20 20 20 73 79 73 74 65 6d 2c 20 77 68 system, wh
34b40 69 63 68 20 6d 69 67 68 74 20 62 65 20 6c 61 72 ich might be lar
34b50 67 65 72 20 74 68 61 6e 20 74 68 65 20 70 61 72 ger than the par
34b60 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 ameter M..*/.int
34b70 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 sqlite3_sleep(i
34b80 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
34b90 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 3REF: Name Of Th
34ba0 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 e Folder Holding
34bb0 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 Temporary Files
34bc0 20 7b 46 31 30 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 {F10310}.**.**
34bd0 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 If this global v
34be0 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 ariable is made
34bf0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 to point to a st
34c00 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a ring which is.**
34c10 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 the name of a f
34c20 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 older (a.k.a. di
34c30 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 rectory), then a
34c40 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c ll temporary fil
34c50 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 es.** created by
34c60 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 SQLite will be
34c70 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 placed in that d
34c80 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68 irectory. If th
34c90 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 is variable.** i
34ca0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
34cb0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 , then SQLite pe
34cc0 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 rforms a search
34cd0 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 for an appropria
34ce0 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 te.** temporary
34cf0 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a file directory..
34d00 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 **.** It is not
34d10 73 61 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74 safe to modify t
34d20 68 69 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63 his variable onc
34d30 65 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f e a [database co
34d40 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 68 61 73 nnection].** has
34d50 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49 been opened. I
34d60 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 t is intended th
34d70 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 at this variable
34d80 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 be set once.**
34d90 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 as part of proce
34da0 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ss initializatio
34db0 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 n and before any
34dc0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
34dd0 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 e.** routines ha
34de0 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64 ve been call and
34df0 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 remain unchange
34e00 64 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f d thereafter..*/
34e10 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 .SQLITE_EXTERN c
34e20 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d har *sqlite3_tem
34e30 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a p_directory;../*
34e40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 .** CAPI3REF: Te
34e50 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 st To See If The
34e60 20 44 61 74 61 62 61 73 65 20 49 73 20 49 6e 20 Database Is In
34e70 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 Auto-Commit Mode
34e80 20 7b 46 31 32 39 33 30 7d 0a 2a 2a 20 4b 45 59 {F12930}.** KEY
34e90 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d WORDS: {autocomm
34ea0 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 it mode}.**.** T
34eb0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 he sqlite3_get_a
34ec0 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 utocommit() inte
34ed0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f rface returns no
34ee0 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 n-zero or.** zer
34ef0 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 o if the given d
34f00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
34f10 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 on is or is not
34f20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f in autocommit mo
34f30 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 de,.** respectiv
34f40 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 ely. Autocommit
34f50 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 mode is on by d
34f60 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63 efault..** Autoc
34f70 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 ommit mode is di
34f80 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 sabled by a [BEG
34f90 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a IN] statement..*
34fa0 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 * Autocommit mod
34fb0 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 e is re-enabled
34fc0 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 by a [COMMIT] or
34fd0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a [ROLLBACK]..**.
34fe0 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 ** If certain ki
34ff0 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 nds of errors oc
35000 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 cur on a stateme
35010 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 nt within a mult
35020 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 i-statement.** t
35030 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f ransaction (erro
35040 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 rs including [SQ
35050 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c LITE_FULL], [SQL
35060 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b ITE_IOERR],.** [
35070 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b SQLITE_NOMEM], [
35080 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e SQLITE_BUSY], an
35090 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 d [SQLITE_INTERR
350a0 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a UPT]) then the.*
350b0 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 * transaction mi
350c0 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 ght be rolled ba
350d0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ck automatically
350e0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 . The only way
350f0 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 to.** find out w
35100 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 hether SQLite au
35110 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c tomatically roll
35120 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e ed back the tran
35130 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a saction after.**
35140 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 an error is to
35150 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f use this functio
35160 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 n..**.** INVARIA
35170 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 NTS:.**.** {F129
35180 33 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 31} The [sqlite3
35190 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 _get_autocommit(
351a0 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 D)] interface re
351b0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f turns non-zero o
351c0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 r.** ze
351d0 72 6f 20 69 66 20 74 68 65 20 5b 64 61 74 61 62 ro if the [datab
351e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
351f0 44 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 D is or is not i
35200 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 n autocommit.**
35210 20 20 20 20 20 20 20 20 20 6d 6f 64 65 2c 20 72 mode, r
35220 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a espectively..**.
35230 2a 2a 20 7b 46 31 32 39 33 32 7d 20 41 75 74 6f ** {F12932} Auto
35240 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f commit mode is o
35250 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a n by default..**
35260 0a 2a 2a 20 7b 46 31 32 39 33 33 7d 20 41 75 74 .** {F12933} Aut
35270 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 ocommit mode is
35280 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 73 75 disabled by a su
35290 63 63 65 73 73 66 75 6c 20 5b 42 45 47 49 4e 5d ccessful [BEGIN]
352a0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a statement..**.*
352b0 2a 20 7b 46 31 32 39 33 34 7d 20 41 75 74 6f 63 * {F12934} Autoc
352c0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 65 6e ommit mode is en
352d0 61 62 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 abled by a succe
352e0 73 73 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d 20 6f ssful [COMMIT] o
352f0 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 r [ROLLBACK].**
35300 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 stateme
35310 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 nt..**.** LIMITA
35320 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 TIONS:.**.** {A1
35330 32 39 33 36 7d 20 49 66 20 61 6e 6f 74 68 65 72 2936} If another
35340 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 thread changes
35350 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 the autocommit s
35360 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 tatus of the dat
35370 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 abase.**
35380 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 connection whi
35390 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 le this routine
353a0 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e is running, then
353b0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
353c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 e.** is
353d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 undefined..*/.i
353e0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 nt sqlite3_get_a
353f0 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 utocommit(sqlite
35400 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
35410 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 3REF: Find The D
35420 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f atabase Handle O
35430 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 f A Prepared Sta
35440 74 65 6d 65 6e 74 20 7b 46 31 33 31 32 30 7d 0a tement {F13120}.
35450 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
35460 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 3_db_handle inte
35470 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
35480 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
35490 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a ection] handle.*
354a0 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 * to which a [pr
354b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
354c0 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 54 68 65 20 ] belongs. The
354d0 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 database handle
354e0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 73 returned by.** s
354f0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 qlite3_db_handle
35500 20 69 73 20 74 68 65 20 73 61 6d 65 20 64 61 74 is the same dat
35510 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68 61 abase handle tha
35520 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74 20 t was the first
35530 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 argument.** to t
35540 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 he [sqlite3_prep
35550 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 are_v2()] call (
35560 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 or its variants)
35570 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74 that was used t
35580 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 o.** create the
35590 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 statement in the
355a0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a first place..**
355b0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
355c0 2a 2a 0a 2a 2a 20 7b 46 31 33 31 32 33 7d 20 54 **.** {F13123} T
355d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 68 he [sqlite3_db_h
355e0 61 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65 72 66 andle(S)] interf
355f0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
35600 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 inter.**
35610 20 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 to the [databa
35620 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
35630 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
35640 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
35650 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
35660 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71 6c 69 74 65 nt] S..*/.sqlite
35670 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 3 *sqlite3_db_ha
35680 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d ndle(sqlite3_stm
35690 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
356a0 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 3REF: Find the n
356b0 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61 ext prepared sta
356c0 74 65 6d 65 6e 74 20 7b 46 31 33 31 34 30 7d 0a tement {F13140}.
356d0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
356e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
356f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 ointer to the ne
35700 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 xt [prepared sta
35710 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a tement] after.**
35720 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 pStmt associate
35730 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 d with the [data
35740 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
35750 20 70 44 62 2e 20 20 49 66 20 70 53 74 6d 74 20 pDb. If pStmt
35760 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 is NULL.** then
35770 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 this interface r
35780 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
35790 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 to the first pr
357a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
357b0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 .** associated w
357c0 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 ith the database
357d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e connection pDb.
357e0 20 20 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 If no prepared
357f0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 statement.** sa
35800 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 tisfies the cond
35810 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 itions of this r
35820 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 outine, it retur
35830 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 ns NULL..**.** I
35840 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
35850 20 7b 46 31 33 31 34 33 7d 20 49 66 20 44 20 69 {F13143} If D i
35860 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f s a [database co
35870 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 nnection] that h
35880 6f 6c 64 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 olds one or more
35890 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 66 .** unf
358a0 69 6e 61 6c 69 7a 65 64 20 5b 70 72 65 70 61 72 inalized [prepar
358b0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 ed statements] a
358c0 6e 64 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 nd S is a NULL p
358d0 6f 69 6e 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20 ointer,.**
358e0 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 then [sqlite
358f0 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 3_next_stmt(D, S
35900 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c )] routine shall
35910 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 return a pointe
35920 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f r.** to
35930 20 6f 6e 65 20 6f 66 20 74 68 65 20 70 72 65 70 one of the prep
35940 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 ared statements
35950 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
35960 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 34 36 D..**.** {F13146
35970 7d 20 49 66 20 44 20 69 73 20 61 20 5b 64 61 74 } If D is a [dat
35980 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
35990 5d 20 74 68 61 74 20 68 6f 6c 64 73 20 6e 6f 20 ] that holds no
359a0 75 6e 66 69 6e 61 6c 69 7a 65 64 0a 2a 2a 20 20 unfinalized.**
359b0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 [prepare
359c0 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e d statements] an
359d0 64 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f d S is a NULL po
359e0 69 6e 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 inter, then.**
359f0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
35a00 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 _next_stmt(D, S)
35a10 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 ] routine shall
35a20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f return a NULL po
35a30 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 inter..**.** {F1
35a40 33 31 34 39 7d 20 49 66 20 53 20 69 73 20 61 20 3149} If S is a
35a50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
35a60 65 6e 74 5d 20 69 6e 20 74 68 65 20 5b 64 61 74 ent] in the [dat
35a70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
35a80 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ] D.**
35a90 61 6e 64 20 53 20 69 73 20 6e 6f 74 20 74 68 65 and S is not the
35aa0 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73 last prepared s
35ab0 74 61 74 65 6d 65 6e 74 20 69 6e 20 44 2c 20 74 tatement in D, t
35ac0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hen.**
35ad0 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 [sqlite3_next_st
35ae0 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e mt(D, S)] routin
35af0 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 e shall return a
35b00 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 pointer.**
35b10 20 20 20 20 20 74 6f 20 74 68 65 20 6e 65 78 74 to the next
35b20 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
35b30 65 6e 74 20 69 6e 20 44 20 61 66 74 65 72 20 53 ent in D after S
35b40 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 35 32 7d ..**.** {F13152}
35b50 20 49 66 20 53 20 69 73 20 74 68 65 20 6c 61 73 If S is the las
35b60 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 t [prepared stat
35b70 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65 0a 2a 2a ement] in the.**
35b80 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 [datab
35b90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
35ba0 44 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 D then the [sqli
35bb0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c te3_next_stmt(D,
35bc0 20 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 S)].**
35bd0 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 routine shall r
35be0 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 eturn a NULL poi
35bf0 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 nter..*/.sqlite3
35c00 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e _stmt *sqlite3_n
35c10 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 ext_stmt(sqlite3
35c20 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 *pDb, sqlite3_s
35c30 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
35c40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
35c50 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 mmit And Rollbac
35c60 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 k Notification C
35c70 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39 35 30 allbacks {F12950
35c80 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 }.**.** The sqli
35c90 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 te3_commit_hook(
35ca0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ) interface regi
35cb0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b sters a callback
35cc0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 .** function to
35cd0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 be invoked whene
35ce0 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f ver a transactio
35cf0 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a n is committed..
35d00 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 ** Any callback
35d10 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 set by a previou
35d20 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 s call to sqlite
35d30 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 3_commit_hook().
35d40 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 ** for the same
35d50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
35d60 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 ion is overridde
35d70 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 n..** The sqlite
35d80 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 3_rollback_hook(
35d90 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ) interface regi
35da0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b sters a callback
35db0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 .** function to
35dc0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 be invoked whene
35dd0 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f ver a transactio
35de0 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a n is committed..
35df0 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 ** Any callback
35e00 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 set by a previou
35e10 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 s call to sqlite
35e20 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 3_commit_hook().
35e30 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 ** for the same
35e40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
35e50 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 ion is overridde
35e60 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67 20 61 n..** The pArg a
35e70 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 rgument is passe
35e80 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 d through to the
35e90 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 49 66 callback..** If
35ea0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e the callback on
35eb0 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 a commit hook f
35ec0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
35ed0 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 non-zero,.** the
35ee0 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 n the commit is
35ef0 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 converted into a
35f00 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a rollback..**.**
35f10 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 If another func
35f20 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 tion was previou
35f30 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 sly registered,
35f40 69 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 its.** pArg valu
35f50 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 e is returned.
35f60 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 Otherwise NULL i
35f70 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
35f80 2a 20 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 * Registering a
35f90 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 NULL function di
35fa0 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 sables the callb
35fb0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 ack..**.** For t
35fc0 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 he purposes of t
35fd0 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 his API, a trans
35fe0 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 action is said t
35ff0 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 o have been.** r
36000 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e olled back if an
36010 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 explicit "ROLLB
36020 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 ACK" statement i
36030 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a s executed, or.*
36040 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f * an error or co
36050 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 nstraint causes
36060 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c an implicit roll
36070 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a back to occur..*
36080 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 * The rollback c
36090 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 allback is not i
360a0 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e nvoked if a tran
360b0 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 saction is.** au
360c0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c tomatically roll
360d0 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 ed back because
360e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
360f0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 nection is close
36100 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 d..** The rollba
36110 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e ck callback is n
36120 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 ot invoked if a
36130 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a transaction is.*
36140 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 * rolled back be
36150 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63 cause a commit c
36160 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64 allback returned
36170 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 non-zero..** <t
36180 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68 odo> Check on th
36190 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a is </todo>.**.**
361a0 20 54 68 65 73 65 20 61 72 65 20 65 78 70 65 72 These are exper
361b0 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 imental interfac
361c0 65 73 20 61 6e 64 20 61 72 65 20 73 75 62 6a 65 es and are subje
361d0 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2a ct to change..**
361e0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
361f0 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 31 7d 20 54 **.** {F12951} T
36200 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d he [sqlite3_comm
36210 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 it_hook(D,F,P)]
36220 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
36230 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ers the.**
36240 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e callback fun
36250 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e ction F to be in
36260 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d voked with argum
36270 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a ent P whenever.*
36280 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61 * a tra
36290 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 nsaction commits
362a0 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 on the [databas
362b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e e connection] D.
362c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 32 7d 20 .**.** {F12952}
362d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d The [sqlite3_com
362e0 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d mit_hook(D,F,P)]
362f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
36300 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e ns the P argumen
36310 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 t.** fr
36320 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 om the previous
36330 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61 call with the sa
36340 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e me [database con
36350 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 nection] D,.**
36360 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 or NULL
36370 6f 6e 20 74 68 65 20 66 69 72 73 74 20 63 61 6c on the first cal
36380 6c 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c l for a particul
36390 61 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ar database conn
363a0 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 ection D..**.**
363b0 7b 46 31 32 39 35 33 7d 20 45 61 63 68 20 63 61 {F12953} Each ca
363c0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
363d0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76 ommit_hook()] ov
363e0 65 72 77 72 69 74 65 73 20 74 68 65 20 63 61 6c erwrites the cal
363f0 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 lback.**
36400 20 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 registered by
36410 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a prior calls..**.
36420 2a 2a 20 7b 46 31 32 39 35 34 7d 20 49 66 20 74 ** {F12954} If t
36430 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f he F argument to
36440 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 [sqlite3_commit
36450 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 _hook(D,F,P)] is
36460 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 NULL.**
36470 20 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 then the commi
36480 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 t hook callback
36490 69 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 is canceled and
364a0 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 no callback.**
364b0 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b is invok
364c0 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 ed when a transa
364d0 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a ction commits..*
364e0 2a 0a 2a 2a 20 7b 46 31 32 39 35 35 7d 20 49 66 *.** {F12955} If
364f0 20 74 68 65 20 63 6f 6d 6d 69 74 20 63 61 6c 6c the commit call
36500 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e back returns non
36510 2d 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20 63 -zero then the c
36520 6f 6d 6d 69 74 20 69 73 0a 2a 2a 20 20 20 20 20 ommit is.**
36530 20 20 20 20 20 63 6f 6e 76 65 72 74 65 64 20 69 converted i
36540 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a nto a rollback..
36550 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 31 7d 20 54 **.** {F12961} T
36560 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c he [sqlite3_roll
36570 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 back_hook(D,F,P)
36580 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ] interface regi
36590 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 sters the.**
365a0 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 callback f
365b0 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 unction F to be
365c0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 invoked with arg
365d0 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 ument P whenever
365e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 .** a t
365f0 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 ransaction rolls
36600 20 62 61 63 6b 20 6f 6e 20 74 68 65 20 5b 64 61 back on the [da
36610 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
36620 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 n] D..**.** {F12
36630 39 36 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 962} The [sqlite
36640 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 3_rollback_hook(
36650 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 D,F,P)] interfac
36660 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 0a e returns the P.
36670 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75 ** argu
36680 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 ment from the pr
36690 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 evious call with
366a0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 the same.**
366b0 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 [database
366c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f connection] D, o
366d0 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 r NULL on the fi
366e0 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 rst call.**
366f0 20 20 20 20 20 66 6f 72 20 61 20 70 61 72 74 69 for a parti
36700 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 63 cular database c
36710 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a onnection D..**.
36720 2a 2a 20 7b 46 31 32 39 36 33 7d 20 45 61 63 68 ** {F12963} Each
36730 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
36740 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 3_rollback_hook(
36750 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 )] overwrites th
36760 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 e callback.**
36770 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 registere
36780 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 d by prior calls
36790 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 34 7d ..**.** {F12964}
367a0 20 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 If the F argume
367b0 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 nt to [sqlite3_r
367c0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 ollback_hook(D,F
367d0 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 ,P)] is NULL.**
367e0 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 then th
367f0 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 e rollback hook
36800 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 callback is canc
36810 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c eled and no call
36820 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 back.**
36830 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e is invoked when
36840 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 a transaction r
36850 6f 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76 6f olls back..*/.vo
36860 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d id *sqlite3_comm
36870 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a it_hook(sqlite3*
36880 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c , int(*)(void*),
36890 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 void*);.void *s
368a0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f qlite3_rollback_
368b0 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 hook(sqlite3*, v
368c0 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 oid(*)(void *),
368d0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
368e0 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 API3REF: Data Ch
368f0 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f ange Notificatio
36900 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 n Callbacks {F12
36910 39 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 970}.**.** The s
36920 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f qlite3_update_ho
36930 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ok() interface r
36940 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 egisters a callb
36950 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ack function.**
36960 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 with the [databa
36970 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
36980 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 dentified by the
36990 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a first argument.
369a0 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 ** to be invoked
369b0 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 whenever a row
369c0 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 is updated, inse
369d0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e rted or deleted.
369e0 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b .** Any callback
369f0 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f set by a previo
36a00 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 us call to this
36a10 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 function.** for
36a20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
36a30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
36a40 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a overridden..**.*
36a50 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 * The second arg
36a60 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
36a70 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 er to the functi
36a80 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 on to invoke whe
36a90 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 n a.** row is up
36aa0 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 dated, inserted
36ab0 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 54 or deleted..** T
36ac0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
36ad0 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 t to the callbac
36ae0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 k is a copy of t
36af0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
36b00 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f t.** to sqlite3_
36b10 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a update_hook()..*
36b20 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c * The second cal
36b30 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 lback argument i
36b40 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 s one of [SQLITE
36b50 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 _INSERT], [SQLIT
36b60 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 E_DELETE],.** or
36b70 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d [SQLITE_UPDATE]
36b80 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 , depending on t
36b90 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 he operation tha
36ba0 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c t caused the cal
36bb0 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 lback.** to be i
36bc0 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74 nvoked..** The t
36bd0 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 hird and fourth
36be0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 arguments to the
36bf0 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 callback contai
36c00 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 n pointers to th
36c10 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e e.** database an
36c20 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e d table name con
36c30 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 taining the affe
36c40 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 cted row..** The
36c50 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 final callback
36c60 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
36c70 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f rowid of the ro
36c80 77 2e 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f w. In the case o
36c90 66 0a 2a 2a 20 61 6e 20 75 70 64 61 74 65 2c 20 f.** an update,
36ca0 74 68 69 73 20 69 73 20 74 68 65 20 72 6f 77 69 this is the rowi
36cb0 64 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61 d after the upda
36cc0 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a te takes place..
36cd0 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 **.** The update
36ce0 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 hook is not inv
36cf0 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e oked when intern
36d00 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 al system tables
36d10 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 are.** modified
36d20 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 (i.e. sqlite_ma
36d30 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f ster and sqlite_
36d40 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a sequence)..**.**
36d50 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 If another func
36d60 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 tion was previou
36d70 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 sly registered,
36d80 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a its pArg value.*
36d90 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 * is returned.
36da0 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 Otherwise NULL i
36db0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
36dc0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
36dd0 0a 2a 2a 20 7b 46 31 32 39 37 31 7d 20 54 68 65 .** {F12971} The
36de0 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 [sqlite3_update
36df0 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e _hook(D,F,P)] in
36e00 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 terface causes t
36e10 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 he callback.**
36e20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e function
36e30 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 F to be invoked
36e40 20 77 69 74 68 20 66 69 72 73 74 20 70 61 72 61 with first para
36e50 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 meter P whenever
36e60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 .** a t
36e70 61 62 6c 65 20 72 6f 77 20 69 73 20 6d 6f 64 69 able row is modi
36e80 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 2c 20 fied, inserted,
36e90 6f 72 20 64 65 6c 65 74 65 64 20 6f 6e 0a 2a 2a or deleted on.**
36ea0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64 the [d
36eb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
36ec0 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 on] D..**.** {F1
36ed0 32 39 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 2973} The [sqlit
36ee0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 e3_update_hook(D
36ef0 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 ,F,P)] interface
36f00 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c returns the val
36f10 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f ue.** o
36f20 66 20 50 20 66 6f 72 20 74 68 65 20 70 72 65 76 f P for the prev
36f30 69 6f 75 73 20 63 61 6c 6c 20 6f 6e 20 74 68 65 ious call on the
36f40 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 same [database
36f50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a connection] D,.*
36f60 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 * or NU
36f70 4c 4c 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 LL for the first
36f80 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 call..**.** {F1
36f90 32 39 37 35 7d 20 49 66 20 74 68 65 20 75 70 64 2975} If the upd
36fa0 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 ate hook callbac
36fb0 6b 20 46 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f k F in [sqlite3_
36fc0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c update_hook(D,F,
36fd0 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 P)].**
36fe0 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 is NULL then the
36ff0 20 6e 6f 20 75 70 64 61 74 65 20 63 61 6c 6c 62 no update callb
37000 61 63 6b 73 20 61 72 65 20 6d 61 64 65 2e 0a 2a acks are made..*
37010 2a 0a 2a 2a 20 7b 46 31 32 39 37 37 7d 20 45 61 *.** {F12977} Ea
37020 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ch call to [sqli
37030 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 te3_update_hook(
37040 44 2c 46 2c 50 29 5d 20 6f 76 65 72 72 69 64 65 D,F,P)] override
37050 73 20 70 72 69 6f 72 20 63 61 6c 6c 73 0a 2a 2a s prior calls.**
37060 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 to the
37070 20 73 61 6d 65 20 69 6e 74 65 72 66 61 63 65 20 same interface
37080 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 on the same [dat
37090 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
370a0 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 ] D..**.** {F129
370b0 37 39 7d 20 54 68 65 20 75 70 64 61 74 65 20 68 79} The update h
370c0 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ook callback is
370d0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e not invoked when
370e0 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d internal system
370f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 61 62 .** tab
37100 6c 65 73 20 73 75 63 68 20 61 73 20 73 71 6c 69 les such as sqli
37110 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 te_master and sq
37120 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 20 61 72 lite_sequence ar
37130 65 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a e modified..**.*
37140 2a 20 7b 46 31 32 39 38 31 7d 20 54 68 65 20 73 * {F12981} The s
37150 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
37160 74 6f 20 74 68 65 20 75 70 64 61 74 65 20 63 61 to the update ca
37170 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 llback.**
37180 20 20 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 is one of [SQ
37190 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 LITE_INSERT], [S
371a0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72 QLITE_DELETE] or
371b0 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d [SQLITE_UPDATE]
371c0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 ,.** de
371d0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f pending on the o
371e0 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 peration that ca
371f0 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 used the callbac
37200 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e k to be invoked.
37210 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 33 7d 20 .**.** {F12983}
37220 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f The third and fo
37230 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 urth arguments t
37240 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 o the callback c
37250 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 0a ontain pointers.
37260 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 7a ** to z
37270 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
37280 54 46 2d 38 20 73 74 72 69 6e 67 73 20 77 68 69 TF-8 strings whi
37290 63 68 20 61 72 65 20 74 68 65 20 6e 61 6d 65 73 ch are the names
372a0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 of the.**
372b0 20 20 20 20 64 61 74 61 62 61 73 65 20 61 6e 64 database and
372c0 20 74 61 62 6c 65 20 74 68 61 74 20 69 73 20 62 table that is b
372d0 65 69 6e 67 20 75 70 64 61 74 65 64 2e 0a 0a 2a eing updated...*
372e0 2a 20 7b 46 31 32 39 38 35 7d 20 54 68 65 20 66 * {F12985} The f
372f0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 inal callback pa
37300 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 72 rameter is the r
37310 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77 20 owid of the row
37320 61 66 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 after.**
37330 20 20 74 68 65 20 63 68 61 6e 67 65 20 6f 63 63 the change occ
37340 75 72 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 urs..*/.void *sq
37350 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f lite3_update_hoo
37360 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a k(. sqlite3*, .
37370 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a void(*)(void *
37380 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 ,int ,char const
37390 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c *,char const *,
373a0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a sqlite3_int64),.
373b0 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a void*.);../*.*
373c0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 * CAPI3REF: Enab
373d0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 le Or Disable Sh
373e0 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 ared Pager Cache
373f0 20 7b 46 31 30 33 33 30 7d 0a 2a 2a 20 4b 45 59 {F10330}.** KEY
37400 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63 WORDS: {shared c
37410 61 63 68 65 7d 20 7b 73 68 61 72 65 64 20 63 61 ache} {shared ca
37420 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 che mode}.**.**
37430 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 This routine ena
37440 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 bles or disables
37450 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 the sharing of
37460 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63 the database cac
37470 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 he.** and schema
37480 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 data structures
37490 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 between [databa
374a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 se connection |
374b0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 connections].**
374c0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 to the same data
374d0 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 base. Sharing is
374e0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 enabled if the
374f0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 argument is true
37500 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 .** and disabled
37510 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 if the argument
37520 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a is false..**.**
37530 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 Cache sharing i
37540 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 s enabled and di
37550 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e sabled for an en
37560 74 69 72 65 20 70 72 6f 63 65 73 73 2e 20 7b 45 tire process. {E
37570 4e 44 7d 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 ND}.** This is a
37580 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 change as of SQ
37590 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
375a0 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 .0. In prior ver
375b0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c sions of SQLite,
375c0 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 .** sharing was
375d0 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 enabled or disab
375e0 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 led for each thr
375f0 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a ead separately..
37600 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20 **.** The cache
37610 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 sharing mode set
37620 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 by this interfa
37630 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 ce effects all s
37640 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c ubsequent.** cal
37650 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f ls to [sqlite3_o
37660 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
37670 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 _open_v2()], and
37680 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
37690 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 ()]..** Existing
376a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
376b0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 tions continue u
376c0 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d se the sharing m
376d0 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 ode.** that was
376e0 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65 in effect at the
376f0 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 time they were
37700 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 opened..**.** Vi
37710 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e rtual tables can
37720 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69 74 68 not be used with
37730 20 61 20 73 68 61 72 65 64 20 63 61 63 68 65 2e a shared cache.
37740 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a When shared.**
37750 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 cache is enable
37760 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f d, the [sqlite3_
37770 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d create_module()]
37780 20 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 API used to reg
37790 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c ister.** virtual
377a0 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 tables will alw
377b0 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 ays return an er
377c0 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ror..**.** This
377d0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
377e0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 [SQLITE_OK] if s
377f0 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73 20 hared cache was
37800 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 enabled or disab
37810 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 led.** successfu
37820 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 lly. An [error
37830 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
37840 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a d otherwise..**.
37850 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65 20 ** Shared cache
37860 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 is disabled by d
37870 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 efault. But this
37880 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e might change in
37890 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 .** future relea
378a0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 ses of SQLite.
378b0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
378c0 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 t care about sha
378d0 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 red.** cache set
378e0 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 ting should set
378f0 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a it explicitly..*
37900 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
37910 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 31 7d 20 .**.** {F10331}
37920 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 A successful inv
37930 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 ocation of [sqli
37940 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 te3_enable_share
37950 64 5f 63 61 63 68 65 28 42 29 5d 0a 2a 2a 20 20 d_cache(B)].**
37960 20 20 20 20 20 20 20 20 77 69 6c 6c 20 65 6e 61 will ena
37970 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 73 ble or disable s
37980 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 hared cache mode
37990 20 66 6f 72 20 61 6e 79 20 73 75 62 73 65 71 75 for any subsequ
379a0 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 ently.**
379b0 20 20 63 72 65 61 74 65 64 20 5b 64 61 74 61 62 created [datab
379c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
379d0 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 in the same proc
379e0 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 ess..**.** {F103
379f0 33 36 7d 20 57 68 65 6e 20 73 68 61 72 65 64 20 36} When shared
37a00 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 cache is enabled
37a10 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 , the [sqlite3_c
37a20 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 0a reate_module()].
37a30 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 ** inte
37a40 72 66 61 63 65 20 77 69 6c 6c 20 61 6c 77 61 79 rface will alway
37a50 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f s return an erro
37a60 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 37 r..**.** {F10337
37a70 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 } The [sqlite3_e
37a80 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 nable_shared_cac
37a90 68 65 28 42 29 5d 20 69 6e 74 65 72 66 61 63 65 he(B)] interface
37aa0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 returns.**
37ab0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d [SQLITE_OK]
37ac0 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 if shared cache
37ad0 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 was enabled or
37ae0 64 69 73 61 62 6c 65 64 20 73 75 63 63 65 73 73 disabled success
37af0 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 fully..**.** {F1
37b00 30 33 33 39 7d 20 53 68 61 72 65 64 20 63 61 63 0339} Shared cac
37b10 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 he is disabled b
37b20 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69 6e y default..*/.in
37b30 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 t sqlite3_enable
37b40 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e _shared_cache(in
37b50 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
37b60 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 REF: Attempt To
37b70 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 Free Heap Memory
37b80 20 7b 46 31 37 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 {F17340}.**.**
37b90 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 The sqlite3_rele
37ba0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 ase_memory() int
37bb0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 erface attempts
37bc0 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a to free N bytes.
37bd0 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 ** of heap memor
37be0 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e y by deallocatin
37bf0 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 g non-essential
37c00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
37c10 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 ns.** held by th
37c20 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 e database libra
37c30 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 ry. {END} Memor
37c40 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 y used to cache
37c50 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 database.** page
37c60 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 s to improve per
37c70 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 formance is an e
37c80 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 xample of non-es
37c90 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a sential memory..
37ca0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 ** sqlite3_relea
37cb0 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 se_memory() retu
37cc0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
37cd0 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 f bytes actually
37ce0 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 freed,.** which
37cf0 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f might be more o
37d00 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 r less than the
37d10 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 amount requested
37d20 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
37d30 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 34 TS:.**.** {F1734
37d40 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 1} The [sqlite3_
37d50 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e release_memory(N
37d60 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 )] interface att
37d70 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 20 20 20 20 empts to.**
37d80 20 20 20 20 20 66 72 65 65 20 4e 20 62 79 74 65 free N byte
37d90 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 s of heap memory
37da0 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 by deallocating
37db0 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 0a 2a non-essential.*
37dc0 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 * memor
37dd0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 y allocations he
37de0 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 ld by the databa
37df0 73 65 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a se library..**.*
37e00 2a 20 7b 46 31 36 33 34 32 7d 20 54 68 65 20 5b * {F16342} The [
37e10 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f sqlite3_release_
37e20 6d 65 6d 6f 72 79 28 4e 29 5d 20 72 65 74 75 72 memory(N)] retur
37e30 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a ns the number.**
37e40 20 20 20 20 20 20 20 20 20 20 6f 66 20 62 79 74 of byt
37e50 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 es actually free
37e60 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 d, which might b
37e70 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a 2a e more or less.*
37e80 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 * than
37e90 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 the amount reque
37ea0 73 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c sted..*/.int sql
37eb0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d ite3_release_mem
37ec0 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a ory(int);../*.**
37ed0 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 CAPI3REF: Impos
37ee0 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 e A Limit On Hea
37ef0 70 20 53 69 7a 65 20 7b 46 31 37 33 35 30 7d 0a p Size {F17350}.
37f00 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
37f10 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 3_soft_heap_limi
37f20 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 70 6c t() interface pl
37f30 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c 69 aces a "soft" li
37f40 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 6d mit.** on the am
37f50 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d ount of heap mem
37f60 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 ory that may be
37f70 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c allocated by SQL
37f80 69 74 65 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 6e ite..** If an in
37f90 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f ternal allocatio
37fa0 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20 74 n is requested t
37fb0 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 hat would exceed
37fc0 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65 61 the.** soft hea
37fd0 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 p limit, [sqlite
37fe0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 3_release_memory
37ff0 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f ()] is invoked o
38000 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 69 ne or.** more ti
38010 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 mes to free up s
38020 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 ome space before
38030 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 the allocation
38040 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a is performed..**
38050 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20 69 73 .** The limit is
38060 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 called "soft",
38070 62 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c 69 because if [sqli
38080 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f te3_release_memo
38090 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 20 ry()].** cannot
380a0 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74 20 free sufficient
380b0 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e memory to preven
380c0 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d t the limit from
380d0 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c being exceeded,
380e0 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 .** the memory i
380f0 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 s allocated anyw
38100 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 ay and the curre
38110 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f nt operation pro
38120 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e ceeds..**.** A n
38130 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 egative or zero
38140 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e value for N mean
38150 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20 s that there is
38160 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d no soft heap lim
38170 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 it and.** [sqlit
38180 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 e3_release_memor
38190 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 y()] will only b
381a0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 e called when me
381b0 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74 65 mory is exhauste
381c0 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c d..** The defaul
381d0 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 t value for the
381e0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 soft heap limit
381f0 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 is zero..**.** S
38200 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65 QLite makes a be
38210 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e st effort to hon
38220 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 or the soft heap
38230 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42 75 74 20 69 limit..** But i
38240 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 f the soft heap
38250 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 62 65 20 limit cannot be
38260 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75 74 69 honored, executi
38270 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 on will.** conti
38280 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 72 6f nue without erro
38290 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 6f r or notificatio
382a0 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 79 20 n. This is why
382b0 74 68 65 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 the limit is.**
382c0 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20 called a "soft"
382d0 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64 limit. It is ad
382e0 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a visory only..**.
382f0 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 ** Prior to SQLi
38300 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 te version 3.5.0
38310 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f , this routine o
38320 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 nly constrained
38330 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c the memory.** al
38340 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 69 6e located by a sin
38350 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68 65 gle thread - the
38360 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 same thread in
38370 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 74 69 which this routi
38380 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 ne.** runs. Beg
38390 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 inning with SQLi
383a0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 te version 3.5.0
383b0 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 , the soft heap
383c0 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c limit is.** appl
383d0 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 ied to all threa
383e0 64 73 2e 20 54 68 65 20 76 61 6c 75 65 20 73 70 ds. The value sp
383f0 65 63 69 66 69 65 64 20 66 6f 72 20 74 68 65 20 ecified for the
38400 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a soft heap limit.
38410 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20 62 ** is an upper b
38420 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 ound on the tota
38430 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
38440 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 ion for all thre
38450 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 69 ads. In.** versi
38460 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69 on 3.5.0 there i
38470 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 s no mechanism f
38480 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 or limiting the
38490 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a heap usage for.*
384a0 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72 * individual thr
384b0 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 eads..**.** INVA
384c0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 RIANTS:.**.** {F
384d0 31 36 33 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 16351} The [sqli
384e0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 te3_soft_heap_li
384f0 6d 69 74 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 mit(N)] interfac
38500 65 20 70 6c 61 63 65 73 20 61 20 73 6f 66 74 20 e places a soft
38510 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 limit.**
38520 20 20 6f 66 20 4e 20 62 79 74 65 73 20 6f 6e 20 of N bytes on
38530 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 the amount of he
38540 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d ap memory that m
38550 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a ay be allocated.
38560 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 69 6e ** usin
38570 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f g [sqlite3_mallo
38580 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 c()] or [sqlite3
38590 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 61 74 20 61 _realloc()] at a
385a0 6e 79 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 20 20 ny point.**
385b0 20 20 20 20 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a in time..**
385c0 0a 2a 2a 20 7b 46 31 36 33 35 32 7d 20 49 66 20 .** {F16352} If
385d0 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 a call to [sqlit
385e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 e3_malloc()] or
385f0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
38600 28 29 5d 20 77 6f 75 6c 64 0a 2a 2a 20 20 20 20 ()] would.**
38610 20 20 20 20 20 20 63 61 75 73 65 20 74 68 65 20 cause the
38620 74 6f 74 61 6c 20 61 6d 6f 75 6e 74 20 6f 66 20 total amount of
38630 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79 allocated memory
38640 20 74 6f 20 65 78 63 65 65 64 20 74 68 65 0a 2a to exceed the.*
38650 2a 20 20 20 20 20 20 20 20 20 20 73 6f 66 74 20 * soft
38660 68 65 61 70 20 6c 69 6d 69 74 2c 20 74 68 65 6e heap limit, then
38670 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 [sqlite3_releas
38680 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 e_memory()] is i
38690 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 nvoked.**
386a0 20 20 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 in an attempt
386b0 20 74 6f 20 72 65 64 75 63 65 20 74 68 65 20 6d to reduce the m
386c0 65 6d 6f 72 79 20 75 73 61 67 65 20 70 72 69 6f emory usage prio
386d0 72 20 74 6f 20 70 72 6f 63 65 65 64 69 6e 67 0a r to proceeding.
386e0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 ** with
386f0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
38700 63 61 74 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a cation attempt..
38710 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 33 7d 20 43 **.** {F16353} C
38720 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
38730 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 _malloc()] or [s
38740 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
38750 5d 20 74 68 61 74 20 74 72 69 67 67 65 72 0a 2a ] that trigger.*
38760 2a 20 20 20 20 20 20 20 20 20 20 61 74 74 65 6d * attem
38770 70 74 73 20 74 6f 20 72 65 64 75 63 65 20 6d 65 pts to reduce me
38780 6d 6f 72 79 20 75 73 61 67 65 20 74 68 72 6f 75 mory usage throu
38790 67 68 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 gh the soft heap
387a0 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 limit.**
387b0 20 20 20 6d 65 63 68 61 6e 69 73 6d 20 63 6f 6e mechanism con
387c0 74 69 6e 75 65 20 65 76 65 6e 20 69 66 20 74 68 tinue even if th
387d0 65 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 64 e attempt to red
387e0 75 63 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 uce memory.**
387f0 20 20 20 20 20 20 20 75 73 61 67 65 20 69 73 20 usage is
38800 75 6e 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2a unsuccessful..**
38810 0a 2a 2a 20 7b 46 31 36 33 35 34 7d 20 41 20 6e .** {F16354} A n
38820 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 egative or zero
38830 76 61 6c 75 65 20 66 6f 72 20 4e 20 69 6e 20 61 value for N in a
38840 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 call to.**
38850 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 6f [sqlite3_so
38860 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29 ft_heap_limit(N)
38870 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
38880 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 0a 2a 2a re is no soft.**
38890 20 20 20 20 20 20 20 20 20 20 68 65 61 70 20 6c heap l
388a0 69 6d 69 74 20 61 6e 64 20 5b 73 71 6c 69 74 65 imit and [sqlite
388b0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 3_release_memory
388c0 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 ()] will only be
388d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c .** cal
388e0 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 led when memory
388f0 69 73 20 63 6f 6d 70 6c 65 74 65 6c 79 20 65 78 is completely ex
38900 68 61 75 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b hausted..**.** {
38910 46 31 36 33 35 35 7d 20 54 68 65 20 64 65 66 61 F16355} The defa
38920 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 ult value for th
38930 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 e soft heap limi
38940 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a t is zero..**.**
38950 20 7b 46 31 36 33 35 38 7d 20 45 61 63 68 20 63 {F16358} Each c
38960 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
38970 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 soft_heap_limit(
38980 4e 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 N)] overrides th
38990 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 e.** va
389a0 6c 75 65 73 20 73 65 74 20 62 79 20 61 6c 6c 20 lues set by all
389b0 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2f 0a prior calls..*/.
389c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 void sqlite3_sof
389d0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 t_heap_limit(int
389e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
389f0 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 EF: Extract Meta
38a00 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c data About A Col
38a10 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 7b umn Of A Table {
38a20 46 31 32 38 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 F12850}.**.** Th
38a30 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
38a40 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f 75 ns metadata abou
38a50 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c t a specific col
38a60 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 umn of a specifi
38a70 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74 61 c.** database ta
38a80 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 ble accessible u
38a90 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62 61 sing the [databa
38aa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 se connection] h
38ab0 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 andle.** passed
38ac0 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e as the first fun
38ad0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a ction argument..
38ae0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e **.** The column
38af0 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 is identified b
38b00 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 y the second, th
38b10 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 ird and fourth p
38b20 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 arameters to.**
38b30 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 this function. T
38b40 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
38b50 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 ter is either th
38b60 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 e name of the da
38b70 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 tabase.** (i.e.
38b80 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f "main", "temp" o
38b90 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 r an attached da
38ba0 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 tabase) containi
38bb0 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 ng the specified
38bc0 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c .** table or NUL
38bd0 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c L. If it is NULL
38be0 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 , then all attac
38bf0 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 hed databases ar
38c00 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f e searched.** fo
38c10 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e r the table usin
38c20 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 g the same algor
38c30 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 ithm used by the
38c40 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 database engine
38c50 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 to.** resolve u
38c60 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 nqualified table
38c70 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a references..**.
38c80 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 ** The third and
38c90 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
38ca0 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 rs to this funct
38cb0 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c ion are the tabl
38cc0 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 e and column.**
38cd0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 name of the desi
38ce0 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 red column, resp
38cf0 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 ectively. Neithe
38d00 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d r of these param
38d10 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 eters.** may be
38d20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 NULL..**.** Meta
38d30 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65 64 data is returned
38d40 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 by writing to t
38d50 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 he memory locati
38d60 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74 68 ons passed as th
38d70 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 e 5th.** and sub
38d80 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 sequent paramete
38d90 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 rs to this funct
38da0 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65 73 ion. Any of thes
38db0 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 e arguments may
38dc0 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 be.** NULL, in w
38dd0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f hich case the co
38de0 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d rresponding elem
38df0 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 ent of metadata
38e00 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a is omitted..**.*
38e10 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a * <blockquote>.*
38e20 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d * <table border=
38e30 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e "1">.** <tr><th>
38e40 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 Parameter <th>
38e50 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c Output<br>Type <
38e60 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e th> Description
38e70 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 .**.** <tr><td>
38e80 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 5th <td> const c
38e90 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 har* <td> Data t
38ea0 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ype.** <tr><td>
38eb0 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 6th <td> const c
38ec0 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f har* <td> Name o
38ed0 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 f default collat
38ee0 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 ion sequence.**
38ef0 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 <tr><td> 7th <td
38f00 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 > int <t
38f10 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d d> True if colum
38f20 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c n has a NOT NULL
38f30 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c constraint.** <
38f40 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e tr><td> 8th <td>
38f50 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 int <td
38f60 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e > True if column
38f70 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 is part of the
38f80 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c PRIMARY KEY.** <
38f90 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e tr><td> 9th <td>
38fa0 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 int <td
38fb0 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e > True if column
38fc0 20 69 73 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e is AUTOINCREMEN
38fd0 54 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a T.** </table>.**
38fe0 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a </blockquote>.*
38ff0 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 *.** The memory
39000 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 pointed to by th
39010 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e e character poin
39020 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f ters returned fo
39030 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 r the.** declara
39040 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f tion type and co
39050 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
39060 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 is valid only u
39070 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a ntil the next.**
39080 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c call to any SQL
39090 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e ite API function
390a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 ..**.** If the s
390b0 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 pecified table i
390c0 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 s actually a vie
390d0 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 w, an [error cod
390e0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a e] is returned..
390f0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 **.** If the spe
39100 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 cified column is
39110 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 "rowid", "oid"
39120 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 or "_rowid_" and
39130 20 61 6e 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50 an.** INTEGER P
39140 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d RIMARY KEY colum
39150 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 n has been expli
39160 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 citly declared,
39170 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a then the output.
39180 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 ** parameters ar
39190 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 e set for the ex
391a0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 plicitly declare
391b0 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 d column. If the
391c0 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c re is no.** expl
391d0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 icitly declared
391e0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 INTEGER PRIMARY
391f0 4b 45 59 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e KEY column, then
39200 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 the output.** p
39210 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 arameters are se
39220 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a t as follows:.**
39230 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 .** <pre>.**
39240 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 data type: "INT
39250 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c EGER".** col
39260 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a lation sequence:
39270 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 "BINARY".**
39280 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 not null: 0.**
39290 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a primary key:
392a0 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 1.** auto i
392b0 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c ncrement: 0.** <
392c0 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 /pre>.**.** This
392d0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f function may lo
392e0 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 ad one or more s
392f0 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 chemas from data
39300 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 base files. If a
39310 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 n.** error occur
39320 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 s during this pr
39330 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 ocess, or if the
39340 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 requested table
39350 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 or column.** ca
39360 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 nnot be found, a
39370 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
39380 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 s returned and a
39390 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 n error message
393a0 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b left.** in the [
393b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
393c0 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72 ion] (to be retr
393d0 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 ieved using sqli
393e0 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a te3_errmsg())..*
393f0 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 *.** This API is
39400 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 only available
39410 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 if the library w
39420 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 as compiled with
39430 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
39440 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 ENABLE_COLUMN_ME
39450 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f TADATA] C-prepro
39460 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 cessor symbol de
39470 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 fined..*/.int sq
39480 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 lite3_table_colu
39490 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 mn_metadata(. s
394a0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
394b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f /* Co
394c0 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 nnection handle
394d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
394e0 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 *zDbName,
394f0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d /* Database nam
39500 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 e or NULL */. c
39510 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c onst char *zTabl
39520 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 eName, /* Ta
39530 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f ble name */. co
39540 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d nst char *zColum
39550 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c nName, /* Col
39560 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 umn name */. ch
39570 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 ar const **pzDat
39580 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 aType, /* OUT
39590 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 PUT: Declared da
395a0 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 ta type */. cha
395b0 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c r const **pzColl
395c0 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 Seq, /* OUTP
395d0 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 UT: Collation se
395e0 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 quence name */.
395f0 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 int *pNotNull,
39600 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
39610 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 OUTPUT: True if
39620 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 NOT NULL constra
39630 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 int exists */.
39640 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 int *pPrimaryKey
39650 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f , /* O
39660 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 UTPUT: True if c
39670 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b olumn part of PK
39680 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f */. int *pAuto
39690 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20 inc
396a0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 /* OUTPUT: Tru
396b0 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 e if column is a
396c0 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f uto-increment */
396d0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
396e0 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 REF: Load An Ext
396f0 65 6e 73 69 6f 6e 20 7b 46 31 32 36 30 30 7d 0a ension {F12600}.
39700 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
39710 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 face loads an SQ
39720 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c Lite extension l
39730 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20 ibrary from the
39740 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a named file..**.*
39750 2a 20 7b 46 31 32 36 30 31 7d 20 54 68 65 20 73 * {F12601} The s
39760 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 qlite3_load_exte
39770 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 nsion() interfac
39780 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f e attempts to lo
39790 61 64 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ad an.**
397a0 20 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 SQLite extensi
397b0 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 on library conta
397c0 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 ined in the file
397d0 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 zFile..**.** {F
397e0 31 32 36 30 32 7d 20 54 68 65 20 65 6e 74 72 79 12602} The entry
397f0 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e point is zProc.
39800 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 33 7d 20 .**.** {F12603}
39810 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 zProc may be 0,
39820 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 in which case th
39830 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e e name of the en
39840 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 20 try point.**
39850 20 20 20 20 20 20 64 65 66 61 75 6c 74 73 20 74 defaults t
39860 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e o "sqlite3_exten
39870 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a sion_init"..**.*
39880 2a 20 7b 46 31 32 36 30 34 7d 20 54 68 65 20 73 * {F12604} The s
39890 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 qlite3_load_exte
398a0 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 nsion() interfac
398b0 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a e shall return.*
398c0 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 * [SQLI
398d0 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
398e0 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 s and [SQLITE_ER
398f0 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e ROR] if somethin
39900 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a g goes wrong..**
39910 0a 2a 2a 20 7b 46 31 32 36 30 35 7d 20 49 66 20 .** {F12605} If
39920 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 an error occurs
39930 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 and pzErrMsg is
39940 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a not 0, then the.
39950 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
39960 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 ite3_load_extens
39970 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ion()] interface
39980 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 shall attempt t
39990 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 o.** fi
399a0 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 ll *pzErrMsg wit
399b0 68 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 h error message
399c0 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d text stored in m
399d0 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 emory.**
399e0 20 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 obtained from
399f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
39a00 29 5d 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 63 )]. {END} The c
39a10 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a alling function.
39a20 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 6f 75 ** shou
39a30 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d ld free this mem
39a40 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b ory by calling [
39a50 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e sqlite3_free()].
39a60 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 36 7d 20 .**.** {F12606}
39a70 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e Extension loadin
39a80 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65 g must be enable
39a90 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 d using.**
39aa0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 [sqlite3_ena
39ab0 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 ble_load_extensi
39ac0 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 on()] prior to c
39ad0 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c alling this API,
39ae0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 74 68 .** oth
39af0 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 erwise an error
39b00 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 will be returned
39b10 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
39b20 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
39b30 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
39b40 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 /* Load
39b50 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 the extension i
39b60 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 nto this databas
39b70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a e connection */.
39b80 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 const char *zF
39b90 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 ile, /* Name
39ba0 6f 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 of the shared li
39bb0 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 brary containing
39bc0 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 extension */.
39bd0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f const char *zPro
39be0 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 c, /* Entry p
39bf0 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 oint. Derived f
39c00 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a rom zFile if 0 *
39c10 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 /. char **pzErr
39c20 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 Msg /* Put
39c30 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 error message h
39c40 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a ere if not 0 */.
39c50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
39c60 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 EF: Enable Or Di
39c70 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 sable Extension
39c80 4c 6f 61 64 69 6e 67 20 7b 46 31 32 36 32 30 7d Loading {F12620}
39c90 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 .**.** So as not
39ca0 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 to open securit
39cb0 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 y holes in older
39cc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 applications th
39cd0 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 at are.** unprep
39ce0 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 ared to deal wit
39cf0 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 h extension load
39d00 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 ing, and as a me
39d10 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 ans of disabling
39d20 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f .** extension lo
39d30 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c ading while eval
39d40 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 uating user-ente
39d50 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c red SQL, the fol
39d60 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 lowing API.** is
39d70 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 provided to tur
39d80 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c n the [sqlite3_l
39d90 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d oad_extension()]
39da0 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e mechanism on an
39db0 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 d off..**.** Ext
39dc0 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 ension loading i
39dd0 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 s off by default
39de0 2e 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 . See ticket #18
39df0 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 32 63..**.** {F1262
39e00 31 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 1} Call the sqli
39e10 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f te3_enable_load_
39e20 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 extension() rout
39e30 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d ine with onoff==
39e40 31 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 1.** to
39e50 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 turn extension
39e60 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 loading on and c
39e70 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 all it with onof
39e80 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 f==0 to turn.**
39e90 20 20 20 20 20 20 20 20 20 69 74 20 62 61 63 6b it back
39ea0 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2a 0a 2a off again..**.*
39eb0 2a 20 7b 46 31 32 36 32 32 7d 20 45 78 74 65 6e * {F12622} Exten
39ec0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 sion loading is
39ed0 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 0a off by default..
39ee0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 */.int sqlite3_e
39ef0 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e nable_load_exten
39f00 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 sion(sqlite3 *db
39f10 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f , int onoff);../
39f20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
39f30 61 6b 65 20 41 72 72 61 6e 67 65 6d 65 6e 74 73 ake Arrangements
39f40 20 54 6f 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c To Automaticall
39f50 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 y Load An Extens
39f60 69 6f 6e 20 7b 46 31 32 36 34 30 7d 0a 2a 2a 0a ion {F12640}.**.
39f70 2a 2a 20 54 68 69 73 20 41 50 49 20 63 61 6e 20 ** This API can
39f80 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72 be invoked at pr
39f90 6f 67 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e ogram startup in
39fa0 20 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73 74 order to regist
39fb0 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 er.** one or mor
39fc0 65 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e e statically lin
39fd0 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 ked extensions t
39fe0 68 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69 hat will be avai
39ff0 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 lable.** to all
3a000 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f new [database co
3a010 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20 7b 45 4e 44 nnections]. {END
3a020 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 }.**.** This rou
3a030 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f tine stores a po
3a040 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 74 inter to the ext
3a050 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 ension in an arr
3a060 61 79 20 74 68 61 74 20 69 73 0a 2a 2a 20 6f 62 ay that is.** ob
3a070 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
3a080 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 ite3_malloc()].
3a090 20 49 66 20 79 6f 75 20 72 75 6e 20 61 20 6d 65 If you run a me
3a0a0 6d 6f 72 79 20 6c 65 61 6b 20 63 68 65 63 6b 65 mory leak checke
3a0b0 72 0a 2a 2a 20 6f 6e 20 79 6f 75 72 20 70 72 6f r.** on your pro
3a0c0 67 72 61 6d 20 61 6e 64 20 69 74 20 72 65 70 6f gram and it repo
3a0d0 72 74 73 20 61 20 6c 65 61 6b 20 62 65 63 61 75 rts a leak becau
3a0e0 73 65 20 6f 66 20 74 68 69 73 20 61 72 72 61 79 se of this array
3a0f0 2c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71 6c , invoke.** [sql
3a100 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f ite3_reset_auto_
3a110 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 extension()] pri
3a120 6f 72 20 74 6f 20 73 68 75 74 64 6f 77 6e 20 74 or to shutdown t
3a130 6f 20 66 72 65 65 20 74 68 65 20 6d 65 6d 6f 72 o free the memor
3a140 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e y..**.** This in
3a150 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 terface is exper
3a160 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 imental and is s
3a170 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
3a180 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 or.** removal i
3a190 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
3a1a0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a s of SQLite..**.
3a1b0 2a 2a 20 7b 46 31 32 36 34 31 7d 20 54 68 69 73 ** {F12641} This
3a1c0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 function regist
3a1d0 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e ers an extension
3a1e0 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 entry point tha
3a1f0 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 t is.**
3a200 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 automatically i
3a210 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 nvoked whenever
3a220 61 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 a new [database
3a230 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 20 connection].**
3a240 20 20 20 20 20 20 20 20 69 73 20 6f 70 65 6e 65 is opene
3a250 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
3a260 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
3a270 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a e3_open16()],.**
3a280 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 or [sq
3a290 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
3a2a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 32 7d ..**.** {F12642}
3a2b0 20 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e Duplicate exten
3a2c0 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 sions are detect
3a2d0 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 ed so calling th
3a2e0 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 is routine.**
3a2f0 20 20 20 20 20 20 20 6d 75 6c 74 69 70 6c 65 20 multiple
3a300 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 times with the s
3a310 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 ame extension is
3a320 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a harmless..**.**
3a330 20 7b 46 31 32 36 34 33 7d 20 54 68 69 73 20 72 {F12643} This r
3a340 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 outine stores a
3a350 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 pointer to the e
3a360 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 xtension in an a
3a370 72 72 61 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 rray.**
3a380 20 74 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 that is obtaine
3a390 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
3a3a0 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a malloc()]..**.**
3a3b0 20 7b 46 31 32 36 34 34 7d 20 41 75 74 6f 6d 61 {F12644} Automa
3a3c0 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 tic extensions a
3a3d0 70 70 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 pply across all
3a3e0 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 69 6e 74 20 threads..*/.int
3a3f0 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 sqlite3_auto_ext
3a400 65 6e 73 69 6f 6e 28 76 6f 69 64 20 2a 78 45 6e ension(void *xEn
3a410 74 72 79 50 6f 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a tryPoint);../*.*
3a420 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
3a430 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 t Automatic Exte
3a440 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 nsion Loading {F
3a450 31 32 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 12660}.**.** Thi
3a460 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 s function disab
3a470 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 les all previous
3a480 6c 79 20 72 65 67 69 73 74 65 72 65 64 20 61 75 ly registered au
3a490 74 6f 6d 61 74 69 63 0a 2a 2a 20 65 78 74 65 6e tomatic.** exten
3a4a0 73 69 6f 6e 73 2e 20 7b 45 4e 44 7d 20 20 49 74 sions. {END} It
3a4b0 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 undoes the effe
3a4c0 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a ct of all prior.
3a4d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f ** [sqlite3_auto
3a4e0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61 _extension()] ca
3a4f0 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 lls..**.** This
3a500 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 interface is exp
3a510 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 erimental and is
3a520 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
3a530 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c ge or.** removal
3a540 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
3a550 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ses of SQLite..*
3a560 2a 0a 2a 2a 20 7b 46 31 32 36 36 31 7d 20 54 68 *.** {F12661} Th
3a570 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 is function disa
3a580 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 bles all previou
3a590 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 0a 2a sly registered.*
3a5a0 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d * autom
3a5b0 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 2e atic extensions.
3a5c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 36 32 7d 20 .**.** {F12662}
3a5d0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 This function di
3a5e0 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 63 sables automatic
3a5f0 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 extensions in a
3a600 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 ll threads..*/.v
3a610 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65 oid sqlite3_rese
3a620 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e t_auto_extension
3a630 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a 2a (void);../*.****
3a640 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 ** EXPERIMENTAL
3a650 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 - subject to cha
3a660 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 nge without noti
3a670 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ce *************
3a680 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 *.**.** The inte
3a690 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 rface to the vir
3a6a0 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 tual-table mecha
3a6b0 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c nism is currentl
3a6c0 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 y considered.**
3a6d0 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 to be experiment
3a6e0 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 al. The interfa
3a6f0 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 ce might change
3a700 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 in incompatible
3a710 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 ways..** If this
3a720 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f is a problem fo
3a730 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 r you, do not us
3a740 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 e the interface
3a750 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a at this time..**
3a760 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 .** When the vir
3a770 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 tual-table mecha
3a780 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c nism stabilizes,
3a790 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 we will declare
3a7a0 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 the.** interfac
3a7b0 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 e fixed, support
3a7c0 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 it indefinitely
3a7d0 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 , and remove thi
3a7e0 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f s comment..*/../
3a7f0 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20 *.** Structures
3a800 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74 used by the virt
3a810 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 ual table interf
3a820 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 ace.*/.typedef s
3a830 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 truct sqlite3_vt
3a840 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b ab sqlite3_vtab;
3a850 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
3a860 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e sqlite3_index_in
3a870 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 fo sqlite3_index
3a880 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 _info;.typedef s
3a890 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 truct sqlite3_vt
3a8a0 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65 ab_cursor sqlite
3a8b0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 3_vtab_cursor;.t
3a8c0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
3a8d0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c lite3_module sql
3a8e0 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a ite3_module;../*
3a8f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 .** CAPI3REF: Vi
3a900 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65 rtual Table Obje
3a910 63 74 20 7b 46 31 38 30 30 30 7d 0a 2a 2a 20 4b ct {F18000}.** K
3a920 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 EYWORDS: sqlite3
3a930 5f 6d 6f 64 75 6c 65 0a 2a 2a 0a 2a 2a 20 41 20 _module.**.** A
3a940 6d 6f 64 75 6c 65 20 69 73 20 61 20 63 6c 61 73 module is a clas
3a950 73 20 6f 66 20 76 69 72 74 75 61 6c 20 74 61 62 s of virtual tab
3a960 6c 65 73 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c les. Each modul
3a970 65 20 69 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 e is defined.**
3a980 62 79 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f by an instance o
3a990 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
3a9a0 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 69 73 structure. This
3a9b0 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 structure consi
3a9c0 73 74 73 0a 2a 2a 20 6d 6f 73 74 6c 79 20 6f 66 sts.** mostly of
3a9d0 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 methods for the
3a9e0 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 module..**.** T
3a9f0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
3aa00 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e experimental an
3aa10 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 d is subject to
3aa20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d change or.** rem
3aa30 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 oval in future r
3aa40 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
3aa50 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c e..*/.struct sql
3aa60 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 ite3_module {.
3aa70 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 int iVersion;.
3aa80 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 int (*xCreate)(s
3aa90 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 qlite3*, void *p
3aaa0 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 Aux,.
3aab0 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f int argc, co
3aac0 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a nst char *const*
3aad0 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 argv,.
3aae0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 sqlite3_vta
3aaf0 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 b **ppVTab, char
3ab00 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f **);. int (*xCo
3ab10 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c nnect)(sqlite3*,
3ab20 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 void *pAux,.
3ab30 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 int
3ab40 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 argc, const char
3ab50 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 *const*argv,.
3ab60 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c sql
3ab70 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 ite3_vtab **ppVT
3ab80 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 ab, char**);. i
3ab90 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 nt (*xBestIndex)
3aba0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
3abb0 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e VTab, sqlite3_in
3abc0 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e dex_info*);. in
3abd0 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 t (*xDisconnect)
3abe0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
3abf0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 VTab);. int (*x
3ac00 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 Destroy)(sqlite3
3ac10 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 _vtab *pVTab);.
3ac20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 int (*xOpen)(sq
3ac30 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 lite3_vtab *pVTa
3ac40 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f b, sqlite3_vtab_
3ac50 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f cursor **ppCurso
3ac60 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f r);. int (*xClo
3ac70 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 se)(sqlite3_vtab
3ac80 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 _cursor*);. int
3ac90 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 (*xFilter)(sqli
3aca0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a te3_vtab_cursor*
3acb0 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f , int idxNum, co
3acc0 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 nst char *idxStr
3acd0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
3ace0 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 int argc, sqli
3acf0 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 te3_value **argv
3ad00 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 );. int (*xNext
3ad10 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 )(sqlite3_vtab_c
3ad20 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 ursor*);. int (
3ad30 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 *xEof)(sqlite3_v
3ad40 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 tab_cursor*);.
3ad50 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 int (*xColumn)(s
3ad60 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
3ad70 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e or*, sqlite3_con
3ad80 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 text*, int);. i
3ad90 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c nt (*xRowid)(sql
3ada0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
3adb0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
3adc0 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 *pRowid);. int
3add0 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 (*xUpdate)(sqli
3ade0 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c te3_vtab *, int,
3adf0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a sqlite3_value *
3ae00 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
3ae10 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 *);. int (*xBe
3ae20 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 gin)(sqlite3_vta
3ae30 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 b *pVTab);. int
3ae40 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 (*xSync)(sqlite
3ae50 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 3_vtab *pVTab);.
3ae60 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 int (*xCommit)
3ae70 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
3ae80 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 VTab);. int (*x
3ae90 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 Rollback)(sqlite
3aea0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 3_vtab *pVTab);.
3aeb0 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e int (*xFindFun
3aec0 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 ction)(sqlite3_v
3aed0 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 tab *pVtab, int
3aee0 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 nArg, const char
3aef0 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 *zName,.
3af00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3af10 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 void (**pxFunc)(
3af20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
3af30 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
3af40 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 ue**),.
3af50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f vo
3af60 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 0a 20 20 id **ppArg);..
3af70 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 int (*xRename)(s
3af80 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 qlite3_vtab *pVt
3af90 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ab, const char *
3afa0 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a zNew);.};../*.**
3afb0 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 CAPI3REF: Virtu
3afc0 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e al Table Indexin
3afd0 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b 46 g Information {F
3afe0 31 38 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 18100}.** KEYWOR
3aff0 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 DS: sqlite3_inde
3b000 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 x_info.**.** The
3b010 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 sqlite3_index_i
3b020 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e nfo structure an
3b030 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75 d its substructu
3b040 72 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a res is used to.*
3b050 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 * pass informati
3b060 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 on into and rece
3b070 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 ive the reply fr
3b080 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 om the xBestInde
3b090 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 x.** method of a
3b0a0 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 n sqlite3_module
3b0b0 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e . The fields un
3b0c0 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 der **Inputs** a
3b0d0 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 re the.** inputs
3b0e0 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 to xBestIndex a
3b0f0 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 nd are read-only
3b100 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e . xBestIndex in
3b110 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 serts its.** res
3b120 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a ults into the **
3b130 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 Outputs** fields
3b140 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e ..**.** The aCon
3b150 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 straint[] array
3b160 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c records WHERE cl
3b170 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 ause constraints
3b180 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a of the form:.**
3b190 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 .** <pre>column
3b1a0 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a OP expr</pre>.**
3b1b0 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 .** where OP is
3b1c0 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 =, <, <=,
3b1d0 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20 >, or >=.
3b1e0 20 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 The particular
3b1f0 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 operator is.** s
3b200 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 tored in aConstr
3b210 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 aint[].op. The
3b220 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c index of the col
3b230 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e umn is stored in
3b240 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b .** aConstraint[
3b250 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e ].iColumn. aCon
3b260 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 straint[].usable
3b270 20 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a is TRUE if the.
3b280 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 ** expr on the r
3b290 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 ight-hand side c
3b2a0 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 an be evaluated
3b2b0 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f (and thus the co
3b2c0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 nstraint.** is u
3b2d0 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 sable) and false
3b2e0 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a if it cannot..*
3b2f0 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a *.** The optimiz
3b300 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 er automatically
3b310 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f inverts terms o
3b320 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 f the form "expr
3b330 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 OP column".** a
3b340 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 nd makes other s
3b350 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 implifications t
3b360 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 o the WHERE clau
3b370 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 se in an attempt
3b380 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 to.** get as ma
3b390 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 ny WHERE clause
3b3a0 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 terms into the f
3b3b0 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 orm shown above
3b3c0 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 as possible..**
3b3d0 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b The aConstraint[
3b3e0 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 ] array only rep
3b3f0 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 orts WHERE claus
3b400 65 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 63 e terms in the c
3b410 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 orrect.** form t
3b420 68 61 74 20 72 65 66 65 72 20 74 6f 20 74 68 65 hat refer to the
3b430 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 particular virt
3b440 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 ual table being
3b450 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 queried..**.** I
3b460 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 nformation about
3b470 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c the ORDER BY cl
3b480 61 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 ause is stored i
3b490 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a n aOrderBy[]..**
3b4a0 20 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f Each term of aO
3b4b0 72 64 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 rderBy records a
3b4c0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f column of the O
3b4d0 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a RDER BY clause..
3b4e0 2a 2a 0a 2a 2a 20 54 68 65 20 78 42 65 73 74 49 **.** The xBestI
3b4f0 6e 64 65 78 20 6d 65 74 68 6f 64 20 6d 75 73 74 ndex method must
3b500 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e fill aConstrain
3b510 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e tUsage[] with in
3b520 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f formation.** abo
3b530 75 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 ut what paramete
3b540 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 rs to pass to xF
3b550 69 6c 74 65 72 2e 20 20 49 66 20 61 72 67 76 49 ilter. If argvI
3b560 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 ndex>0 then.** t
3b570 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 he right-hand si
3b580 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 de of the corres
3b590 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 ponding aConstra
3b5a0 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 int[] is evaluat
3b5b0 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 ed.** and become
3b5c0 73 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d s the argvIndex-
3b5d0 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 th entry in argv
3b5e0 2e 20 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e . If aConstrain
3b5f0 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a tUsage[].omit.**
3b600 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 is true, then t
3b610 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 he constraint is
3b620 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 assumed to be f
3b630 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 ully handled by
3b640 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 the.** virtual t
3b650 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 able and is not
3b660 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 checked again by
3b670 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 SQLite..**.** T
3b680 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 he idxNum and id
3b690 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 xPtr values are
3b6a0 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 recorded and pas
3b6b0 73 65 64 20 69 6e 74 6f 20 78 46 69 6c 74 65 72 sed into xFilter
3b6c0 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 ..** sqlite3_fre
3b6d0 65 28 29 20 69 73 20 75 73 65 64 20 74 6f 20 66 e() is used to f
3b6e0 72 65 65 20 69 64 78 50 74 72 20 69 66 20 6e 65 ree idxPtr if ne
3b6f0 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69 edToFreeIdxPtr i
3b700 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 s true..**.** Th
3b710 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 e orderByConsume
3b720 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74 d means that out
3b730 70 75 74 20 66 72 6f 6d 20 78 46 69 6c 74 65 72 put from xFilter
3b740 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a will occur in.*
3b750 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 * the correct or
3b760 64 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 der to satisfy t
3b770 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 he ORDER BY clau
3b780 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 se so that no se
3b790 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e parate.** sortin
3b7a0 67 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72 g step is requir
3b7b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 ed..**.** The es
3b7c0 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 timatedCost valu
3b7d0 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 e is an estimate
3b7e0 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 of the cost of
3b7f0 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 doing the.** par
3b800 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 ticular lookup.
3b810 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 A full scan of
3b820 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 a table with N e
3b830 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 ntries should ha
3b840 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 ve.** a cost of
3b850 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 N. A binary sea
3b860 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f rch of a table o
3b870 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 f N entries shou
3b880 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 ld have a.** cos
3b890 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 t of approximate
3b8a0 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2a 0a 2a 2a ly log(N)..**.**
3b8b0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
3b8c0 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 is experimental
3b8d0 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 and is subject t
3b8e0 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 o change or.** r
3b8f0 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 emoval in future
3b900 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
3b910 69 74 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 ite..*/.struct s
3b920 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 qlite3_index_inf
3b930 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 o {. /* Inputs
3b940 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72 */. int nConstr
3b950 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 aint;
3b960 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 /* Number of ent
3b970 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 ries in aConstra
3b980 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 int */. struct
3b990 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f sqlite3_index_co
3b9a0 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 nstraint {.
3b9b0 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 int iColumn;
3b9c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c /* Col
3b9d0 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 umn on left-hand
3b9e0 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 side of constra
3b9f0 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 int */. unsi
3ba00 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 20 gned char op;
3ba10 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 /* Constra
3ba20 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a int operator */.
3ba30 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 unsigned ch
3ba40 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 2f ar usable; /
3ba50 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20 63 * True if this c
3ba60 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 61 onstraint is usa
3ba70 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 ble */. int
3ba80 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 iTermOffset;
3ba90 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e /* Used in
3baa0 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 ternally - xBest
3bab0 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 6e Index should ign
3bac0 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e ore */. } *aCon
3bad0 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 straint;
3bae0 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 /* Table of
3baf0 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e WHERE clause con
3bb00 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e straints */. in
3bb10 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20 t nOrderBy;
3bb20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 /* Numb
3bb30 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 er of terms in t
3bb40 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 he ORDER BY clau
3bb50 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 se */. struct s
3bb60 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 qlite3_index_ord
3bb70 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 erby {. int
3bb80 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 iColumn;
3bb90 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 /* Column
3bba0 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 number */. u
3bbb0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 73 nsigned char des
3bbc0 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 c; /* True
3bbd0 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73 for DESC. Fals
3bbe0 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 e for ASC. */.
3bbf0 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 20 } *aOrderBy;
3bc00 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68 /* Th
3bc10 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 e ORDER BY claus
3bc20 65 20 2a 2f 0a 0a 20 20 2f 2a 20 4f 75 74 70 75 e */.. /* Outpu
3bc30 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 ts */. struct s
3bc40 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e qlite3_index_con
3bc50 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a straint_usage {.
3bc60 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 int argvInde
3bc70 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 x; /*
3bc80 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e if >0, constrain
3bc90 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 t is part of arg
3bca0 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a v to xFilter */.
3bcb0 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 unsigned cha
3bcc0 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 r omit; /*
3bcd0 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 Do not code a te
3bce0 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 st for this cons
3bcf0 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 traint */. } *a
3bd00 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b ConstraintUsage;
3bd10 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 . int idxNum;
3bd20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
3bd30 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 Number used to
3bd40 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 identify the ind
3bd50 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 ex */. char *id
3bd60 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 xStr;
3bd70 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f /* String, po
3bd80 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 ssibly obtained
3bd90 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c from sqlite3_mal
3bda0 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 loc */. int nee
3bdb0 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 dToFreeIdxStr;
3bdc0 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 /* Free idxS
3bdd0 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 tr using sqlite3
3bde0 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20 _free() if true
3bdf0 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 */. int orderBy
3be00 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 Consumed;
3be10 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 /* True if outpu
3be20 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 t is already ord
3be30 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 ered */. double
3be40 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 estimatedCost;
3be50 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 /* Estimate
3be60 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 d cost of using
3be70 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b this index */.};
3be80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3be90 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
3bea0 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 _EQ 2.#define
3beb0 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
3bec0 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 NSTRAINT_GT 4
3bed0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3bee0 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
3bef0 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 _LE 8.#define
3bf00 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
3bf10 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 NSTRAINT_LT 1
3bf20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 6.#define SQLITE
3bf30 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e _INDEX_CONSTRAIN
3bf40 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 T_GE 32.#defi
3bf50 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f ne SQLITE_INDEX_
3bf60 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 CONSTRAINT_MATCH
3bf70 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 64../*.** CAPI3
3bf80 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 REF: Register A
3bf90 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d Virtual Table Im
3bfa0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 46 31 plementation {F1
3bfb0 38 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 8200}.**.** This
3bfc0 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 65 64 routine is used
3bfd0 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e to register a n
3bfe0 65 77 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 77 ew module name w
3bff0 69 74 68 20 61 0a 2a 2a 20 5b 64 61 74 61 62 61 ith a.** [databa
3c000 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
3c010 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 Module names mu
3c020 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64 st be registered
3c030 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 before.** creat
3c040 69 6e 67 20 6e 65 77 20 76 69 72 74 75 61 6c 20 ing new virtual
3c050 74 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d 6f tables on the mo
3c060 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 20 dule, or before
3c070 75 73 69 6e 67 0a 2a 2a 20 70 72 65 65 78 69 73 using.** preexis
3c080 74 69 6e 67 20 76 69 72 74 75 61 6c 20 74 61 62 ting virtual tab
3c090 6c 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c les of the modul
3c0a0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e e..**.** This in
3c0b0 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 terface is exper
3c0c0 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 imental and is s
3c0d0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
3c0e0 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 or.** removal i
3c0f0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
3c100 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a s of SQLite..*/.
3c110 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 int sqlite3_crea
3c120 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c te_module(. sql
3c130 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
3c140 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 /* SQLit
3c150 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 e connection to
3c160 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 register module
3c170 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 with */. const
3c180 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 char *zName,
3c190 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 /* Name of
3c1a0 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 the module */.
3c1b0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f const sqlite3_mo
3c1c0 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 dule *, /* Me
3c1d0 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f thods for the mo
3c1e0 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a dule */. void *
3c1f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3c200 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 /* Client d
3c210 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f ata for xCreate/
3c220 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a xConnect */.);..
3c230 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
3c240 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75 Register A Virtu
3c250 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 al Table Impleme
3c260 6e 74 61 74 69 6f 6e 20 7b 46 31 38 32 31 30 7d ntation {F18210}
3c270 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
3c280 69 6e 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c ine is identical
3c290 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
3c2a0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 _create_module()
3c2b0 5d 20 6d 65 74 68 6f 64 20 61 62 6f 76 65 2c 0a ] method above,.
3c2c0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 ** except that i
3c2d0 74 20 61 6c 6c 6f 77 73 20 61 20 64 65 73 74 72 t allows a destr
3c2e0 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 74 uctor function t
3c2f0 6f 20 62 65 20 73 70 65 63 69 66 69 65 64 2e 20 o be specified.
3c300 49 74 20 69 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f It is.** even mo
3c310 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 re experimental
3c320 74 68 61 6e 20 74 68 65 20 72 65 73 74 20 6f 66 than the rest of
3c330 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 the virtual tab
3c340 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a 69 6e 74 20 les API..*/.int
3c350 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d sqlite3_create_m
3c360 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 odule_v2(. sqli
3c370 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
3c380 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 /* SQLite
3c390 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 connection to r
3c3a0 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 egister module w
3c3b0 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ith */. const c
3c3c0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 har *zName,
3c3d0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 /* Name of t
3c3e0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 he module */. c
3c3f0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 onst sqlite3_mod
3c400 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 ule *, /* Met
3c410 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 hods for the mod
3c420 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c ule */. void *,
3c430 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3c440 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 /* Client da
3c450 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 ta for xCreate/x
3c460 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 Connect */. voi
3c470 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 d(*xDestroy)(voi
3c480 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c d*) /* Modul
3c490 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e e destructor fun
3c4a0 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a ction */.);../*.
3c4b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 ** CAPI3REF: Vir
3c4c0 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 tual Table Insta
3c4d0 6e 63 65 20 4f 62 6a 65 63 74 20 7b 46 31 38 30 nce Object {F180
3c4e0 31 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 10}.** KEYWORDS:
3c4f0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a sqlite3_vtab.**
3c500 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c 65 .** Every module
3c510 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
3c520 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 uses a subclass
3c530 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
3c540 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f structure.** to
3c550 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72 74 describe a part
3c560 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 icular instance
3c570 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 of the module.
3c580 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77 69 Each subclass wi
3c590 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 ll.** be tailore
3c5a0 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 d to the specifi
3c5b0 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d c needs of the m
3c5c0 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 odule implementa
3c5d0 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 tion..** The pur
3c5e0 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 pose of this sup
3c5f0 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 erclass is to de
3c600 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 fine certain fie
3c610 6c 64 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 lds that are.**
3c620 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f common to all mo
3c630 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 dule implementat
3c640 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 ions..**.** Virt
3c650 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f ual tables metho
3c660 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 ds can set an er
3c670 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 ror message by a
3c680 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 ssigning a.** st
3c690 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 ring obtained fr
3c6a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 om [sqlite3_mpri
3c6b0 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 ntf()] to zErrMs
3c6c0 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73 g. The method s
3c6d0 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 hould.** take ca
3c6e0 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f re that any prio
3c6f0 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65 65 r string is free
3c700 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b d by a call to [
3c710 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a sqlite3_free()].
3c720 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 ** prior to assi
3c730 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 gning a new stri
3c740 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 ng to zErrMsg.
3c750 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 After the error
3c760 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 message.** is de
3c770 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 livered up to th
3c780 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 e client applica
3c790 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 tion, the string
3c7a0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 will be automat
3c7b0 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 ically.** freed
3c7c0 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 by sqlite3_free(
3c7d0 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 ) and the zErrMs
3c7e0 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 g field will be
3c7f0 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a 2a zeroed. Note.**
3c800 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 6d 70 that sqlite3_mp
3c810 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 rintf() and sqli
3c820 74 65 33 5f 66 72 65 65 28 29 20 61 72 65 20 75 te3_free() are u
3c830 73 65 64 20 6f 6e 20 74 68 65 20 7a 45 72 72 4d sed on the zErrM
3c840 73 67 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e 63 sg field.** sinc
3c850 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 e virtual tables
3c860 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69 6d are commonly im
3c870 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f 61 plemented in loa
3c880 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 dable extensions
3c890 20 77 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f 74 which.** do not
3c8a0 20 68 61 76 65 20 61 63 63 65 73 73 20 74 6f 20 have access to
3c8b0 73 71 6c 69 74 65 33 4d 50 72 69 6e 74 66 28 29 sqlite3MPrintf()
3c8c0 20 6f 72 20 73 71 6c 69 74 65 33 46 72 65 65 28 or sqlite3Free(
3c8d0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e )..**.** This in
3c8e0 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 terface is exper
3c8f0 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 imental and is s
3c900 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
3c910 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 or.** removal i
3c920 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
3c930 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a s of SQLite..*/.
3c940 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
3c950 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 tab {. const sq
3c960 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d lite3_module *pM
3c970 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d odule; /* The m
3c980 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 odule for this v
3c990 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a irtual table */.
3c9a0 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 int nRef;
3c9b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3c9c0 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e /* Used intern
3c9d0 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a ally */. char *
3c9e0 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20 zErrMsg;
3c9f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 /* Err
3ca00 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 or message from
3ca10 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
3ca20 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 ) */. /* Virtua
3ca30 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e l table implemen
3ca40 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 tations will typ
3ca50 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 ically add addit
3ca60 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a ional fields */.
3ca70 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
3ca80 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c EF: Virtual Tabl
3ca90 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63 74 20 e Cursor Object
3caa0 20 7b 46 31 38 30 32 30 7d 0a 2a 2a 20 4b 45 59 {F18020}.** KEY
3cab0 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 WORDS: sqlite3_v
3cac0 74 61 62 5f 63 75 72 73 6f 72 0a 2a 2a 0a 2a 2a tab_cursor.**.**
3cad0 20 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d Every module im
3cae0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 plementation use
3caf0 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 s a subclass of
3cb00 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 the following st
3cb10 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 ructure.** to de
3cb20 73 63 72 69 62 65 20 63 75 72 73 6f 72 73 20 74 scribe cursors t
3cb30 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 hat point into t
3cb40 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 he virtual table
3cb50 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a and are used.**
3cb60 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 to loop through
3cb70 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 the virtual tab
3cb80 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 le. Cursors are
3cb90 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 created using t
3cba0 68 65 0a 2a 2a 20 78 4f 70 65 6e 20 6d 65 74 68 he.** xOpen meth
3cbb0 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 od of the module
3cbc0 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 . Each module i
3cbd0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
3cbe0 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 ll define.** the
3cbf0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 content of a cu
3cc00 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 rsor structure t
3cc10 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e o suit its own n
3cc20 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 eeds..**.** This
3cc30 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 superclass exis
3cc40 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 ts in order to d
3cc50 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 efine fields of
3cc60 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a the cursor that.
3cc70 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f ** are common to
3cc80 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 all implementat
3cc90 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ions..**.** This
3cca0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 interface is ex
3ccb0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 perimental and i
3ccc0 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 s subject to cha
3ccd0 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 nge or.** remova
3cce0 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 l in future rele
3ccf0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
3cd00 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 */.struct sqlite
3cd10 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 3_vtab_cursor {.
3cd20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a sqlite3_vtab *
3cd30 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 pVtab; /* V
3cd40 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 irtual table of
3cd50 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 this cursor */.
3cd60 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c /* Virtual tabl
3cd70 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
3cd80 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 s will typically
3cd90 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 add additional
3cda0 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a fields */.};../*
3cdb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
3cdc0 63 6c 61 72 65 20 54 68 65 20 53 63 68 65 6d 61 clare The Schema
3cdd0 20 4f 66 20 41 20 56 69 72 74 75 61 6c 20 54 61 Of A Virtual Ta
3cde0 62 6c 65 20 7b 46 31 38 32 38 30 7d 0a 2a 2a 0a ble {F18280}.**.
3cdf0 2a 2a 20 54 68 65 20 78 43 72 65 61 74 65 20 61 ** The xCreate a
3ce00 6e 64 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 nd xConnect meth
3ce10 6f 64 73 20 6f 66 20 61 20 6d 6f 64 75 6c 65 20 ods of a module
3ce20 75 73 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e use the followin
3ce30 67 20 41 50 49 0a 2a 2a 20 74 6f 20 64 65 63 6c g API.** to decl
3ce40 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 are the format (
3ce50 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 the names and da
3ce60 74 61 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 tatypes of the c
3ce70 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 olumns) of.** th
3ce80 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 e virtual tables
3ce90 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e they implement.
3cea0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
3ceb0 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69 6d rface is experim
3cec0 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 ental and is sub
3ced0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f ject to change o
3cee0 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 r.** removal in
3cef0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
3cf00 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e of SQLite..*/.in
3cf10 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 t sqlite3_declar
3cf20 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c e_vtab(sqlite3*,
3cf30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 72 const char *zCr
3cf40 65 61 74 65 54 61 62 6c 65 29 3b 0a 0a 2f 2a 0a eateTable);../*.
3cf50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65 ** CAPI3REF: Ove
3cf60 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e rload A Function
3cf70 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54 For A Virtual T
3cf80 61 62 6c 65 20 7b 46 31 38 33 30 30 7d 0a 2a 2a able {F18300}.**
3cf90 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c .** Virtual tabl
3cfa0 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61 es can provide a
3cfb0 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 lternative imple
3cfc0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 mentations of fu
3cfd0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 nctions.** using
3cfe0 20 74 68 65 20 78 46 69 6e 64 46 75 6e 63 74 69 the xFindFuncti
3cff0 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42 75 74 20 on method. But
3d000 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 global versions
3d010 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f of those functio
3d020 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 ns.** must exist
3d030 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 in order to be
3d040 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a overloaded..**.*
3d050 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b 65 73 * This API makes
3d060 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 sure a global v
3d070 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 ersion of a func
3d080 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72 74 tion with a part
3d090 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 icular.** name a
3d0a0 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 nd number of par
3d0b0 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e 20 ameters exists.
3d0c0 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 If no such func
3d0d0 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 tion exists.** b
3d0e0 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20 69 efore this API i
3d0f0 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 s called, a new
3d100 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 61 function is crea
3d110 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d ted. The implem
3d120 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 entation.** of t
3d130 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 he new function
3d140 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 61 6e always causes an
3d150 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 exception to be
3d160 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 thrown. So.**
3d170 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e the new function
3d180 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 is not good for
3d190 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74 73 anything by its
3d1a0 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a elf. Its only.*
3d1b0 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f 20 * purpose is to
3d1c0 62 65 20 61 20 70 6c 61 63 65 68 6f 6c 64 65 72 be a placeholder
3d1d0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 function that c
3d1e0 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 an be overloaded
3d1f0 0a 2a 2a 20 62 79 20 76 69 72 74 75 61 6c 20 74 .** by virtual t
3d200 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 ables..**.** Thi
3d210 73 20 41 50 49 20 73 68 6f 75 6c 64 20 62 65 20 s API should be
3d220 63 6f 6e 73 69 64 65 72 65 64 20 70 61 72 74 20 considered part
3d230 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 of the virtual t
3d240 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 2c 0a able interface,.
3d250 2a 2a 20 77 68 69 63 68 20 69 73 20 65 78 70 65 ** which is expe
3d260 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 73 75 62 rimental and sub
3d270 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a ject to change..
3d280 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f */.int sqlite3_o
3d290 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e verload_function
3d2a0 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 (sqlite3*, const
3d2b0 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 char *zFuncName
3d2c0 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a , int nArg);../*
3d2d0 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 .** The interfac
3d2e0 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c e to the virtual
3d2f0 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d -table mechanism
3d300 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 defined above (
3d310 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 back up.** to a
3d320 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 comment remarkab
3d330 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 ly similar to th
3d340 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 is one) is curre
3d350 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a ntly considered.
3d360 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d ** to be experim
3d370 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 ental. The inte
3d380 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e rface might chan
3d390 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 ge in incompatib
3d3a0 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 le ways..** If t
3d3b0 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d his is a problem
3d3c0 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 for you, do not
3d3d0 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 use the interfa
3d3e0 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e ce at this time.
3d3f0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
3d400 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 virtual-table me
3d410 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a chanism stabiliz
3d420 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c es, we will decl
3d430 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 are the.** inter
3d440 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 face fixed, supp
3d450 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 ort it indefinit
3d460 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 ely, and remove
3d470 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a this comment..**
3d480 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 .****** EXPERIME
3d490 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 NTAL - subject t
3d4a0 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 o change without
3d4b0 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a notice ********
3d4c0 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a ******.*/../*.**
3d4d0 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e CAPI3REF: A Han
3d4e0 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 dle To An Open B
3d4f0 4c 4f 42 20 7b 46 31 37 38 30 30 7d 0a 2a 2a 20 LOB {F17800}.**
3d500 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 KEYWORDS: {BLOB
3d510 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 handle} {BLOB ha
3d520 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 ndles}.**.** An
3d530 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
3d540 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e object represen
3d550 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 ts an open BLOB
3d560 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c on which.** [sql
3d570 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c ite3_blob_open |
3d580 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f incremental BLO
3d590 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 B I/O] can be pe
3d5a0 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a 65 rformed..** Obje
3d5b0 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 cts of this type
3d5c0 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20 are created by
3d5d0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
3d5e0 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 en()].** and des
3d5f0 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 troyed by [sqlit
3d600 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d e3_blob_close()]
3d610 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 ..** The [sqlite
3d620 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 3_blob_read()] a
3d630 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 nd [sqlite3_blob
3d640 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 _write()] interf
3d650 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 aces.** can be u
3d660 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 sed to read or w
3d670 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 rite small subse
3d680 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c ctions of the BL
3d690 4f 42 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 OB..** The [sqli
3d6a0 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 te3_blob_bytes()
3d6b0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
3d6c0 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 rns the size of
3d6d0 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 the BLOB in byte
3d6e0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 s..*/.typedef st
3d6f0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f ruct sqlite3_blo
3d700 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a b sqlite3_blob;.
3d710 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
3d720 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 Open A BLOB For
3d730 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f Incremental I/O
3d740 20 7b 46 31 37 38 31 30 7d 0a 2a 2a 0a 2a 2a 20 {F17810}.**.**
3d750 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 73 20 This interfaces
3d760 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 opens a [BLOB ha
3d770 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 ndle | handle] t
3d780 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 o the BLOB locat
3d790 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f ed.** in row iRo
3d7a0 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d w, column zColum
3d7b0 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 n, table zTable
3d7c0 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62 3b in database zDb;
3d7d0 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 .** in other wor
3d7e0 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42 4c 4f ds, the same BLO
3d7f0 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20 B that would be
3d800 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a selected by:.**.
3d810 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 ** <pre>.**
3d820 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 SELECT zColumn F
3d830 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 ROM zDb.zTable W
3d840 48 45 52 45 20 72 6f 77 69 64 20 3d 20 69 52 6f HERE rowid = iRo
3d850 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e w;.** </pre> {EN
3d860 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 D}.**.** If the
3d870 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 flags parameter
3d880 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 is non-zero, the
3d890 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 the BLOB is ope
3d8a0 6e 65 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 ned for read.**
3d8b0 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73 and write access
3d8c0 2e 20 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c . If it is zero,
3d8d0 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 the BLOB is ope
3d8e0 6e 65 64 20 66 6f 72 20 72 65 61 64 20 61 63 63 ned for read acc
3d8f0 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 ess..**.** Note
3d900 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 that the databas
3d910 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 e name is not th
3d920 65 20 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 e filename that
3d930 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 contains.** the
3d940 64 61 74 61 62 61 73 65 20 62 75 74 20 72 61 74 database but rat
3d950 68 65 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 her the symbolic
3d960 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
3d970 61 62 61 73 65 20 74 68 61 74 0a 2a 2a 20 69 73 abase that.** is
3d980 20 61 73 73 69 67 6e 65 64 20 77 68 65 6e 20 74 assigned when t
3d990 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 63 he database is c
3d9a0 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b onnected using [
3d9b0 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 46 6f 72 20 ATTACH]..** For
3d9c0 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 the main databas
3d9d0 65 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 e file, the data
3d9e0 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 base name is "ma
3d9f0 69 6e 22 2e 0a 2a 2a 20 46 6f 72 20 54 45 4d 50 in"..** For TEMP
3da00 20 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 tables, the dat
3da10 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 abase name is "t
3da20 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 emp"..**.** On s
3da30 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f uccess, [SQLITE_
3da40 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 OK] is returned
3da50 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f and the new [BLO
3da60 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 B handle] is wri
3da70 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c tten.** to *ppBl
3da80 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e ob. Otherwise an
3da90 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 [error code] is
3daa0 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e returned and an
3dab0 79 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e 0a y value written.
3dac0 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 20 73 68 ** to *ppBlob sh
3dad0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 ould not be used
3dae0 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 0a by the caller..
3daf0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
3db00 20 73 65 74 73 20 74 68 65 20 5b 64 61 74 61 62 sets the [datab
3db10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
3db20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d error code and m
3db30 65 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 essage.** access
3db40 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 ible via [sqlite
3db50 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 3_errcode()] and
3db60 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
3db70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ()]..**.** If th
3db80 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f e row that a BLO
3db90 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 B handle points
3dba0 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62 to is modified b
3dbb0 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d y an.** [UPDATE]
3dbc0 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 , [DELETE], or b
3dbd0 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 y [ON CONFLICT]
3dbe0 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 side-effects.**
3dbf0 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 then the BLOB ha
3dc00 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61 ndle is marked a
3dc10 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 s "expired"..**
3dc20 54 68 69 73 20 69 73 20 74 72 75 65 20 69 66 20 This is true if
3dc30 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 any column of th
3dc40 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64 e row is changed
3dc50 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a , even a column.
3dc60 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 ** other than th
3dc70 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 e one the BLOB h
3dc80 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e andle is open on
3dc90 2e 0a 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 5b 73 ..** Calls to [s
3dca0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 qlite3_blob_read
3dcb0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
3dcc0 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 _blob_write()] f
3dcd0 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 20 or.** a expired
3dce0 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 6c BLOB handle fail
3dcf0 20 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e 20 with an return
3dd00 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f code of [SQLITE_
3dd10 41 42 4f 52 54 5d 2e 0a 2a 2a 20 43 68 61 6e 67 ABORT]..** Chang
3dd20 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 es written into
3dd30 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 a BLOB prior to
3dd40 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69 6e the BLOB expirin
3dd50 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c g are not.** rol
3dd60 6c 62 61 63 6b 20 62 79 20 74 68 65 20 65 78 70 lback by the exp
3dd70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 iration of the B
3dd80 4c 4f 42 2e 20 20 53 75 63 68 20 63 68 61 6e 67 LOB. Such chang
3dd90 65 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c es will eventual
3dda0 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 ly.** commit if
3ddb0 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 the transaction
3ddc0 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d continues to com
3ddd0 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 pletion..**.** I
3dde0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
3ddf0 20 7b 46 31 37 38 31 33 7d 20 41 20 73 75 63 63 {F17813} A succ
3de00 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f essful invocatio
3de10 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 n of the [sqlite
3de20 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 42 2c 3_blob_open(D,B,
3de30 54 2c 43 2c 52 2c 46 2c 50 29 5d 0a 2a 2a 20 20 T,C,R,F,P)].**
3de40 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 interfac
3de50 65 20 73 68 61 6c 6c 20 6f 70 65 6e 20 61 6e 20 e shall open an
3de60 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f [sqlite3_blob] o
3de70 62 6a 65 63 74 20 50 20 6f 6e 20 74 68 65 20 42 bject P on the B
3de80 4c 4f 42 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 LOB.**
3de90 69 6e 20 63 6f 6c 75 6d 6e 20 43 20 6f 66 20 74 in column C of t
3dea0 68 65 20 74 61 62 6c 65 20 54 20 69 6e 20 74 68 he table T in th
3deb0 65 20 64 61 74 61 62 61 73 65 20 42 20 6f 6e 0a e database B on.
3dec0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
3ded0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
3dee0 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b tion] D..**.** {
3def0 46 31 37 38 31 34 7d 20 41 20 73 75 63 63 65 73 F17814} A succes
3df00 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 sful invocation
3df10 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 of [sqlite3_blob
3df20 5f 6f 70 65 6e 28 44 2c 2e 2e 2e 29 5d 20 73 68 _open(D,...)] sh
3df30 61 6c 6c 20 73 74 61 72 74 0a 2a 2a 20 20 20 20 all start.**
3df40 20 20 20 20 20 20 61 20 6e 65 77 20 74 72 61 6e a new tran
3df50 73 61 63 74 69 6f 6e 20 6f 6e 20 74 68 65 20 5b saction on the [
3df60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3df70 69 6f 6e 5d 20 44 20 69 66 20 74 68 61 74 0a 2a ion] D if that.*
3df80 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65 * conne
3df90 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 6c 72 ction is not alr
3dfa0 65 61 64 79 20 69 6e 20 61 20 74 72 61 6e 73 61 eady in a transa
3dfb0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 ction..**.** {F1
3dfc0 37 38 31 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 7816} The [sqlit
3dfd0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 42 e3_blob_open(D,B
3dfe0 2c 54 2c 43 2c 52 2c 46 2c 50 29 5d 20 69 6e 74 ,T,C,R,F,P)] int
3dff0 65 72 66 61 63 65 20 73 68 61 6c 6c 20 6f 70 65 erface shall ope
3e000 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 n.** th
3e010 65 20 42 4c 4f 42 20 66 6f 72 20 72 65 61 64 20 e BLOB for read
3e020 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73 and write access
3e030 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 if and only if
3e040 74 68 65 20 46 0a 2a 2a 20 20 20 20 20 20 20 20 the F.**
3e050 20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e parameter is n
3e060 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b on-zero..**.** {
3e070 46 31 37 38 31 39 7d 20 54 68 65 20 5b 73 71 6c F17819} The [sql
3e080 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 ite3_blob_open()
3e090 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c ] interface shal
3e0a0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
3e0b0 5f 4f 4b 5d 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 _OK] on.**
3e0c0 20 20 20 20 73 75 63 63 65 73 73 20 61 6e 64 20 success and
3e0d0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b an appropriate [
3e0e0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 error code] on f
3e0f0 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 ailure..**.** {F
3e100 31 37 38 32 31 7d 20 49 66 20 61 6e 20 65 72 72 17821} If an err
3e110 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 or occurs during
3e120 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b evaluation of [
3e130 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
3e140 6e 28 44 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 n(D,...)].**
3e150 20 20 20 20 20 20 74 68 65 6e 20 73 75 62 73 65 then subse
3e160 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b quent calls to [
3e170 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
3e180 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 D)],.**
3e190 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
3e1a0 28 44 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 (D)], and [sqlit
3e1b0 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 20 e3_errmsg16(D)]
3e1c0 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 shall return.**
3e1d0 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 informa
3e1e0 74 69 6f 6e 20 61 70 70 72 6f 70 72 69 61 74 65 tion appropriate
3e1f0 20 66 6f 72 20 74 68 61 74 20 65 72 72 6f 72 2e for that error.
3e200 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 32 34 7d 20 .**.** {F17824}
3e210 49 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 69 6e If any column in
3e220 20 74 68 65 20 72 6f 77 20 74 68 61 74 20 61 20 the row that a
3e230 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 68 [sqlite3_blob] h
3e240 61 73 20 6f 70 65 6e 20 69 73 0a 2a 2a 20 20 20 as open is.**
3e250 20 20 20 20 20 20 20 63 68 61 6e 67 65 64 20 62 changed b
3e260 79 20 61 20 73 65 70 61 72 61 74 65 20 5b 55 50 y a separate [UP
3e270 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 DATE] or [DELETE
3e280 5d 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 62 ] statement or b
3e290 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e y.** an
3e2a0 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 [ON CONFLICT] s
3e2b0 69 64 65 20 65 66 66 65 63 74 2c 20 74 68 65 6e ide effect, then
3e2c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c the [sqlite3_bl
3e2d0 6f 62 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 ob] shall.**
3e2e0 20 20 20 20 20 20 62 65 20 6d 61 72 6b 65 64 20 be marked
3e2f0 61 73 20 69 6e 76 61 6c 69 64 2e 0a 2a 2f 0a 69 as invalid..*/.i
3e300 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f nt sqlite3_blob_
3e310 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a open(. sqlite3*
3e320 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
3e330 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 zDb,. const cha
3e340 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e r *zTable,. con
3e350 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e st char *zColumn
3e360 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 ,. sqlite3_int6
3e370 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 4 iRow,. int fl
3e380 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 ags,. sqlite3_b
3e390 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a lob **ppBlob.);.
3e3a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
3e3b0 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 Close A BLOB Ha
3e3c0 6e 64 6c 65 20 7b 46 31 37 38 33 30 7d 0a 2a 2a ndle {F17830}.**
3e3d0 0a 2a 2a 20 43 6c 6f 73 65 73 20 61 6e 20 6f 70 .** Closes an op
3e3e0 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d en [BLOB handle]
3e3f0 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 ..**.** Closing
3e400 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 a BLOB shall cau
3e410 73 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 se the current t
3e420 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f ransaction to co
3e430 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 mmit.** if there
3e440 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c are no other BL
3e450 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 OBs, no pending
3e460 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
3e470 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 nts, and the.**
3e480 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3e490 69 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 ion is in [autoc
3e4a0 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 ommit mode]..**
3e4b0 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 77 65 If any writes we
3e4c0 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42 re made to the B
3e4d0 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20 LOB, they might
3e4e0 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65 be held in cache
3e4f0 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c .** until the cl
3e500 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66 ose operation if
3e510 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 20 they will fit.
3e520 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 {END}.**.** Clos
3e530 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 ing the BLOB oft
3e540 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 en forces the ch
3e550 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 anges.** out to
3e560 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 disk and so if a
3e570 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 ny I/O errors oc
3e580 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c cur, they will l
3e590 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 ikely occur.** a
3e5a0 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 t the time when
3e5b0 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 the BLOB is clos
3e5c0 65 64 2e 20 20 7b 46 31 37 38 33 33 7d 20 41 6e ed. {F17833} An
3e5d0 79 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 y errors that oc
3e5e0 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c cur during.** cl
3e5f0 6f 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 osing are report
3e600 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f ed as a non-zero
3e610 20 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 0a 2a return value..*
3e620 2a 0a 2a 2a 20 54 68 65 20 42 4c 4f 42 20 69 73 *.** The BLOB is
3e630 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 closed uncondit
3e640 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 ionally. Even i
3e650 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 f this routine r
3e660 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 eturns.** an err
3e670 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f or code, the BLO
3e680 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 B is still close
3e690 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 d..**.** INVARIA
3e6a0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 NTS:.**.** {F178
3e6b0 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 33} The [sqlite3
3e6c0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 50 29 5d 20 _blob_close(P)]
3e6d0 69 6e 74 65 72 66 61 63 65 20 63 6c 6f 73 65 73 interface closes
3e6e0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f an [sqlite3_blo
3e6f0 62 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f b].** o
3e700 62 6a 65 63 74 20 50 20 70 72 65 76 69 6f 75 73 bject P previous
3e710 6c 79 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 20 ly opened using
3e720 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
3e730 65 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 en()]..**.** {F1
3e740 37 38 33 36 7d 20 43 6c 6f 73 69 6e 67 20 61 6e 7836} Closing an
3e750 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 [sqlite3_blob]
3e760 6f 62 6a 65 63 74 20 75 73 69 6e 67 0a 2a 2a 20 object using.**
3e770 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
3e780 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 3_blob_close()]
3e790 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 shall cause the
3e7a0 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 current transact
3e7b0 69 6f 6e 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 ion to.**
3e7c0 20 20 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 commit if the
3e7d0 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 re are no other
3e7e0 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c open [sqlite3_bl
3e7f0 6f 62 5d 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 20 ob] objects.**
3e800 20 20 20 20 20 20 20 20 6f 72 20 5b 70 72 65 70 or [prep
3e810 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
3e820 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 on the same [da
3e830 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3e840 6e 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 n] and.**
3e850 20 20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 the database
3e860 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e connection is in
3e870 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 [autocommit mod
3e880 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 33 e]..**.** {F1783
3e890 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 9} The [sqlite3_
3e8a0 62 6c 6f 62 5f 63 6c 6f 73 65 28 50 29 5d 20 69 blob_close(P)] i
3e8b0 6e 74 65 72 66 61 63 65 73 20 73 68 61 6c 6c 20 nterfaces shall
3e8c0 63 6c 6f 73 65 20 74 68 65 0a 2a 2a 20 20 20 20 close the.**
3e8d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 [sqlite3_b
3e8e0 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 50 20 75 6e lob] object P un
3e8f0 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 65 conditionally, e
3e900 76 65 6e 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 ven if.**
3e910 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 [sqlite3_blob
3e920 5f 63 6c 6f 73 65 28 50 29 5d 20 72 65 74 75 72 _close(P)] retur
3e930 6e 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 ns something oth
3e940 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
3e950 4f 4b 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 OK]..*/.int sqli
3e960 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 te3_blob_close(s
3e970 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a qlite3_blob *);.
3e980 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
3e990 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 Return The Size
3e9a0 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 Of An Open BLOB
3e9b0 20 7b 46 31 37 38 34 30 7d 0a 2a 2a 0a 2a 2a 20 {F17840}.**.**
3e9c0 52 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 Returns the size
3e9d0 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 in bytes of the
3e9e0 20 42 4c 4f 42 20 61 63 63 65 73 73 69 62 6c 65 BLOB accessible
3e9f0 20 76 69 61 20 74 68 65 20 6f 70 65 6e 0a 2a 2a via the open.**
3ea00 20 5b 5d 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 []BLOB handle]
3ea10 69 6e 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 in its only argu
3ea20 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 ment..**.** INVA
3ea30 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 RIANTS:.**.** {F
3ea40 31 37 38 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 17843} The [sqli
3ea50 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 50 te3_blob_bytes(P
3ea60 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
3ea70 75 72 6e 73 20 74 68 65 20 73 69 7a 65 0a 2a 2a urns the size.**
3ea80 20 20 20 20 20 20 20 20 20 20 69 6e 20 62 79 74 in byt
3ea90 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 74 es of the BLOB t
3eaa0 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 hat the [sqlite3
3eab0 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 50 0a _blob] object P.
3eac0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 66 65 ** refe
3ead0 72 73 20 74 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 rs to..*/.int sq
3eae0 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 lite3_blob_bytes
3eaf0 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 (sqlite3_blob *)
3eb00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
3eb10 46 3a 20 52 65 61 64 20 44 61 74 61 20 46 72 6f F: Read Data Fro
3eb20 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 m A BLOB Increme
3eb30 6e 74 61 6c 6c 79 20 7b 46 31 37 38 35 30 7d 0a ntally {F17850}.
3eb40 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 **.** This funct
3eb50 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 ion is used to r
3eb60 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e ead data from an
3eb70 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 open [BLOB hand
3eb80 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 le] into a.** ca
3eb90 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 ller-supplied bu
3eba0 66 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 ffer. N bytes of
3ebb0 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 data are copied
3ebc0 20 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a into buffer Z.*
3ebd0 2a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 * from the open
3ebe0 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 BLOB, starting a
3ebf0 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 t offset iOffset
3ec00 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 66 66 73 65 ..**.** If offse
3ec10 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 t iOffset is les
3ec20 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 s than N bytes f
3ec30 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 rom the end of t
3ec40 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c he BLOB,.** [SQL
3ec50 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 ITE_ERROR] is re
3ec60 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 turned and no da
3ec70 74 61 20 69 73 20 72 65 61 64 2e 20 20 49 66 20 ta is read. If
3ec80 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a N or iOffset is.
3ec90 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 ** less than zer
3eca0 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 o, [SQLITE_ERROR
3ecb0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e ] is returned an
3ecc0 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 d no data is rea
3ecd0 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 d..**.** An atte
3ece0 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d mpt to read from
3ecf0 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f an expired [BLO
3ed00 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 B handle] fails
3ed10 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 with an.** error
3ed20 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 code of [SQLITE
3ed30 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f _ABORT]..**.** O
3ed40 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 n success, SQLIT
3ed50 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 E_OK is returned
3ed60 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 ..** Otherwise,
3ed70 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
3ed80 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 or an [extended
3ed90 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
3eda0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 eturned..**.** I
3edb0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
3edc0 20 7b 46 31 37 38 35 33 7d 20 41 20 73 75 63 63 {F17853} A succ
3edd0 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f essful invocatio
3ede0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c n of [sqlite3_bl
3edf0 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 ob_read(P,Z,N,X)
3ee00 5d 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 ] .** s
3ee10 68 61 6c 6c 20 72 65 61 64 73 20 4e 20 62 79 74 hall reads N byt
3ee20 65 73 20 6f 66 20 64 61 74 61 20 6f 75 74 20 6f es of data out o
3ee30 66 20 74 68 65 20 42 4c 4f 42 20 72 65 66 65 72 f the BLOB refer
3ee40 65 6e 63 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 enced by.**
3ee50 20 20 20 20 20 5b 42 4c 4f 42 20 68 61 6e 64 6c [BLOB handl
3ee60 65 5d 20 50 20 62 65 67 69 6e 6e 69 6e 67 20 61 e] P beginning a
3ee70 74 20 6f 66 66 73 65 74 20 58 20 61 6e 64 20 73 t offset X and s
3ee80 74 6f 72 65 20 74 68 6f 73 65 20 62 79 74 65 73 tore those bytes
3ee90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 .** int
3eea0 6f 20 62 75 66 66 65 72 20 5a 2e 0a 2a 2a 0a 2a o buffer Z..**.*
3eeb0 2a 20 7b 46 31 37 38 35 36 7d 20 49 6e 20 5b 73 * {F17856} In [s
3eec0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 qlite3_blob_read
3eed0 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 66 20 74 68 (P,Z,N,X)] if th
3eee0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c e size of the BL
3eef0 4f 42 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 OB.** i
3ef00 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 2b 58 20 s less than N+X
3ef10 62 79 74 65 73 2c 20 74 68 65 6e 20 74 68 65 20 bytes, then the
3ef20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 6c function shall l
3ef30 65 61 76 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 eave the.**
3ef40 20 20 20 20 20 5a 20 62 75 66 66 65 72 20 75 6e Z buffer un
3ef50 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 changed and retu
3ef60 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 rn [SQLITE_ERROR
3ef70 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 35 39 ]..**.** {F17859
3ef80 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c } In [sqlite3_bl
3ef90 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 ob_read(P,Z,N,X)
3efa0 5d 20 69 66 20 58 20 6f 72 20 4e 20 69 73 20 6c ] if X or N is l
3efb0 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 0a 2a 2a ess than zero.**
3efc0 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 then t
3efd0 68 65 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c he function shal
3efe0 6c 20 6c 65 61 76 65 20 74 68 65 20 5a 20 62 75 l leave the Z bu
3eff0 66 66 65 72 20 75 6e 63 68 61 6e 67 65 64 0a 2a ffer unchanged.*
3f000 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 72 * and r
3f010 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 eturn [SQLITE_ER
3f020 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 ROR]..**.** {F17
3f030 38 36 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 862} The [sqlite
3f040 33 5f 62 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 3_blob_read(P,Z,
3f050 4e 2c 58 29 5d 20 69 6e 74 65 72 66 61 63 65 20 N,X)] interface
3f060 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 shall return [SQ
3f070 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 20 20 20 20 LITE_OK].**
3f080 20 20 20 20 20 69 66 20 4e 20 62 79 74 65 73 20 if N bytes
3f090 61 72 65 20 73 75 63 63 65 73 73 66 75 6c 6c 79 are successfully
3f0a0 20 72 65 61 64 20 69 6e 74 6f 20 62 75 66 66 65 read into buffe
3f0b0 72 20 5a 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 r Z..**.** {F178
3f0c0 36 33 7d 20 49 66 20 74 68 65 20 5b 42 4c 4f 42 63} If the [BLOB
3f0d0 20 68 61 6e 64 6c 65 5d 20 50 20 69 73 20 65 78 handle] P is ex
3f0e0 70 69 72 65 64 20 61 6e 64 20 58 20 61 6e 64 20 pired and X and
3f0f0 4e 20 61 72 65 20 77 69 74 68 69 6e 20 62 6f 75 N are within bou
3f100 6e 64 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 nds.**
3f110 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c then [sqlite3_bl
3f120 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 ob_read(P,Z,N,X)
3f130 5d 20 73 68 61 6c 6c 20 6c 65 61 76 65 20 74 68 ] shall leave th
3f140 65 20 5a 20 62 75 66 66 65 72 0a 2a 2a 20 20 20 e Z buffer.**
3f150 20 20 20 20 20 20 20 75 6e 63 68 61 6e 67 65 64 unchanged
3f160 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c and return [SQL
3f170 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a ITE_ABORT]..**.*
3f180 2a 20 7b 46 31 37 38 36 35 7d 20 49 66 20 74 68 * {F17865} If th
3f190 65 20 72 65 71 75 65 73 74 65 64 20 72 65 61 64 e requested read
3f1a0 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 6f could not be co
3f1b0 6d 70 6c 65 74 65 64 2c 0a 2a 2a 20 20 20 20 20 mpleted,.**
3f1c0 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 the [sqlite
3f1d0 33 5f 62 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 3_blob_read(P,Z,
3f1e0 4e 2c 58 29 5d 20 69 6e 74 65 72 66 61 63 65 20 N,X)] interface
3f1f0 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 6e 0a shall return an.
3f200 2a 2a 20 20 20 20 20 20 20 20 20 20 61 70 70 72 ** appr
3f210 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 opriate [error c
3f220 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 ode] or [extende
3f230 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a d error code]..*
3f240 2a 0a 2a 2a 20 7b 46 31 37 38 36 38 7d 20 49 66 *.** {F17868} If
3f250 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
3f260 20 64 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69 during evaluati
3f270 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 on of [sqlite3_b
3f280 6c 6f 62 5f 72 65 61 64 28 50 2c 2e 2e 2e 29 5d lob_read(P,...)]
3f290 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
3f2a0 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c n subsequent cal
3f2b0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 ls to [sqlite3_e
3f2c0 72 72 63 6f 64 65 28 44 29 5d 2c 0a 2a 2a 20 20 rrcode(D)],.**
3f2d0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
3f2e0 5f 65 72 72 6d 73 67 28 44 29 5d 2c 20 61 6e 64 _errmsg(D)], and
3f2f0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
3f300 31 36 28 44 29 5d 20 73 68 61 6c 6c 20 72 65 74 16(D)] shall ret
3f310 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 urn.**
3f320 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 70 70 72 information appr
3f330 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 61 74 opriate for that
3f340 20 65 72 72 6f 72 2c 20 77 68 65 72 65 20 44 20 error, where D
3f350 69 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 is the.**
3f360 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e [database con
3f370 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 77 61 nection] that wa
3f380 73 20 75 73 65 64 20 74 6f 20 6f 70 65 6e 20 74 s used to open t
3f390 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d he [BLOB handle]
3f3a0 20 50 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 P..*/.int sqlit
3f3b0 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c e3_blob_read(sql
3f3c0 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 ite3_blob *, voi
3f3d0 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 d *Z, int N, int
3f3e0 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a iOffset);../*.*
3f3f0 2a 20 43 41 50 49 33 52 45 46 3a 20 57 72 69 74 * CAPI3REF: Writ
3f400 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42 4c e Data Into A BL
3f410 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 OB Incrementally
3f420 20 7b 46 31 37 38 37 30 7d 0a 2a 2a 0a 2a 2a 20 {F17870}.**.**
3f430 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 This function is
3f440 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 used to write d
3f450 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e ata into an open
3f460 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 [BLOB handle] f
3f470 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d rom a.** caller-
3f480 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e supplied buffer.
3f490 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 N bytes of data
3f4a0 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d are copied from
3f4b0 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a the buffer Z.**
3f4c0 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 into the open B
3f4d0 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 LOB, starting at
3f4e0 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e offset iOffset.
3f4f0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 42 .**.** If the [B
3f500 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 LOB handle] pass
3f510 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ed as the first
3f520 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 argument was not
3f530 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 opened for.** w
3f540 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 riting (the flag
3f550 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b s parameter to [
3f560 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
3f570 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a n()] was zero),.
3f580 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e ** this function
3f590 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
3f5a0 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a _READONLY]..**.*
3f5b0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
3f5c0 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 may only modify
3f5d0 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 the contents of
3f5e0 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a the BLOB; it is.
3f5f0 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 ** not possible
3f600 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 to increase the
3f610 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 size of a BLOB u
3f620 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a sing this API..*
3f630 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 * If offset iOff
3f640 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e set is less than
3f650 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 N bytes from th
3f660 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f e end of the BLO
3f670 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 B,.** [SQLITE_ER
3f680 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ROR] is returned
3f690 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 and no data is
3f6a0 77 72 69 74 74 65 6e 2e 20 20 49 66 20 4e 20 69 written. If N i
3f6b0 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a s.** less than z
3f6c0 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f ero [SQLITE_ERRO
3f6d0 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 R] is returned a
3f6e0 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 nd no data is wr
3f6f0 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 itten..**.** An
3f700 61 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 attempt to write
3f710 20 74 6f 20 61 6e 20 65 78 70 69 72 65 64 20 5b to an expired [
3f720 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 BLOB handle] fai
3f730 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 ls with an.** er
3f740 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c ror code of [SQL
3f750 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20 57 72 69 ITE_ABORT]. Wri
3f760 74 65 73 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 tes to the BLOB
3f770 74 68 61 74 20 6f 63 63 75 72 72 65 64 0a 2a 2a that occurred.**
3f780 20 62 65 66 6f 72 65 20 74 68 65 20 5b 42 4c 4f before the [BLO
3f790 42 20 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 65 B handle] expire
3f7a0 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 64 d are not rolled
3f7b0 20 62 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a 20 back by the.**
3f7c0 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 expiration of th
3f7d0 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67 68 e handle, though
3f7e0 20 6f 66 20 63 6f 75 72 73 65 20 74 68 6f 73 65 of course those
3f7f0 20 63 68 61 6e 67 65 73 20 6d 69 67 68 74 0a 2a changes might.*
3f800 2a 20 68 61 76 65 20 62 65 65 6e 20 6f 76 65 72 * have been over
3f810 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 73 written by the s
3f820 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 65 78 tatement that ex
3f830 70 69 72 65 64 20 74 68 65 20 42 4c 4f 42 20 68 pired the BLOB h
3f840 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 6f andle.** or by o
3f850 74 68 65 72 20 69 6e 64 65 70 65 6e 64 65 6e 74 ther independent
3f860 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a statements..**.
3f870 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 ** On success, S
3f880 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 QLITE_OK is retu
3f890 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 rned..** Otherwi
3f8a0 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f 72 20 63 se, an [error c
3f8b0 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 ode] or an [exte
3f8c0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d nded error code]
3f8d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
3f8e0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
3f8f0 2a 2a 0a 2a 2a 20 7b 46 31 37 38 37 33 7d 20 41 **.** {F17873} A
3f900 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f successful invo
3f910 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 cation of [sqlit
3f920 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50 2c e3_blob_write(P,
3f930 5a 2c 4e 2c 58 29 5d 0a 2a 2a 20 20 20 20 20 20 Z,N,X)].**
3f940 20 20 20 20 73 68 61 6c 6c 20 77 72 69 74 65 20 shall write
3f950 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 N bytes of data
3f960 66 72 6f 6d 20 62 75 66 66 65 72 20 5a 20 69 6e from buffer Z in
3f970 74 6f 20 74 68 65 20 42 4c 4f 42 20 0a 2a 2a 20 to the BLOB .**
3f980 20 20 20 20 20 20 20 20 20 72 65 66 65 72 65 6e referen
3f990 63 65 64 20 62 79 20 5b 42 4c 4f 42 20 68 61 6e ced by [BLOB han
3f9a0 64 6c 65 5d 20 50 20 62 65 67 69 6e 6e 69 6e 67 dle] P beginning
3f9b0 20 61 74 20 6f 66 66 73 65 74 20 58 20 69 6e 74 at offset X int
3f9c0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 o.** th
3f9d0 65 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 7b 46 e BLOB..**.** {F
3f9e0 31 37 38 37 34 7d 20 49 6e 20 74 68 65 20 61 62 17874} In the ab
3f9f0 73 65 6e 63 65 20 6f 66 20 6f 74 68 65 72 20 6f sence of other o
3fa00 76 65 72 72 69 64 64 69 6e 67 20 63 68 61 6e 67 verridding chang
3fa10 65 73 2c 20 74 68 65 20 63 68 61 6e 67 65 73 0a es, the changes.
3fa20 2a 2a 20 20 20 20 20 20 20 20 20 20 77 72 69 74 ** writ
3fa30 74 65 6e 20 74 6f 20 61 20 42 4c 4f 42 20 62 79 ten to a BLOB by
3fa40 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 [sqlite3_blob_w
3fa50 72 69 74 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a rite()] shall.**
3fa60 20 20 20 20 20 20 20 20 20 20 72 65 6d 61 69 6e remain
3fa70 20 69 6e 20 65 66 66 65 63 74 20 61 66 74 65 72 in effect after
3fa80 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 the associated
3fa90 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 [BLOB handle] ex
3faa0 70 69 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 pires..**.** {F1
3fab0 37 38 37 35 7d 20 49 66 20 74 68 65 20 5b 42 4c 7875} If the [BL
3fac0 4f 42 20 68 61 6e 64 6c 65 5d 20 50 20 77 61 73 OB handle] P was
3fad0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 opened for read
3fae0 69 6e 67 20 6f 6e 6c 79 20 74 68 65 6e 0a 2a 2a ing only then.**
3faf0 20 20 20 20 20 20 20 20 20 20 61 6e 20 69 6e 76 an inv
3fb00 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 ocation of [sqli
3fb10 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50 te3_blob_write(P
3fb20 2c 5a 2c 4e 2c 58 29 5d 20 73 68 61 6c 6c 20 6c ,Z,N,X)] shall l
3fb30 65 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 eave.**
3fb40 20 74 68 65 20 72 65 66 65 72 65 6e 63 65 64 20 the referenced
3fb50 42 4c 4f 42 20 75 6e 63 68 61 6e 67 65 64 20 61 BLOB unchanged a
3fb60 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 nd return [SQLIT
3fb70 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a E_READONLY]..**.
3fb80 2a 2a 20 7b 46 31 37 38 37 36 7d 20 49 66 20 74 ** {F17876} If t
3fb90 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 he size of the B
3fba0 4c 4f 42 20 72 65 66 65 72 65 6e 63 65 64 20 62 LOB referenced b
3fbb0 79 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 y [BLOB handle]
3fbc0 50 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 P is.**
3fbd0 20 6c 65 73 73 20 74 68 61 6e 20 4e 2b 58 20 62 less than N+X b
3fbe0 79 74 65 73 20 74 68 65 6e 20 5b 73 71 6c 69 74 ytes then [sqlit
3fbf0 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50 2c e3_blob_write(P,
3fc00 5a 2c 4e 2c 58 29 5d 20 73 68 61 6c 6c 0a 2a 2a Z,N,X)] shall.**
3fc10 20 20 20 20 20 20 20 20 20 20 6c 65 61 76 65 20 leave
3fc20 74 68 65 20 42 4c 4f 42 20 75 6e 63 68 61 6e 67 the BLOB unchang
3fc30 65 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 ed and return [S
3fc40 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a QLITE_ERROR]..**
3fc50 0a 2a 2a 20 7b 46 31 37 38 37 37 7d 20 49 66 20 .** {F17877} If
3fc60 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 the [BLOB handle
3fc70 5d 20 50 20 69 73 20 65 78 70 69 72 65 64 20 61 ] P is expired a
3fc80 6e 64 20 58 20 61 6e 64 20 4e 20 61 72 65 20 77 nd X and N are w
3fc90 69 74 68 69 6e 20 62 6f 75 6e 64 73 0a 2a 2a 20 ithin bounds.**
3fca0 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 then [s
3fcb0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 qlite3_blob_read
3fcc0 28 50 2c 5a 2c 4e 2c 58 29 5d 20 73 68 61 6c 6c (P,Z,N,X)] shall
3fcd0 20 6c 65 61 76 65 20 74 68 65 20 42 4c 4f 42 0a leave the BLOB.
3fce0 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 63 68 ** unch
3fcf0 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e anged and return
3fd00 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e [SQLITE_ABORT].
3fd10 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 37 39 7d 20 .**.** {F17879}
3fd20 49 66 20 58 20 6f 72 20 4e 20 61 72 65 20 6c 65 If X or N are le
3fd30 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 74 68 65 ss than zero the
3fd40 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f n [sqlite3_blob_
3fd50 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29 5d 0a write(P,Z,N,X)].
3fd60 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c ** shal
3fd70 6c 20 6c 65 61 76 65 20 74 68 65 20 42 4c 4f 42 l leave the BLOB
3fd80 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 5b referenced by [
3fd90 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 50 20 75 BLOB handle] P u
3fda0 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 20 20 20 20 nchanged.**
3fdb0 20 20 20 20 20 61 6e 64 20 72 65 74 75 72 6e 20 and return
3fdc0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a [SQLITE_ERROR]..
3fdd0 2a 2a 0a 2a 2a 20 7b 46 31 37 38 38 32 7d 20 54 **.** {F17882} T
3fde0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 he [sqlite3_blob
3fdf0 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29 5d _write(P,Z,N,X)]
3fe00 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c interface shall
3fe10 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 return.**
3fe20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 [SQLITE_OK]
3fe30 69 66 20 4e 20 62 79 74 65 73 20 77 68 65 72 65 if N bytes where
3fe40 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 77 72 successfully wr
3fe50 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 42 itten into the B
3fe60 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 LOB..**.** {F178
3fe70 38 35 7d 20 49 66 20 74 68 65 20 72 65 71 75 65 85} If the reque
3fe80 73 74 65 64 20 77 72 69 74 65 20 63 6f 75 6c 64 sted write could
3fe90 20 6e 6f 74 20 62 65 20 63 6f 6d 70 6c 65 74 65 not be complete
3fea0 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 d,.** t
3feb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 he [sqlite3_blob
3fec0 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29 5d _write(P,Z,N,X)]
3fed0 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c interface shall
3fee0 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 20 20 return an.**
3fef0 20 20 20 20 20 20 20 61 70 70 72 6f 70 72 69 61 appropria
3ff00 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 te [error code]
3ff10 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 or [extended err
3ff20 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 or code]..**.**
3ff30 7b 46 31 37 38 38 38 7d 20 49 66 20 61 6e 20 65 {F17888} If an e
3ff40 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 rror occurs duri
3ff50 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 ng evaluation of
3ff60 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 [sqlite3_blob_w
3ff70 72 69 74 65 28 44 2c 2e 2e 2e 29 5d 0a 2a 2a 20 rite(D,...)].**
3ff80 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 73 75 then su
3ff90 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 bsequent calls t
3ffa0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f o [sqlite3_errco
3ffb0 64 65 28 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 de(D)],.**
3ffc0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 [sqlite3_err
3ffd0 6d 73 67 28 44 29 5d 2c 20 61 6e 64 20 5b 73 71 msg(D)], and [sq
3ffe0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44 lite3_errmsg16(D
3fff0 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a )] shall return.
40000 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f ** info
40010 72 6d 61 74 69 6f 6e 20 61 70 70 72 6f 70 72 69 rmation appropri
40020 61 74 65 20 66 6f 72 20 74 68 61 74 20 65 72 72 ate for that err
40030 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 or..*/.int sqlit
40040 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 e3_blob_write(sq
40050 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f lite3_blob *, co
40060 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 nst void *z, int
40070 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 n, int iOffset)
40080 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
40090 46 3a 20 56 69 72 74 75 61 6c 20 46 69 6c 65 20 F: Virtual File
400a0 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 20 7b System Objects {
400b0 46 31 31 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 20 F11200}.**.** A
400c0 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73 74 virtual filesyst
400d0 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20 5b em (VFS) is an [
400e0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
400f0 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 ect.** that SQLi
40100 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65 72 te uses to inter
40110 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 act.** with the
40120 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 underlying opera
40130 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f ting system. Mo
40140 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c 64 73 st SQLite builds
40150 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 come with a.**
40160 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20 56 single default V
40170 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72 6f FS that is appro
40180 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20 68 priate for the h
40190 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a ost computer..**
401a0 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20 62 New VFSes can b
401b0 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 e registered and
401c0 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73 20 existing VFSes
401d0 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74 65 can be unregiste
401e0 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c red..** The foll
401f0 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 owing interfaces
40200 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a are provided..*
40210 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
40220 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 _vfs_find() inte
40230 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
40240 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 46 53 pointer to a VFS
40250 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e given its name.
40260 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 63 61 .** Names are ca
40270 73 65 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a se sensitive..**
40280 20 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d Names are zero-
40290 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 terminated UTF-8
402a0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 strings..** If
402b0 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 there is no matc
402c0 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 h, a NULL pointe
402d0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a r is returned..*
402e0 2a 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 * If zVfsName is
402f0 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 NULL then the d
40300 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 72 65 efault VFS is re
40310 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 turned..**.** Ne
40320 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67 69 w VFSes are regi
40330 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c 69 stered with sqli
40340 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 te3_vfs_register
40350 28 29 2e 0a 2a 2a 20 45 61 63 68 20 6e 65 77 20 ()..** Each new
40360 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65 20 VFS becomes the
40370 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 20 74 default VFS if t
40380 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 he makeDflt flag
40390 20 69 73 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 is set..** The
403a0 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62 65 20 same VFS can be
403b0 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 registered multi
403c0 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 6f 75 ple times withou
403d0 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 t injury..** To
403e0 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e 67 make an existing
403f0 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64 65 VFS into the de
40400 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69 73 fault VFS, regis
40410 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 ter it again.**
40420 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66 6c with the makeDfl
40430 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66 20 t flag set. If
40440 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56 46 two different VF
40450 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 Ses with the.**
40460 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72 65 same name are re
40470 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 62 65 gistered, the be
40480 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
40490 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46 ned. If a.** VF
404a0 53 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 S is registered
404b0 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61 74 with a name that
404c0 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 is NULL or an e
404d0 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 mpty string,.**
404e0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
404f0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a r is undefined..
40500 2a 2a 0a 2a 2a 20 55 6e 72 65 67 69 73 74 65 72 **.** Unregister
40510 20 61 20 56 46 53 20 77 69 74 68 20 74 68 65 20 a VFS with the
40520 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 sqlite3_vfs_unre
40530 67 69 73 74 65 72 28 29 20 69 6e 74 65 72 66 61 gister() interfa
40540 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64 65 ce..** If the de
40550 66 61 75 6c 74 20 56 46 53 20 69 73 20 75 6e 72 fault VFS is unr
40560 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 egistered, anoth
40570 65 72 20 56 46 53 20 69 73 20 63 68 6f 73 65 6e er VFS is chosen
40580 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 as.** the defau
40590 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63 65 20 lt. The choice
405a0 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46 53 20 for the new VFS
405b0 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a is arbitrary..**
405c0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
405d0 2a 2a 0a 2a 2a 20 7b 46 31 31 32 30 33 7d 20 54 **.** {F11203} T
405e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f he [sqlite3_vfs_
405f0 66 69 6e 64 28 4e 29 5d 20 69 6e 74 65 72 66 61 find(N)] interfa
40600 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
40610 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 nter to the.**
40620 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 register
40630 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d ed [sqlite3_vfs]
40640 20 6f 62 6a 65 63 74 20 77 68 6f 73 65 20 6e 61 object whose na
40650 6d 65 20 65 78 61 63 74 6c 79 20 6d 61 74 63 68 me exactly match
40660 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 es.** t
40670 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 he zero-terminat
40680 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 ed UTF-8 string
40690 4e 2c 20 6f 72 20 69 74 20 72 65 74 75 72 6e 73 N, or it returns
406a0 20 4e 55 4c 4c 20 69 66 0a 2a 2a 20 20 20 20 20 NULL if.**
406b0 20 20 20 20 20 74 68 65 72 65 20 69 73 20 6e 6f there is no
406c0 20 6d 61 74 63 68 2e 0a 2a 2a 0a 2a 2a 20 7b 46 match..**.** {F
406d0 31 31 32 30 36 7d 20 49 66 20 74 68 65 20 4e 20 11206} If the N
406e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
406f0 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 4e lite3_vfs_find(N
40700 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a )] is NULL then.
40710 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
40720 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
40730 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
40740 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 e default [sqlit
40750 65 33 5f 76 66 73 5d 0a 2a 2a 20 20 20 20 20 20 e3_vfs].**
40760 20 20 20 20 6f 62 6a 65 63 74 20 69 66 20 74 68 object if th
40770 65 72 65 20 69 73 20 6f 6e 65 2c 20 6f 72 20 4e ere is one, or N
40780 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 ULL if there is
40790 6e 6f 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 no default.**
407a0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
407b0 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a vfs] object..**.
407c0 2a 2a 20 7b 46 31 31 32 30 39 7d 20 54 68 65 20 ** {F11209} The
407d0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 [sqlite3_vfs_reg
407e0 69 73 74 65 72 28 50 2c 46 29 5d 20 69 6e 74 65 ister(P,F)] inte
407f0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 rface registers
40800 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
40810 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 5b 73 71 6c well-formed [sql
40820 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
40830 20 50 20 75 73 69 6e 67 20 74 68 65 20 6e 61 6d P using the nam
40840 65 20 67 69 76 65 6e 0a 2a 2a 20 20 20 20 20 20 e given.**
40850 20 20 20 20 62 79 20 74 68 65 20 7a 4e 61 6d 65 by the zName
40860 20 66 69 65 6c 64 20 6f 66 20 74 68 65 20 6f 62 field of the ob
40870 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 ject..**.** {F11
40880 32 31 32 7d 20 55 73 69 6e 67 20 74 68 65 20 5b 212} Using the [
40890 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 sqlite3_vfs_regi
408a0 73 74 65 72 28 50 2c 46 29 5d 20 69 6e 74 65 72 ster(P,F)] inter
408b0 66 61 63 65 20 74 6f 20 72 65 67 69 73 74 65 72 face to register
408c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
408d0 20 73 61 6d 65 20 5b 73 71 6c 69 74 65 33 5f 76 same [sqlite3_v
408e0 66 73 5d 20 6f 62 6a 65 63 74 20 6d 75 6c 74 69 fs] object multi
408f0 70 6c 65 20 74 69 6d 65 73 20 69 73 20 61 20 68 ple times is a h
40900 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a armless no-op..*
40910 2a 0a 2a 2a 20 7b 46 31 31 32 31 35 7d 20 54 68 *.** {F11215} Th
40920 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 e [sqlite3_vfs_r
40930 65 67 69 73 74 65 72 28 50 2c 46 29 5d 20 69 6e egister(P,F)] in
40940 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 74 68 terface makes th
40950 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 0a e [sqlite3_vfs].
40960 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65 ** obje
40970 63 74 20 50 20 74 68 65 20 64 65 66 61 75 6c 74 ct P the default
40980 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
40990 62 6a 65 63 74 20 69 66 20 46 20 69 73 20 6e 6f bject if F is no
409a0 6e 2d 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 n-zero..**.** {F
409b0 31 31 32 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 11218} The [sqli
409c0 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 te3_vfs_unregist
409d0 65 72 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65 er(P)] interface
409e0 20 75 6e 72 65 67 69 73 74 65 72 73 20 74 68 65 unregisters the
409f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
40a00 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
40a10 74 20 50 20 73 6f 20 74 68 61 74 20 69 74 20 69 t P so that it i
40a20 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 74 75 s no longer retu
40a30 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 rned by.**
40a40 20 20 20 20 73 75 62 73 65 71 75 65 6e 74 20 63 subsequent c
40a50 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
40a60 5f 76 66 73 5f 66 69 6e 64 28 29 5d 2e 0a 2a 2f _vfs_find()]..*/
40a70 0a 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 .sqlite3_vfs *sq
40a80 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 lite3_vfs_find(c
40a90 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e onst char *zVfsN
40aa0 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ame);.int sqlite
40ab0 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 73 3_vfs_register(s
40ac0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 qlite3_vfs*, int
40ad0 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 makeDflt);.int
40ae0 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 sqlite3_vfs_unre
40af0 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 gister(sqlite3_v
40b00 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 fs*);../*.** CAP
40b10 49 33 52 45 46 3a 20 4d 75 74 65 78 65 73 20 7b I3REF: Mutexes {
40b20 46 31 37 30 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 F17000}.**.** Th
40b30 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 e SQLite core us
40b40 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 es these routine
40b50 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 s for thread.**
40b60 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e synchronization.
40b70 20 54 68 6f 75 67 68 20 74 68 65 79 20 61 72 65 Though they are
40b80 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e intended for in
40b90 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 ternal.** use by
40ba0 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 SQLite, code th
40bb0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 at links against
40bc0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 SQLite is.** pe
40bd0 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20 61 rmitted to use a
40be0 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
40bf0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ines..**.** The
40c00 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f SQLite source co
40c10 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 de contains mult
40c20 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 iple implementat
40c30 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65 ions.** of these
40c40 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e mutex routines.
40c50 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65 An appropriate
40c60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a implementation.
40c70 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20 61 ** is selected a
40c80 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 utomatically at
40c90 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 54 compile-time. T
40ca0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 he following.**
40cb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
40cc0 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e are available in
40cd0 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 the SQLite core
40ce0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
40cf0 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
40d00 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 TEX_OS2.** <li>
40d10 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 SQLITE_MUTEX_P
40d20 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 THREAD.** <li>
40d30 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 SQLITE_MUTEX_W3
40d40 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 2.** <li> SQLI
40d50 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a TE_MUTEX_NOOP.**
40d60 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 </ul>.**.** The
40d70 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f SQLITE_MUTEX_NO
40d80 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f OP implementatio
40d90 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f n is a set of ro
40da0 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74 20 64 utines.** that d
40db0 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b oes no real lock
40dc0 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f ing and is appro
40dd0 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 69 priate for use i
40de0 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68 n.** a single-th
40df0 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 readed applicati
40e00 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f on. The SQLITE_
40e10 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 MUTEX_OS2,.** SQ
40e20 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 LITE_MUTEX_PTHRE
40e30 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d AD, and SQLITE_M
40e40 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65 UTEX_W32 impleme
40e50 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 ntations.** are
40e60 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 appropriate for
40e70 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55 6e 69 use on OS/2, Uni
40e80 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73 2e 0a x, and Windows..
40e90 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 **.** If SQLite
40ea0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
40eb0 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 the SQLITE_MUTE
40ec0 58 5f 41 50 50 44 45 46 20 70 72 65 70 72 6f 63 X_APPDEF preproc
40ed0 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64 essor.** macro d
40ee0 65 66 69 6e 65 64 20 28 77 69 74 68 20 22 2d 44 efined (with "-D
40ef0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 SQLITE_MUTEX_APP
40f00 44 45 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f DEF=1"), then no
40f10 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d mutex.** implem
40f20 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c entation is incl
40f30 75 64 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 uded with the li
40f40 62 72 61 72 79 2e 20 49 6e 20 74 68 69 73 20 63 brary. In this c
40f50 61 73 65 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 ase the.** appli
40f60 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 cation must supp
40f70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d 75 74 65 ly a custom mute
40f80 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e x implementation
40f90 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 using the.** [S
40fa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
40fb0 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 20 74 68 EX] option of th
40fc0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
40fd0 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 62 () function.** b
40fe0 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20 73 71 efore calling sq
40ff0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
41000 28 29 20 6f 72 20 61 6e 79 20 6f 74 68 65 72 20 () or any other
41010 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 0a public sqlite3_.
41020 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 ** function that
41030 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 calls sqlite3_i
41040 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a nitialize()..**.
41050 2a 2a 20 7b 46 31 37 30 31 31 7d 20 54 68 65 20 ** {F17011} The
41060 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
41070 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61 6c loc() routine al
41080 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a locates a new.**
41090 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75 72 mutex and retur
410a0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
410b0 69 74 2e 20 7b 46 31 37 30 31 32 7d 20 49 66 20 it. {F17012} If
410c0 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a it returns NULL.
410d0 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 ** that means th
410e0 61 74 20 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 at a mutex could
410f0 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 not be allocate
41100 64 2e 20 7b 46 31 37 30 31 33 7d 20 53 51 4c 69 d. {F17013} SQLi
41110 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e te.** will unwin
41120 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20 d its stack and
41130 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e return an error.
41140 20 7b 46 31 37 30 31 34 7d 20 54 68 65 20 61 72 {F17014} The ar
41150 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c gument.** to sql
41160 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 ite3_mutex_alloc
41170 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 () is one of the
41180 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 se integer const
41190 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ants:.**.** <ul>
411a0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
411b0 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c _MUTEX_FAST.** <
411c0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 li> SQLITE_MUTE
411d0 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c X_RECURSIVE.** <
411e0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 li> SQLITE_MUTE
411f0 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 0a X_STATIC_MASTER.
41200 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
41210 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d MUTEX_STATIC_MEM
41220 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
41230 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 _MUTEX_STATIC_ME
41240 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 M2.** <li> SQLI
41250 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
41260 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 PRNG.** <li> SQ
41270 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
41280 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 C_LRU.** <li> S
41290 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
412a0 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e IC_LRU2.** </ul>
412b0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30 31 35 7d 20 .**.** {F17015}
412c0 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 63 6f The first two co
412d0 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20 73 71 nstants cause sq
412e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f lite3_mutex_allo
412f0 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a c() to create.**
41300 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 54 a new mutex. T
41310 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73 20 he new mutex is
41320 72 65 63 75 72 73 69 76 65 20 77 68 65 6e 20 53 recursive when S
41330 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 QLITE_MUTEX_RECU
41340 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65 64 RSIVE.** is used
41350 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73 61 but not necessa
41360 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51 4c rily so when SQL
41370 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 ITE_MUTEX_FAST i
41380 73 20 75 73 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a s used. {END}.**
41390 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70 6c 65 The mutex imple
413a0 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e mentation does n
413b0 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65 20 ot need to make
413c0 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a a distinction.**
413d0 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f between SQLITE_
413e0 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 MUTEX_RECURSIVE
413f0 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 and SQLITE_MUTEX
41400 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f 65 73 _FAST if it does
41410 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f 2e .** not want to.
41420 20 20 7b 46 31 37 30 31 36 7d 20 42 75 74 20 53 {F17016} But S
41430 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 QLite will only
41440 72 65 71 75 65 73 74 20 61 20 72 65 63 75 72 73 request a recurs
41450 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 ive mutex in.**
41460 63 61 73 65 73 20 77 68 65 72 65 20 69 74 20 72 cases where it r
41470 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65 2e eally needs one.
41480 20 20 7b 45 4e 44 7d 20 49 66 20 61 20 66 61 73 {END} If a fas
41490 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 ter non-recursiv
414a0 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 e mutex.** imple
414b0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 76 61 mentation is ava
414c0 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f ilable on the ho
414d0 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 st platform, the
414e0 20 6d 75 74 65 78 20 73 75 62 73 79 73 74 65 6d mutex subsystem
414f0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75 72 6e .** might return
41500 20 73 75 63 68 20 61 20 6d 75 74 65 78 20 69 6e such a mutex in
41510 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c response to SQL
41520 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a ITE_MUTEX_FAST..
41530 2a 2a 0a 2a 2a 20 7b 46 31 37 30 31 37 7d 20 54 **.** {F17017} T
41540 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65 64 he other allowed
41550 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 73 parameters to s
41560 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
41570 6f 63 28 29 20 65 61 63 68 20 72 65 74 75 72 6e oc() each return
41580 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f .** a pointer to
41590 20 61 20 73 74 61 74 69 63 20 70 72 65 65 78 69 a static preexi
415a0 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 7b 45 4e sting mutex. {EN
415b0 44 7d 20 20 46 6f 75 72 20 73 74 61 74 69 63 20 D} Four static
415c0 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 mutexes are.** u
415d0 73 65 64 20 62 79 20 74 68 65 20 63 75 72 72 65 sed by the curre
415e0 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 nt version of SQ
415f0 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20 76 65 Lite. Future ve
41600 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
41610 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64 64 69 .** may add addi
41620 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 tional static mu
41630 74 65 78 65 73 2e 20 20 53 74 61 74 69 63 20 6d texes. Static m
41640 75 74 65 78 65 73 20 61 72 65 20 66 6f 72 20 69 utexes are for i
41650 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 nternal.** use b
41660 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 y SQLite only.
41670 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
41680 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 75 74 t use SQLite mut
41690 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 exes should.** u
416a0 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 se only the dyna
416b0 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65 74 75 mic mutexes retu
416c0 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45 5f 4d rned by SQLITE_M
416d0 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 UTEX_FAST or.**
416e0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 SQLITE_MUTEX_REC
416f0 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 URSIVE..**.** {F
41700 31 37 30 31 38 7d 20 4e 6f 74 65 20 74 68 61 74 17018} Note that
41710 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 if one of the d
41720 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70 61 72 ynamic mutex par
41730 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54 45 5f ameters (SQLITE_
41740 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 MUTEX_FAST.** or
41750 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 SQLITE_MUTEX_RE
41760 43 55 52 53 49 56 45 29 20 69 73 20 75 73 65 64 CURSIVE) is used
41770 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 then sqlite3_mu
41780 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 tex_alloc().** r
41790 65 74 75 72 6e 73 20 61 20 64 69 66 66 65 72 65 eturns a differe
417a0 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 nt mutex on ever
417b0 79 20 63 61 6c 6c 2e 20 20 7b 46 31 37 30 33 34 y call. {F17034
417c0 7d 20 42 75 74 20 66 6f 72 20 74 68 65 20 73 74 } But for the st
417d0 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 74 79 atic.** mutex ty
417e0 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20 6d 75 pes, the same mu
417f0 74 65 78 20 69 73 20 72 65 74 75 72 6e 65 64 20 tex is returned
41800 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20 74 68 on every call th
41810 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20 73 61 at has.** the sa
41820 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a me type number..
41830 2a 2a 0a 2a 2a 20 7b 46 31 37 30 31 39 7d 20 54 **.** {F17019} T
41840 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 he sqlite3_mutex
41850 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 _free() routine
41860 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 deallocates a pr
41870 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f eviously.** allo
41880 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 cated dynamic mu
41890 74 65 78 2e 20 7b 46 31 37 30 32 30 7d 20 53 51 tex. {F17020} SQ
418a0 4c 69 74 65 20 69 73 20 63 61 72 65 66 75 6c 20 Lite is careful
418b0 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 65 76 to deallocate ev
418c0 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d ery.** dynamic m
418d0 75 74 65 78 20 74 68 61 74 20 69 74 20 61 6c 6c utex that it all
418e0 6f 63 61 74 65 73 2e 20 7b 41 31 37 30 32 31 7d ocates. {A17021}
418f0 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 The dynamic mut
41900 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 exes must not be
41910 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 in.** use when
41920 74 68 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 they are dealloc
41930 61 74 65 64 2e 20 7b 41 31 37 30 32 32 7d 20 41 ated. {A17022} A
41940 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 ttempting to dea
41950 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 74 69 63 llocate a static
41960 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 75 6c 74 .** mutex result
41970 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 s in undefined b
41980 65 68 61 76 69 6f 72 2e 20 7b 46 31 37 30 32 33 ehavior. {F17023
41990 7d 20 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64 } SQLite never d
419a0 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20 eallocates.** a
419b0 73 74 61 74 69 63 20 6d 75 74 65 78 2e 20 7b 45 static mutex. {E
419c0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ND}.**.** The sq
419d0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 lite3_mutex_ente
419e0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f r() and sqlite3_
419f0 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 mutex_try() rout
41a00 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 ines attempt.**
41a10 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 to enter a mutex
41a20 2e 20 7b 46 31 37 30 32 34 7d 20 49 66 20 61 6e . {F17024} If an
41a30 6f 74 68 65 72 20 74 68 72 65 61 64 20 69 73 20 other thread is
41a40 61 6c 72 65 61 64 79 20 77 69 74 68 69 6e 20 74 already within t
41a50 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c he mutex,.** sql
41a60 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 ite3_mutex_enter
41a70 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e () will block an
41a80 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f d sqlite3_mutex_
41a90 74 72 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72 try() will retur
41aa0 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 n.** SQLITE_BUSY
41ab0 2e 20 7b 46 31 37 30 32 35 7d 20 20 54 68 65 20 . {F17025} The
41ac0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 sqlite3_mutex_tr
41ad0 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 y() interface re
41ae0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
41af0 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65 73 ].** upon succes
41b00 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 7b 46 31 sful entry. {F1
41b10 37 30 32 36 7d 20 4d 75 74 65 78 65 73 20 63 72 7026} Mutexes cr
41b20 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 53 eated using.** S
41b30 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 QLITE_MUTEX_RECU
41b40 52 53 49 56 45 20 63 61 6e 20 62 65 20 65 6e 74 RSIVE can be ent
41b50 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 ered multiple ti
41b60 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d 65 20 mes by the same
41b70 74 68 72 65 61 64 2e 0a 2a 2a 20 7b 46 31 37 30 thread..** {F170
41b80 32 37 7d 20 49 6e 20 73 75 63 68 20 63 61 73 65 27} In such case
41b90 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 s the,.** mutex
41ba0 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20 61 must be exited a
41bb0 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f n equal number o
41bc0 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61 f times before a
41bd0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a nother thread.**
41be0 20 63 61 6e 20 65 6e 74 65 72 2e 20 20 7b 41 31 can enter. {A1
41bf0 37 30 32 38 7d 20 49 66 20 74 68 65 20 73 61 6d 7028} If the sam
41c00 65 20 74 68 72 65 61 64 20 74 72 69 65 73 20 74 e thread tries t
41c10 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 o enter any othe
41c20 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d 75 74 r.** kind of mut
41c30 65 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 ex more than onc
41c40 65 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 e, the behavior
41c50 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
41c60 20 7b 46 31 37 30 32 39 7d 20 53 51 4c 69 74 65 {F17029} SQLite
41c70 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 will never exhi
41c80 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 bit.** such beha
41c90 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 vior in its own
41ca0 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73 2e 0a use of mutexes..
41cb0 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73 79 73 74 65 **.** Some syste
41cc0 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c ms (for example,
41cd0 20 57 69 6e 64 6f 77 73 20 39 35 29 20 64 6f 20 Windows 95) do
41ce0 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68 65 20 not support the
41cf0 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d 70 operation.** imp
41d00 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 71 6c 69 lemented by sqli
41d10 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2e te3_mutex_try().
41d20 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73 74 65 On those syste
41d30 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 ms, sqlite3_mute
41d40 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 6c 6c 20 x_try().** will
41d50 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 53 51 always return SQ
41d60 4c 49 54 45 5f 42 55 53 59 2e 20 20 7b 46 31 37 LITE_BUSY. {F17
41d70 30 33 30 7d 20 54 68 65 20 53 51 4c 69 74 65 20 030} The SQLite
41d80 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 core only ever u
41d90 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d ses.** sqlite3_m
41da0 75 74 65 78 5f 74 72 79 28 29 20 61 73 20 61 6e utex_try() as an
41db0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f optimization so
41dc0 20 74 68 69 73 20 69 73 20 61 63 63 65 70 74 61 this is accepta
41dd0 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ble behavior..**
41de0 0a 2a 2a 20 7b 46 31 37 30 33 31 7d 20 54 68 65 .** {F17031} The
41df0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c sqlite3_mutex_l
41e00 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65 20 65 eave() routine e
41e10 78 69 74 73 20 61 20 6d 75 74 65 78 20 74 68 61 xits a mutex tha
41e20 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 t was.** previou
41e30 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 sly entered by t
41e40 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 20 he same thread.
41e50 20 7b 41 31 37 30 33 32 7d 20 54 68 65 20 62 65 {A17032} The be
41e60 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 havior.** is und
41e70 65 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d 75 efined if the mu
41e80 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72 65 tex is not curre
41e90 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 ntly entered by
41ea0 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 the.** calling t
41eb0 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74 20 hread or is not
41ec0 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 currently alloca
41ed0 74 65 64 2e 20 20 7b 46 31 37 30 33 33 7d 20 53 ted. {F17033} S
41ee0 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 QLite will.** ne
41ef0 76 65 72 20 64 6f 20 65 69 74 68 65 72 2e 20 7b ver do either. {
41f00 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 END}.**.** If th
41f10 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 e argument to sq
41f20 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 lite3_mutex_ente
41f30 72 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 r(), sqlite3_mut
41f40 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a 2a 20 ex_try(), or.**
41f50 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 sqlite3_mutex_le
41f60 61 76 65 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 ave() is a NULL
41f70 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 61 6c pointer, then al
41f80 6c 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 l three routines
41f90 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 20 6e 6f .** behave as no
41fa0 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 -ops..**.** See
41fb0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d also: [sqlite3_m
41fc0 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64 utex_held()] and
41fd0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
41fe0 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 notheld()]..*/.s
41ff0 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 qlite3_mutex *sq
42000 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f lite3_mutex_allo
42010 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c c(int);.void sql
42020 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 ite3_mutex_free(
42030 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b sqlite3_mutex*);
42040 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 .void sqlite3_mu
42050 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74 65 tex_enter(sqlite
42060 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 3_mutex*);.int s
42070 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 qlite3_mutex_try
42080 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 (sqlite3_mutex*)
42090 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d ;.void sqlite3_m
420a0 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69 74 utex_leave(sqlit
420b0 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a e3_mutex*);../*.
420c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 ** CAPI3REF: Mut
420d0 65 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 ex Methods Objec
420e0 74 20 7b 46 31 37 31 32 30 7d 0a 2a 2a 0a 2a 2a t {F17120}.**.**
420f0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
42100 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 64 this structure d
42110 65 66 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c efines the low-l
42120 65 76 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a evel routines.**
42130 20 75 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 used to allocat
42140 65 20 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65 e and use mutexe
42150 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 s..**.** Usually
42160 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 , the default mu
42170 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 tex implementati
42180 6f 6e 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 ons provided by
42190 53 51 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 SQLite are.** su
421a0 66 66 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 fficient, howeve
421b0 72 20 74 68 65 20 75 73 65 72 20 68 61 73 20 74 r the user has t
421c0 68 65 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 he option of sub
421d0 73 74 69 74 75 74 69 6e 67 20 61 20 63 75 73 74 stituting a cust
421e0 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 om.** implementa
421f0 74 69 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c tion for special
42200 69 7a 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 ized deployments
42210 20 6f 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20 or systems for
42220 77 68 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 which SQLite.**
42230 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 does not provide
42240 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c a suitable impl
42250 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 ementation. In t
42260 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 75 73 his case, the us
42270 65 72 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e er.** creates an
42280 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 d populates an i
42290 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
422a0 73 74 72 75 63 74 75 72 65 20 74 6f 20 70 61 73 structure to pas
422b0 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f s.** to sqlite3_
422c0 63 6f 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 config() along w
422d0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
422e0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 CONFIG_MUTEX] op
422f0 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f tion..** Additio
42300 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e nally, an instan
42310 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 ce of this struc
42320 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 ture can be used
42330 20 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 as an.** output
42340 20 76 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71 variable when q
42350 75 65 72 79 69 6e 67 20 74 68 65 20 73 79 73 74 uerying the syst
42360 65 6d 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 em for the curre
42370 6e 74 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c nt mutex.** impl
42380 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e ementation, usin
42390 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f g the [SQLITE_CO
423a0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f NFIG_GETMUTEX] o
423b0 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ption..**.** The
423c0 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 xMutexInit meth
423d0 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 od defined by th
423e0 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 is structure is
423f0 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 invoked as.** pa
42400 72 74 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 rt of system ini
42410 74 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 tialization by t
42420 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 he sqlite3_initi
42430 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e alize() function
42440 2e 0a 2a 2a 20 7b 46 31 37 30 30 31 7d 20 54 68 ..** {F17001} Th
42450 65 20 78 4d 75 74 65 78 49 6e 69 74 20 72 6f 75 e xMutexInit rou
42460 74 69 6e 65 20 73 68 61 6c 6c 20 62 65 20 63 61 tine shall be ca
42470 6c 6c 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f lled by SQLite o
42480 6e 63 65 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 nce for each.**
42490 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 effective call t
424a0 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 o [sqlite3_initi
424b0 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 alize()]..**.**
424c0 54 68 65 20 78 4d 75 74 65 78 45 6e 64 20 6d 65 The xMutexEnd me
424d0 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 thod defined by
424e0 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 69 this structure i
424f0 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 s invoked as.**
42500 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20 73 part of system s
42510 68 75 74 64 6f 77 6e 20 62 79 20 74 68 65 20 73 hutdown by the s
42520 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
42530 29 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a ) function. The.
42540 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
42550 6e 20 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64 n of this method
42560 20 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 is expected to
42570 72 65 6c 65 61 73 65 20 61 6c 6c 20 6f 75 74 73 release all outs
42580 74 61 6e 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 tanding.** resou
42590 72 63 65 73 20 6f 62 74 61 69 6e 65 64 20 62 79 rces obtained by
425a0 20 74 68 65 20 6d 75 74 65 78 20 6d 65 74 68 6f the mutex metho
425b0 64 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ds implementatio
425c0 6e 2c 20 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a n, especially.**
425d0 20 74 68 6f 73 65 20 6f 62 74 61 69 6e 65 64 20 those obtained
425e0 62 79 20 74 68 65 20 78 4d 75 74 65 78 49 6e 69 by the xMutexIni
425f0 74 20 6d 65 74 68 6f 64 2e 20 7b 46 31 37 30 30 t method. {F1700
42600 33 7d 20 54 68 65 20 78 4d 75 74 65 78 45 6e 64 3} The xMutexEnd
42610 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
42620 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 shall be invoked
42630 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63 once for each c
42640 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
42650 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a shutdown()]..**.
42660 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 ** The remaining
42670 20 73 65 76 65 6e 20 6d 65 74 68 6f 64 73 20 64 seven methods d
42680 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 efined by this s
42690 74 72 75 63 74 75 72 65 20 28 78 4d 75 74 65 78 tructure (xMutex
426a0 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 Alloc,.** xMutex
426b0 46 72 65 65 2c 20 78 4d 75 74 65 78 45 6e 74 65 Free, xMutexEnte
426c0 72 2c 20 78 4d 75 74 65 78 54 72 79 2c 20 78 4d r, xMutexTry, xM
426d0 75 74 65 78 4c 65 61 76 65 2c 20 78 4d 75 74 65 utexLeave, xMute
426e0 78 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 xHeld and.** xMu
426f0 74 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c texNotheld) impl
42700 65 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77 ement the follow
42710 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 28 ing interfaces (
42720 72 65 73 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a respectively):.*
42730 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c *.** <ul>.** <
42740 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 li> [sqlite3_mu
42750 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c tex_alloc()] </l
42760 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 i>.** <li> [s
42770 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 qlite3_mutex_fre
42780 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 e()] </li>.**
42790 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
427a0 75 74 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f utex_enter()] </
427b0 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b li>.** <li> [
427c0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 sqlite3_mutex_tr
427d0 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 y()] </li>.**
427e0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
427f0 75 74 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f utex_leave()] </
42800 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b li>.** <li> [
42810 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 sqlite3_mutex_he
42820 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 ld()] </li>.**
42830 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
42840 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d mutex_notheld()]
42850 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a </li>.** </ul>.
42860 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 64 **.** The only d
42870 69 66 66 65 72 65 6e 63 65 20 69 73 20 74 68 61 ifference is tha
42880 74 20 74 68 65 20 70 75 62 6c 69 63 20 73 71 6c t the public sql
42890 69 74 65 33 5f 58 58 58 20 66 75 6e 63 74 69 6f ite3_XXX functio
428a0 6e 73 20 65 6e 75 6d 65 72 61 74 65 64 0a 2a 2a ns enumerated.**
428b0 20 61 62 6f 76 65 20 73 69 6c 65 6e 74 6c 79 20 above silently
428c0 69 67 6e 6f 72 65 20 61 6e 79 20 69 6e 76 6f 63 ignore any invoc
428d0 61 74 69 6f 6e 73 20 74 68 61 74 20 70 61 73 73 ations that pass
428e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
428f0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 instead.** of a
42900 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 valid mutex hand
42910 6c 65 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e le. The implemen
42920 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 6d tations of the m
42930 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64 0a 2a ethods defined.*
42940 2a 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74 * by this struct
42950 75 72 65 20 61 72 65 20 6e 6f 74 20 72 65 71 75 ure are not requ
42960 69 72 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 74 ired to handle t
42970 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 72 65 his case, the re
42980 73 75 6c 74 73 0a 2a 2a 20 6f 66 20 70 61 73 73 sults.** of pass
42990 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ing a NULL point
429a0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 er instead of a
429b0 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 valid mutex hand
429c0 6c 65 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 le are undefined
429d0 0a 2a 2a 20 28 69 2e 65 2e 20 69 74 20 69 73 20 .** (i.e. it is
429e0 61 63 63 65 70 74 61 62 6c 65 20 74 6f 20 70 72 acceptable to pr
429f0 6f 76 69 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65 ovide an impleme
42a00 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 73 65 67 ntation that seg
42a10 66 61 75 6c 74 73 20 69 66 0a 2a 2a 20 69 74 20 faults if.** it
42a20 69 73 20 70 61 73 73 65 64 20 61 20 4e 55 4c 4c is passed a NULL
42a30 20 70 6f 69 6e 74 65 72 29 2e 0a 2a 2f 0a 74 79 pointer)..*/.ty
42a40 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
42a50 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
42a60 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ds sqlite3_mutex
42a70 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 _methods;.struct
42a80 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d sqlite3_mutex_m
42a90 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 ethods {. int (
42aa0 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69 *xMutexInit)(voi
42ab0 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 d);. int (*xMut
42ac0 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 exEnd)(void);.
42ad0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 sqlite3_mutex *(
42ae0 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e *xMutexAlloc)(in
42af0 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 t);. void (*xMu
42b00 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 65 33 texFree)(sqlite3
42b10 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 _mutex *);. voi
42b20 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 d (*xMutexEnter)
42b30 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a (sqlite3_mutex *
42b40 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 );. int (*xMute
42b50 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 xTry)(sqlite3_mu
42b60 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 tex *);. void (
42b70 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71 *xMutexLeave)(sq
42b80 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a lite3_mutex *);.
42b90 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 int (*xMutexHe
42ba0 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 ld)(sqlite3_mute
42bb0 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d x *);. int (*xM
42bc0 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c utexNotheld)(sql
42bd0 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d ite3_mutex *);.}
42be0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
42bf0 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69 63 F: Mutex Verific
42c00 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b ation Routines {
42c10 46 31 37 30 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 F17080}.**.** Th
42c20 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f e sqlite3_mutex_
42c30 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c 69 74 held() and sqlit
42c40 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 e3_mutex_notheld
42c50 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 () routines.** a
42c60 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 re intended for
42c70 75 73 65 20 69 6e 73 69 64 65 20 61 73 73 65 72 use inside asser
42c80 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 t() statements.
42c90 7b 46 31 37 30 38 31 7d 20 54 68 65 20 53 51 4c {F17081} The SQL
42ca0 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 ite core.** neve
42cb0 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 r uses these rou
42cc0 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 tines except ins
42cd0 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 ide an assert()
42ce0 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 and applications
42cf0 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 .** are advised
42d00 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 to follow the le
42d10 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 ad of the core.
42d20 20 7b 46 31 37 30 38 32 7d 20 54 68 65 20 63 6f {F17082} The co
42d30 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 re only.** provi
42d40 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 des implementati
42d50 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f ons for these ro
42d60 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 utines when it i
42d70 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 s compiled.** wi
42d80 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 th the SQLITE_DE
42d90 42 55 47 20 66 6c 61 67 2e 20 20 7b 41 31 37 30 BUG flag. {A170
42da0 38 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 87} External mut
42db0 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ex implementatio
42dc0 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 ns.** are only r
42dd0 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 equired to provi
42de0 64 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 de these routine
42df0 73 20 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55 s if SQLITE_DEBU
42e00 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 G is.** defined
42e10 61 6e 64 20 69 66 20 4e 44 45 42 55 47 20 69 73 and if NDEBUG is
42e20 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a not defined..**
42e30 0a 2a 2a 20 7b 46 31 37 30 38 33 7d 20 54 68 65 .** {F17083} The
42e40 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 se routines shou
42e50 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 ld return true i
42e60 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 f the mutex in t
42e70 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a heir argument.**
42e80 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 is held or not
42e90 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 held, respective
42ea0 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 ly, by the calli
42eb0 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a ng thread..**.**
42ec0 20 7b 58 31 37 30 38 34 7d 20 54 68 65 20 69 6d {X17084} The im
42ed0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 plementation is
42ee0 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 not required to
42ef0 70 72 6f 76 69 64 65 64 20 76 65 72 73 69 6f 6e provided version
42f00 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f s of these.** ro
42f10 75 74 69 6e 65 73 20 74 68 61 74 20 61 63 74 75 utines that actu
42f20 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 66 20 74 68 ally work. If th
42f30 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
42f40 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 does not provid
42f50 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 e working.** ver
42f60 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 72 sions of these r
42f70 6f 75 74 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 outines, it shou
42f80 6c 64 20 61 74 20 6c 65 61 73 74 20 70 72 6f 76 ld at least prov
42f90 69 64 65 20 73 74 75 62 73 20 74 68 61 74 20 61 ide stubs that a
42fa0 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e 20 lways.** return
42fb0 74 72 75 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 true so that one
42fc0 20 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 70 does not get sp
42fd0 75 72 69 6f 75 73 20 61 73 73 65 72 74 69 6f 6e urious assertion
42fe0 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a failures..**.**
42ff0 20 7b 46 31 37 30 38 35 7d 20 49 66 20 74 68 65 {F17085} If the
43000 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
43010 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 ite3_mutex_held(
43020 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e ) is a NULL poin
43030 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 ter then.** the
43040 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 routine should r
43050 65 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44 7d 20 eturn 1. {END}
43060 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 This seems count
43070 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e er-intuitive sin
43080 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 ce.** clearly th
43090 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 e mutex cannot b
430a0 65 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65 e held if it doe
430b0 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75 s not exist. Bu
430c0 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 t the.** the rea
430d0 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f son the mutex do
430e0 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20 es not exist is
430f0 62 65 63 61 75 73 65 20 74 68 65 20 62 75 69 6c because the buil
43100 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e d is not.** usin
43110 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20 g mutexes. And
43120 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 we do not want t
43130 68 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74 he assert() cont
43140 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 aining the.** ca
43150 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 ll to sqlite3_mu
43160 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 tex_held() to fa
43170 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 il, so a non-zer
43180 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 o return is.** t
43190 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 he appropriate t
431a0 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b 46 31 hing to do. {F1
431b0 37 30 38 36 7d 20 54 68 65 20 73 71 6c 69 74 65 7086} The sqlite
431c0 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 3_mutex_notheld(
431d0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 ).** interface s
431e0 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72 hould also retur
431f0 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61 n 1 when given a
43200 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
43210 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 /.int sqlite3_mu
43220 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 33 tex_held(sqlite3
43230 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 _mutex*);.int sq
43240 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 lite3_mutex_noth
43250 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 eld(sqlite3_mute
43260 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 x*);../*.** CAPI
43270 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70 65 3REF: Mutex Type
43280 73 20 7b 46 31 37 30 30 31 7d 0a 2a 2a 0a 2a 2a s {F17001}.**.**
43290 20 7b 46 31 37 30 30 32 7d 20 54 68 65 20 5b 73 {F17002} The [s
432a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
432b0 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 oc()] interface
432c0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
432d0 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68 rgument.** which
432e0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 is one of these
432f0 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
43300 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ts..*/.#define S
43310 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 QLITE_MUTEX_FAST
43320 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 0.#
43330 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
43340 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 20 20 TEX_RECURSIVE
43350 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
43360 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
43370 49 43 5f 4d 41 53 54 45 52 20 20 20 20 32 0a 23 IC_MASTER 2.#
43380 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
43390 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20 TEX_STATIC_MEM
433a0 20 20 20 20 20 33 20 20 2f 2a 20 73 71 6c 69 74 3 /* sqlit
433b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 e3_malloc() */.#
433c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
433d0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20 TEX_STATIC_MEM2
433e0 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 4 /* sqlit
433f0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 e3_release_memor
43400 79 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 y() */.#define S
43410 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
43420 49 43 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 IC_PRNG 5
43430 2f 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f /* sqlite3_rando
43440 6d 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 m() */.#define S
43450 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
43460 49 43 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 IC_LRU 6
43470 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 /* lru page list
43480 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
43490 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
434a0 4c 52 55 32 20 20 20 20 20 20 37 20 20 2f 2a 20 LRU2 7 /*
434b0 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f lru page list */
434c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
434d0 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e 74 : Low-Level Cont
434e0 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73 65 20 rol Of Database
434f0 46 69 6c 65 73 20 7b 46 31 31 33 30 30 7d 0a 2a Files {F11300}.*
43500 2a 0a 2a 2a 20 7b 46 31 31 33 30 31 7d 20 54 68 *.** {F11301} Th
43510 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f e [sqlite3_file_
43520 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 control()] inter
43530 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64 69 72 face makes a dir
43540 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a ect call to the.
43550 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 ** xFileControl
43560 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65 20 5b method for the [
43570 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
43580 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 ds] object assoc
43590 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 iated.** with a
435a0 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 particular datab
435b0 61 73 65 20 69 64 65 6e 74 69 66 69 65 64 20 62 ase identified b
435c0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 y the second arg
435d0 75 6d 65 6e 74 2e 20 7b 46 31 31 33 30 32 7d 20 ument. {F11302}
435e0 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 The.** name of t
435f0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 74 he database is t
43600 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 he name assigned
43610 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 to the database
43620 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 by the.** <a hr
43630 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61 63 68 2e ef="lang_attach.
43640 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c 2f 61 3e html">ATTACH</a>
43650 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 68 61 SQL command tha
43660 74 20 6f 70 65 6e 65 64 20 74 68 65 0a 2a 2a 20 t opened the.**
43670 64 61 74 61 62 61 73 65 2e 20 7b 46 31 31 33 30 database. {F1130
43680 33 7d 20 54 6f 20 63 6f 6e 74 72 6f 6c 20 74 68 3} To control th
43690 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 e main database
436a0 66 69 6c 65 2c 20 75 73 65 20 74 68 65 20 6e 61 file, use the na
436b0 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a 20 6f 72 20 me "main".** or
436c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 a NULL pointer.
436d0 7b 46 31 31 33 30 34 7d 20 54 68 65 20 74 68 69 {F11304} The thi
436e0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 rd and fourth pa
436f0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 rameters to this
43700 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 72 65 20 routine.** are
43710 70 61 73 73 65 64 20 64 69 72 65 63 74 6c 79 20 passed directly
43720 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 73 through to the s
43730 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 econd and third
43740 70 61 72 61 6d 65 74 65 72 73 20 6f 66 0a 2a 2a parameters of.**
43750 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f the xFileContro
43760 6c 20 6d 65 74 68 6f 64 2e 20 20 7b 46 31 31 33 l method. {F113
43770 30 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 05} The return v
43780 61 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69 6c alue of the xFil
43790 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 68 eControl.** meth
437a0 6f 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 72 od becomes the r
437b0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
437c0 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a his routine..**.
437d0 2a 2a 20 7b 46 31 31 33 30 36 7d 20 49 66 20 74 ** {F11306} If t
437e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
437f0 74 65 72 20 28 7a 44 62 4e 61 6d 65 29 20 64 6f ter (zDbName) do
43800 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 74 68 65 es not match the
43810 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 name of any.**
43820 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 66 69 open database fi
43830 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f le, then SQLITE_
43840 45 52 52 4f 52 20 69 73 20 72 65 74 75 72 6e 65 ERROR is returne
43850 64 2e 20 7b 46 31 31 33 30 37 7d 20 54 68 69 73 d. {F11307} This
43860 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 error.** code i
43870 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72 65 64 s not remembered
43880 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65 and will not be
43890 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b 73 71 recalled by [sq
438a0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
438b0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
438c0 65 72 72 6d 73 67 28 29 5d 2e 20 7b 41 31 31 33 errmsg()]. {A113
438d0 30 38 7d 20 54 68 65 20 75 6e 64 65 72 6c 79 69 08} The underlyi
438e0 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 ng xFileControl
438f0 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a 2a 2a 20 method might.**
43900 61 6c 73 6f 20 72 65 74 75 72 6e 20 53 51 4c 49 also return SQLI
43910 54 45 5f 45 52 52 4f 52 2e 20 20 7b 41 31 31 33 TE_ERROR. {A113
43920 30 39 7d 20 54 68 65 72 65 20 69 73 20 6e 6f 20 09} There is no
43930 77 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75 69 way to distingui
43940 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61 6e sh between.** an
43950 20 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e 61 incorrect zDbNa
43960 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54 45 me and an SQLITE
43970 5f 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66 72 _ERROR return fr
43980 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e om the underlyin
43990 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f g.** xFileContro
439a0 6c 20 6d 65 74 68 6f 64 2e 20 7b 45 4e 44 7d 0a l method. {END}.
439b0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
439c0 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f [SQLITE_FCNTL_LO
439d0 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69 6e 74 20 CKSTATE].*/.int
439e0 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
439f0 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a 2c 20 63 trol(sqlite3*, c
43a00 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 onst char *zDbNa
43a10 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 me, int op, void
43a20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
43a30 52 45 46 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 REF: Testing Int
43a40 65 72 66 61 63 65 20 7b 46 31 31 34 30 30 7d 0a erface {F11400}.
43a50 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
43a60 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 3_test_control()
43a70 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 interface is us
43a80 65 64 20 74 6f 20 72 65 61 64 20 6f 75 74 20 69 ed to read out i
43a90 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 61 74 65 nternal.** state
43aa0 20 6f 66 20 53 51 4c 69 74 65 20 61 6e 64 20 74 of SQLite and t
43ab0 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c 74 73 20 o inject faults
43ac0 69 6e 74 6f 20 53 51 4c 69 74 65 20 66 6f 72 20 into SQLite for
43ad0 74 65 73 74 69 6e 67 0a 2a 2a 20 70 75 72 70 6f testing.** purpo
43ae0 73 65 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 ses. The first
43af0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 parameter is an
43b00 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 74 operation code t
43b10 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a hat determines.*
43b20 2a 20 74 68 65 20 6e 75 6d 62 65 72 2c 20 6d 65 * the number, me
43b30 61 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 65 72 61 aning, and opera
43b40 74 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 75 62 73 tion of all subs
43b50 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 equent parameter
43b60 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e s..**.** This in
43b70 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 66 terface is not f
43b80 6f 72 20 75 73 65 20 62 79 20 61 70 70 6c 69 63 or use by applic
43b90 61 74 69 6f 6e 73 2e 20 20 49 74 20 65 78 69 73 ations. It exis
43ba0 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 ts solely.** for
43bb0 20 76 65 72 69 66 79 69 6e 67 20 74 68 65 20 63 verifying the c
43bc0 6f 72 72 65 63 74 20 6f 70 65 72 61 74 69 6f 6e orrect operation
43bd0 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c of the SQLite l
43be0 69 62 72 61 72 79 2e 20 20 44 65 70 65 6e 64 69 ibrary. Dependi
43bf0 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 74 68 65 ng.** on how the
43c00 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 SQLite library
43c10 69 73 20 63 6f 6d 70 69 6c 65 64 2c 20 74 68 69 is compiled, thi
43c20 73 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 s interface migh
43c30 74 20 6e 6f 74 20 65 78 69 73 74 2e 0a 2a 2a 0a t not exist..**.
43c40 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f ** The details o
43c50 66 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 f the operation
43c60 63 6f 64 65 73 2c 20 74 68 65 69 72 20 6d 65 61 codes, their mea
43c70 6e 69 6e 67 73 2c 20 74 68 65 20 70 61 72 61 6d nings, the param
43c80 65 74 65 72 73 0a 2a 2a 20 74 68 65 79 20 74 61 eters.** they ta
43c90 6b 65 2c 20 61 6e 64 20 77 68 61 74 20 74 68 65 ke, and what the
43ca0 79 20 64 6f 20 61 72 65 20 61 6c 6c 20 73 75 62 y do are all sub
43cb0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 ject to change w
43cc0 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 0a 2a ithout notice..*
43cd0 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 * Unlike most of
43ce0 20 74 68 65 20 53 51 4c 69 74 65 20 41 50 49 2c the SQLite API,
43cf0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 this function i
43d00 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 s not guaranteed
43d10 20 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 65 20 63 to.** operate c
43d20 6f 6e 73 69 73 74 65 6e 74 6c 79 20 66 72 6f 6d onsistently from
43d30 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 one release to
43d40 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 69 6e 74 the next..*/.int
43d50 20 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f sqlite3_test_co
43d60 6e 74 72 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e ntrol(int op, ..
43d70 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
43d80 52 45 46 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 REF: Testing Int
43d90 65 72 66 61 63 65 20 4f 70 65 72 61 74 69 6f 6e erface Operation
43da0 20 43 6f 64 65 73 20 7b 46 31 31 34 31 30 7d 0a Codes {F11410}.
43db0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
43dc0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 76 61 tants are the va
43dd0 6c 69 64 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f lid operation co
43de0 64 65 20 70 61 72 61 6d 65 74 65 72 73 20 75 73 de parameters us
43df0 65 64 0a 2a 2a 20 61 73 20 74 68 65 20 66 69 72 ed.** as the fir
43e00 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b st argument to [
43e10 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e sqlite3_test_con
43e20 74 72 6f 6c 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 trol()]..**.** T
43e30 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 hese parameters
43e40 61 6e 64 20 74 68 65 69 72 20 6d 65 61 6e 69 6e and their meanin
43e50 67 73 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 gs are subject t
43e60 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 77 69 74 68 o change.** with
43e70 6f 75 74 20 6e 6f 74 69 63 65 2e 20 20 54 68 65 out notice. The
43e80 73 65 20 76 61 6c 75 65 73 20 61 72 65 20 66 6f se values are fo
43e90 72 20 74 65 73 74 69 6e 67 20 70 75 72 70 6f 73 r testing purpos
43ea0 65 73 20 6f 6e 6c 79 2e 0a 2a 2a 20 41 70 70 6c es only..** Appl
43eb0 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ications should
43ec0 6e 6f 74 20 75 73 65 20 61 6e 79 20 6f 66 20 74 not use any of t
43ed0 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 hese parameters
43ee0 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 or the.** [sqlit
43ef0 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 e3_test_control(
43f00 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f )] interface..*/
43f10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
43f20 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 53 41 TESTCTRL_PRNG_SA
43f30 56 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 VE
43f40 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 5.#define SQLI
43f50 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 TE_TESTCTRL_PRNG
43f60 5f 52 45 53 54 4f 52 45 20 20 20 20 20 20 20 20 _RESTORE
43f70 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 6.#define S
43f80 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 QLITE_TESTCTRL_P
43f90 52 4e 47 5f 52 45 53 45 54 20 20 20 20 20 20 20 RNG_RESET
43fa0 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 7.#defin
43fb0 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 e SQLITE_TESTCTR
43fc0 4c 5f 42 49 54 56 45 43 5f 54 45 53 54 20 20 20 L_BITVEC_TEST
43fd0 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 8.#de
43fe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 fine SQLITE_TEST
43ff0 43 54 52 4c 5f 46 41 55 4c 54 5f 49 4e 53 54 41 CTRL_FAULT_INSTA
44000 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 39 0a LL 9.
44010 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
44020 45 53 54 43 54 52 4c 5f 42 45 4e 49 47 4e 5f 4d ESTCTRL_BENIGN_M
44030 41 4c 4c 4f 43 5f 48 4f 4f 4b 53 20 20 20 20 20 ALLOC_HOOKS
44040 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 10../*.** CAPI3R
44050 45 46 3a 20 53 51 4c 69 74 65 20 52 75 6e 74 69 EF: SQLite Runti
44060 6d 65 20 53 74 61 74 75 73 20 7b 46 31 37 32 30 me Status {F1720
44070 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 0}.**.** This in
44080 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
44090 74 6f 20 72 65 74 72 69 65 76 65 20 72 75 6e 74 to retrieve runt
440a0 69 6d 65 20 73 74 61 74 75 73 20 69 6e 66 6f 72 ime status infor
440b0 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 mation.** about
440c0 74 68 65 20 70 72 65 66 6f 72 6d 61 6e 63 65 20 the preformance
440d0 6f 66 20 53 51 4c 69 74 65 2c 20 61 6e 64 20 6f of SQLite, and o
440e0 70 74 69 6f 6e 61 6c 6c 79 20 74 6f 20 72 65 73 ptionally to res
440f0 65 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 68 69 et various.** hi
44100 67 68 77 61 74 65 72 20 6d 61 72 6b 73 2e 20 20 ghwater marks.
44110 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
44120 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 nt is an integer
44130 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 code for.** the
44140 20 73 70 65 63 69 66 69 63 20 70 61 72 61 6d 65 specific parame
44150 74 65 72 20 74 6f 20 6d 65 61 73 75 72 65 2e 20 ter to measure.
44160 20 52 65 63 6f 67 6e 69 7a 65 64 20 69 6e 74 65 Recognized inte
44170 67 65 72 20 63 6f 64 65 73 0a 2a 2a 20 61 72 65 ger codes.** are
44180 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 5b 53 51 of the form [SQ
44190 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f LITE_STATUS_MEMO
441a0 52 59 5f 55 53 45 44 20 7c 20 53 51 4c 49 54 45 RY_USED | SQLITE
441b0 5f 53 54 41 54 55 53 5f 2e 2e 2e 5d 2e 0a 2a 2a _STATUS_...]..**
441c0 20 54 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c The current val
441d0 75 65 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 ue of the parame
441e0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 ter is returned
441f0 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e 0a into *pCurrent..
44200 2a 2a 20 54 68 65 20 68 69 67 68 65 73 74 20 72 ** The highest r
44210 65 63 6f 72 64 65 64 20 76 61 6c 75 65 20 69 73 ecorded value is
44220 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 48 returned in *pH
44230 69 67 68 77 61 74 65 72 2e 20 20 49 66 20 74 68 ighwater. If th
44240 65 0a 2a 2a 20 72 65 73 65 74 46 6c 61 67 20 69 e.** resetFlag i
44250 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 s true, then the
44260 20 68 69 67 68 65 73 74 20 72 65 63 6f 72 64 20 highest record
44270 76 61 6c 75 65 20 69 73 20 72 65 73 65 74 20 61 value is reset a
44280 66 74 65 72 0a 2a 2a 20 2a 70 48 69 67 68 77 61 fter.** *pHighwa
44290 74 65 72 20 69 73 20 77 72 69 74 74 65 6e 2e 20 ter is written.
442a0 53 6f 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 Some parameters
442b0 64 6f 20 6e 6f 74 20 72 65 63 6f 72 64 20 74 68 do not record th
442c0 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 76 61 6c e highest.** val
442d0 75 65 2e 20 20 46 6f 72 20 74 68 6f 73 65 20 70 ue. For those p
442e0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6e 6f 74 arameters.** not
442f0 68 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 20 hing is written
44300 69 6e 74 6f 20 2a 70 48 69 67 68 77 61 74 65 72 into *pHighwater
44310 20 61 6e 64 20 74 68 65 20 72 65 73 65 74 46 6c and the resetFl
44320 61 67 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a ag is ignored..*
44330 2a 20 4f 74 68 65 72 20 70 61 72 61 6d 65 74 65 * Other paramete
44340 72 73 20 72 65 63 6f 72 64 20 6f 6e 6c 79 20 74 rs record only t
44350 68 65 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 he highwater mar
44360 6b 20 61 6e 64 20 6e 6f 74 20 74 68 65 20 63 75 k and not the cu
44370 72 72 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 rrent.** value.
44380 20 46 6f 72 20 74 68 65 73 65 20 6c 61 74 74 65 For these latte
44390 72 20 70 61 72 61 6d 65 74 65 72 73 20 6e 6f 74 r parameters not
443a0 68 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 20 hing is written
443b0 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e 0a into *pCurrent..
443c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
443d0 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 ne returns SQLIT
443e0 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 20 E_OK on success
443f0 61 6e 64 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a and a non-zero.*
44400 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f * [error code] o
44410 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a n failure..**.**
44420 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 This routine is
44430 20 74 68 72 65 61 64 73 61 66 65 20 62 75 74 20 threadsafe but
44440 69 73 20 6e 6f 74 20 61 74 6f 6d 69 63 2e 20 20 is not atomic.
44450 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e This routine can
44460 0a 2a 2a 20 63 61 6c 6c 65 64 20 77 68 69 6c 65 .** called while
44470 20 6f 74 68 65 72 20 74 68 72 65 61 64 73 20 61 other threads a
44480 72 65 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 73 re running the s
44490 61 6d 65 20 6f 72 20 64 69 66 66 65 72 65 6e 74 ame or different
444a0 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 SQLite.** inter
444b0 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 20 faces. However
444c0 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 the values retur
444d0 6e 65 64 20 69 6e 20 2a 70 43 75 72 72 65 6e 74 ned in *pCurrent
444e0 20 61 6e 64 0a 2a 2a 20 2a 70 48 69 67 68 77 61 and.** *pHighwa
444f0 74 65 72 20 72 65 66 6c 65 63 74 20 74 68 65 20 ter reflect the
44500 73 74 61 74 75 73 20 6f 66 20 53 51 4c 69 74 65 status of SQLite
44510 20 61 74 20 64 69 66 66 65 72 65 6e 74 20 70 6f at different po
44520 69 6e 74 73 20 69 6e 20 74 69 6d 65 0a 2a 2a 20 ints in time.**
44530 61 6e 64 20 69 74 20 69 73 20 70 6f 73 73 69 62 and it is possib
44540 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 le that another
44550 74 68 72 65 61 64 20 6d 69 67 68 74 20 63 68 61 thread might cha
44560 6e 67 65 20 74 68 65 20 70 61 72 61 6d 65 74 65 nge the paramete
44570 72 0a 2a 2a 20 69 6e 20 62 65 74 77 65 65 6e 20 r.** in between
44580 74 68 65 20 74 69 6d 65 73 20 77 68 65 6e 20 2a the times when *
44590 70 43 75 72 72 65 6e 74 20 61 6e 64 20 2a 70 48 pCurrent and *pH
445a0 69 67 68 77 61 74 65 72 20 61 72 65 20 77 72 69 ighwater are wri
445b0 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 tten..**.** This
445c0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 interface is ex
445d0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 perimental and i
445e0 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 s subject to cha
445f0 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 nge or.** remova
44600 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 l in future rele
44610 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
44620 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 */.int sqlite3_s
44630 74 61 74 75 73 28 69 6e 74 20 6f 70 2c 20 69 6e tatus(int op, in
44640 74 20 2a 70 43 75 72 72 65 6e 74 2c 20 69 6e 74 t *pCurrent, int
44650 20 2a 70 48 69 67 68 77 61 74 65 72 2c 20 69 6e *pHighwater, in
44660 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f t resetFlag);../
44670 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
44680 74 61 74 75 73 20 50 61 72 61 6d 65 74 65 72 73 tatus Parameters
44690 20 7b 46 31 37 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 {F17250}.**.**
446a0 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f These integer co
446b0 6e 73 74 61 6e 74 73 20 64 65 73 69 67 6e 61 74 nstants designat
446c0 65 20 76 61 72 69 6f 75 73 20 72 75 6e 2d 74 69 e various run-ti
446d0 6d 65 20 73 74 61 74 75 73 20 70 61 72 61 6d 65 me status parame
446e0 74 65 72 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e ters.** that can
446f0 20 62 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 be returned by
44700 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 [sqlite3_status(
44710 29 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a )]..**.** <dl>.*
44720 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 * <dt>SQLITE_STA
44730 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 3c TUS_MEMORY_USED<
44740 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
44750 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
44760 65 20 63 75 72 72 65 6e 74 20 61 6d 6f 75 6e 74 e current amount
44770 20 6f 66 20 6d 65 6d 6f 72 79 20 63 68 65 63 6b of memory check
44780 65 64 20 6f 75 74 0a 2a 2a 20 75 73 69 6e 67 20 ed out.** using
44790 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
447a0 29 5d 2c 20 65 69 74 68 65 72 20 64 69 72 65 63 )], either direc
447b0 74 6c 79 20 6f 72 20 69 6e 64 69 72 65 63 74 6c tly or indirectl
447c0 79 2e 20 20 54 68 65 0a 2a 2a 20 66 69 67 75 72 y. The.** figur
447d0 65 20 69 6e 63 6c 75 64 65 73 20 63 61 6c 6c 73 e includes calls
447e0 20 6d 61 64 65 20 74 6f 20 5b 73 71 6c 69 74 65 made to [sqlite
447f0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 79 20 74 3_malloc()] by t
44800 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a he application.*
44810 2a 20 61 6e 64 20 69 6e 74 65 72 6e 61 6c 20 6d * and internal m
44820 65 6d 6f 72 79 20 75 73 61 67 65 20 62 79 20 74 emory usage by t
44830 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
44840 79 2e 20 20 53 63 72 61 74 63 68 20 6d 65 6d 6f y. Scratch memo
44850 72 79 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 6c 65 64 ry.** controlled
44860 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 by [SQLITE_CONF
44870 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 IG_SCRATCH] and
44880 61 75 78 69 6c 69 61 72 79 20 70 61 67 65 2d 63 auxiliary page-c
44890 61 63 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 63 ache.** memory c
448a0 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51 ontrolled by [SQ
448b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
448c0 43 41 43 48 45 5d 20 69 73 20 6e 6f 74 20 69 6e CACHE] is not in
448d0 63 6c 75 64 65 64 20 69 6e 0a 2a 2a 20 74 68 69 cluded in.** thi
448e0 73 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 s parameter. Th
448f0 65 20 61 6d 6f 75 6e 74 20 72 65 74 75 72 6e 65 e amount returne
44900 64 20 69 73 20 74 68 65 20 73 75 6d 20 6f 66 20 d is the sum of
44910 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a the allocation.*
44920 2a 20 73 69 7a 65 73 20 61 73 20 72 65 70 6f 72 * sizes as repor
44930 74 65 64 20 62 79 20 74 68 65 20 78 53 69 7a 65 ted by the xSize
44940 20 6d 65 74 68 6f 64 20 69 6e 20 5b 73 71 6c 69 method in [sqli
44950 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
44960 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
44970 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 >SQLITE_STATUS_P
44980 41 47 45 43 41 43 48 45 5f 55 53 45 44 3c 2f 64 AGECACHE_USED</d
44990 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 t>.** <dd>This p
449a0 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e 73 arameter returns
449b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 the number of p
449c0 61 67 65 73 20 75 73 65 64 20 6f 75 74 20 6f 66 ages used out of
449d0 20 74 68 65 0a 2a 2a 20 70 61 67 65 20 63 61 63 the.** page cac
449e0 68 65 20 62 75 66 66 65 72 20 63 6f 6e 66 69 67 he buffer config
449f0 75 72 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 ured using [SQLI
44a00 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
44a10 43 48 45 5d 2e 20 20 54 68 65 0a 2a 2a 20 76 61 CHE]. The.** va
44a20 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 lue returned is
44a30 69 6e 20 70 61 67 65 73 2c 20 6e 6f 74 20 69 6e in pages, not in
44a40 20 62 79 74 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a bytes.</dd>.**.
44a50 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 ** <dt>SQLITE_ST
44a60 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 4f ATUS_PAGECACHE_O
44a70 56 45 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 VERFLOW</dt>.**
44a80 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 <dd>This paramet
44a90 65 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e er returns the n
44aa0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f umber of bytes o
44ab0 66 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 f page cache.**
44ac0 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 68 69 63 68 allocation which
44ad0 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 73 74 could not be st
44ae0 61 74 69 73 66 69 65 64 20 62 79 20 74 68 65 20 atisfied by the
44af0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
44b00 41 47 45 43 41 43 48 45 5d 0a 2a 2a 20 62 75 66 AGECACHE].** buf
44b10 66 65 72 20 61 6e 64 20 77 68 65 72 65 20 66 6f fer and where fo
44b20 72 63 65 64 20 74 6f 20 6f 76 65 72 66 6c 6f 77 rced to overflow
44b30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c to [sqlite3_mal
44b40 6c 6f 63 28 29 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a loc()].</dd>.**.
44b50 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 ** <dt>SQLITE_ST
44b60 41 54 55 53 5f 53 43 52 41 54 43 48 5f 55 53 45 ATUS_SCRATCH_USE
44b70 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
44b80 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 is parameter ret
44b90 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
44ba0 6f 66 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 75 of allocations u
44bb0 73 65 64 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a sed out of the.*
44bc0 2a 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 * scratch alloca
44bd0 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 20 62 tion lookaside b
44be0 75 66 66 65 72 20 63 6f 6e 66 69 67 75 72 65 64 uffer configured
44bf0 20 75 73 69 6e 67 0a 2a 2a 20 5b 53 51 4c 49 54 using.** [SQLIT
44c00 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
44c10 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 ]. The value re
44c20 74 75 72 6e 65 64 20 69 73 20 69 6e 20 61 6c 6c turned is in all
44c30 6f 63 61 74 69 6f 6e 73 2c 20 6e 6f 74 0a 2a 2a ocations, not.**
44c40 20 69 6e 20 62 79 74 65 73 2e 20 20 53 69 6e 63 in bytes. Sinc
44c50 65 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 e a single threa
44c60 64 20 6d 61 79 20 6f 6e 6c 79 20 68 61 76 65 20 d may only have
44c70 6f 6e 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a one allocation.*
44c80 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 61 74 * outstanding at
44c90 20 74 69 6d 65 2c 20 74 68 69 73 20 70 61 72 61 time, this para
44ca0 6d 65 74 65 72 20 61 6c 73 6f 20 72 65 70 6f 72 meter also repor
44cb0 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ts the number of
44cc0 20 74 68 72 65 61 64 73 0a 2a 2a 20 75 73 69 6e threads.** usin
44cd0 67 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 g scratch memory
44ce0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
44cf0 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 e.</dd>.**.** <d
44d00 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f t>SQLITE_STATUS_
44d10 53 43 52 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57 SCRATCH_OVERFLOW
44d20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
44d30 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 s parameter retu
44d40 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
44d50 66 20 62 79 74 65 73 20 6f 66 20 73 63 72 61 74 f bytes of scrat
44d60 63 68 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c ch memory.** all
44d70 6f 63 61 74 69 6f 6e 20 77 68 69 63 68 20 63 6f ocation which co
44d80 75 6c 64 20 6e 6f 74 20 62 65 20 73 74 61 74 69 uld not be stati
44d90 73 66 69 65 64 20 62 79 20 74 68 65 20 5b 53 51 sfied by the [SQ
44da0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
44db0 54 43 48 5d 0a 2a 2a 20 62 75 66 66 65 72 20 61 TCH].** buffer a
44dc0 6e 64 20 77 68 65 72 65 20 66 6f 72 63 65 64 20 nd where forced
44dd0 74 6f 20 6f 76 65 72 66 6c 6f 77 20 74 6f 20 5b to overflow to [
44de0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
44df0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 ].</dd>.**.** <d
44e00 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f t>SQLITE_STATUS_
44e10 4d 41 4c 4c 4f 43 5f 53 49 5a 45 3c 2f 64 74 3e MALLOC_SIZE</dt>
44e20 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 .** <dd>This par
44e30 61 6d 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 ameter records t
44e40 68 65 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 he largest memor
44e50 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 y allocation req
44e60 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 uest.** handed t
44e70 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f o [sqlite3_mallo
44e80 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 c()] or [sqlite3
44e90 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 28 6f 72 20 _realloc()] (or
44ea0 74 68 65 69 72 0a 2a 2a 20 69 6e 74 65 72 6e 61 their.** interna
44eb0 6c 20 65 71 75 69 76 61 6c 65 6e 74 73 29 2e 20 l equivalents).
44ec0 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 69 6e The value of in
44ed0 74 65 72 65 73 74 20 69 73 20 72 65 74 75 72 6e terest is return
44ee0 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67 in the.** *pHig
44ef0 68 77 61 74 65 72 20 70 61 72 61 6d 65 74 65 72 hwater parameter
44f00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 to [sqlite3_sta
44f10 74 75 73 28 29 5d 2e 20 20 54 68 65 20 76 61 6c tus()]. The val
44f20 75 65 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e ue written.** in
44f30 74 6f 20 74 68 65 20 2a 70 43 75 72 72 65 6e 74 to the *pCurrent
44f40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 6e parameter is un
44f50 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a defined.</dd>.**
44f60 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 4e 65 77 </dl>.**.** New
44f70 20 73 74 61 74 75 73 20 70 61 72 61 6d 65 74 65 status paramete
44f80 72 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 rs may be added
44f90 66 72 6f 6d 20 74 69 6d 65 20 74 6f 20 74 69 6d from time to tim
44fa0 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e..*/.#define SQ
44fb0 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f LITE_STATUS_MEMO
44fc0 52 59 5f 55 53 45 44 20 20 20 20 20 20 20 20 20 RY_USED
44fd0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
44fe0 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 43 E_STATUS_PAGECAC
44ff0 48 45 5f 55 53 45 44 20 20 20 20 20 20 20 31 0a HE_USED 1.
45000 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
45010 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f TATUS_PAGECACHE_
45020 4f 56 45 52 46 4c 4f 57 20 20 20 32 0a 23 64 65 OVERFLOW 2.#de
45030 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 fine SQLITE_STAT
45040 55 53 5f 53 43 52 41 54 43 48 5f 55 53 45 44 20 US_SCRATCH_USED
45050 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 3.#defin
45060 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f e SQLITE_STATUS_
45070 53 43 52 41 54 43 48 5f 4f 56 45 52 46 4c 4f 57 SCRATCH_OVERFLOW
45080 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 4.#define S
45090 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c QLITE_STATUS_MAL
450a0 4c 4f 43 5f 53 49 5a 45 20 20 20 20 20 20 20 20 LOC_SIZE
450b0 20 20 35 0a 0a 0a 2f 2a 0a 2a 2a 20 55 6e 64 6f 5.../*.** Undo
450c0 20 74 68 65 20 68 61 63 6b 20 74 68 61 74 20 63 the hack that c
450d0 6f 6e 76 65 72 74 73 20 66 6c 6f 61 74 69 6e 67 onverts floating
450e0 20 70 6f 69 6e 74 20 74 79 70 65 73 20 74 6f 20 point types to
450f0 69 6e 74 65 67 65 72 20 66 6f 72 0a 2a 2a 20 62 integer for.** b
45100 75 69 6c 64 73 20 6f 6e 20 70 72 6f 63 65 73 73 uilds on process
45110 6f 72 73 20 77 69 74 68 6f 75 74 20 66 6c 6f 61 ors without floa
45120 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f ting point suppo
45130 72 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 rt..*/.#ifdef SQ
45140 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 LITE_OMIT_FLOATI
45150 4e 47 5f 50 4f 49 4e 54 0a 23 20 75 6e 64 65 66 NG_POINT.# undef
45160 20 64 6f 75 62 6c 65 0a 23 65 6e 64 69 66 0a 0a double.#endif..
45170 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c #ifdef __cpluspl
45180 75 73 0a 7d 20 20 2f 2a 20 45 6e 64 20 6f 66 20 us.} /* End of
45190 74 68 65 20 27 65 78 74 65 72 6e 20 22 43 22 27 the 'extern "C"'
451a0 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65 6e 64 69 66 block */.#endif
451b0 0a 23 65 6e 64 69 66 0a .#endif.