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 38 34 20 32 30 30 38 2f 30 n,v 1.384 2008/0
05f0: 37 2f 33 31 20 31 37 3a 31 36 3a 30 35 20 64 72 7/31 17:16:05 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 48 31 30 30 31 30 7d 20 umbers {H10010}
0840: 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S60100>.**.** T
0850: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f he SQLITE_VERSIO
0860: 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f 56 45 52 N and SQLITE_VER
0870: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65 66 SION_NUMBER #def
0880: 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68 65 20 73 ines in.** the s
0890: 71 6c 69 74 65 33 2e 68 20 66 69 6c 65 20 73 70 qlite3.h file sp
08a0: 65 63 69 66 79 20 74 68 65 20 76 65 72 73 69 6f ecify the versio
08b0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 77 69 74 68 n of SQLite with
08c0: 20 77 68 69 63 68 0a 2a 2a 20 74 68 61 74 20 68 which.** that h
08d0: 65 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73 eader file is as
08e0: 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 sociated..**.**
08f0: 54 68 65 20 22 76 65 72 73 69 6f 6e 22 20 6f 66 The "version" of
0900: 20 53 51 4c 69 74 65 20 69 73 20 61 20 73 74 72 SQLite is a str
0910: 69 6e 67 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 ing of the form
0920: 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54 68 65 20 "X.Y.Z"..** The
0930: 70 68 72 61 73 65 20 22 61 6c 70 68 61 22 20 6f phrase "alpha" o
0940: 72 20 22 62 65 74 61 22 20 6d 69 67 68 74 20 62 r "beta" might b
0950: 65 20 61 70 70 65 6e 64 65 64 20 61 66 74 65 72 e appended after
0960: 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68 65 20 58 the Z..** The X
0970: 20 76 61 6c 75 65 20 69 73 20 6d 61 6a 6f 72 20 value is major
0980: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 version number a
0990: 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69 74 lways 3 in SQLit
09a0: 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c e3..** The X val
09b0: 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 ue only changes
09c0: 77 68 65 6e 20 62 61 63 6b 77 61 72 64 73 20 63 when backwards c
09d0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73 0a ompatibility is.
09e0: 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 65 ** broken and we
09f0: 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 72 intend to never
0a00: 20 62 72 65 61 6b 20 62 61 63 6b 77 61 72 64 73 break backwards
0a10: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a compatibility..
0a20: 2a 2a 20 54 68 65 20 59 20 76 61 6c 75 65 20 69 ** The Y value i
0a30: 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 s the minor vers
0a40: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 6f ion number and o
0a50: 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e nly changes when
0a60: 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 20 6d 61 .** there are ma
0a70: 6a 6f 72 20 66 65 61 74 75 72 65 20 65 6e 68 61 jor feature enha
0a80: 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 ncements that ar
0a90: 65 20 66 6f 72 77 61 72 64 73 20 63 6f 6d 70 61 e forwards compa
0aa0: 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f 74 tible.** but not
0ab0: 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
0ac0: 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 5a 20 tible..** The Z
0ad0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 72 65 6c value is the rel
0ae0: 65 61 73 65 20 6e 75 6d 62 65 72 20 61 6e 64 20 ease number and
0af0: 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 77 is incremented w
0b00: 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c 65 ith.** each rele
0b10: 61 73 65 20 62 75 74 20 72 65 73 65 74 73 20 62 ase but resets b
0b20: 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 65 76 65 ack to 0 wheneve
0b30: 72 20 59 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 r Y is increment
0b40: 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ed..**.** See al
0b50: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 so: [sqlite3_lib
0b60: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b version()] and [
0b70: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
0b80: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e 0a 2a 2a on_number()]..**
0b90: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
0ba0: 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 31 7d 20 54 **.** {H10011} T
0bb0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f he SQLITE_VERSIO
0bc0: 4e 20 23 64 65 66 69 6e 65 20 69 6e 20 74 68 65 N #define in the
0bd0: 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 sqlite3.h heade
0be0: 72 20 66 69 6c 65 20 73 68 61 6c 6c 0a 2a 2a 20 r file shall.**
0bf0: 20 20 20 20 20 20 20 20 20 65 76 61 6c 75 61 74 evaluat
0c00: 65 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 e to a string li
0c10: 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 teral that is th
0c20: 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e e SQLite version
0c30: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 .** wit
0c40: 68 20 77 68 69 63 68 20 74 68 65 20 68 65 61 64 h which the head
0c50: 65 72 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63 er file is assoc
0c60: 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 iated..**.** {H1
0c70: 30 30 31 34 7d 20 54 68 65 20 53 51 4c 49 54 45 0014} The SQLITE
0c80: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 _VERSION_NUMBER
0c90: 23 64 65 66 69 6e 65 20 73 68 61 6c 6c 20 72 65 #define shall re
0ca0: 73 6f 6c 76 65 20 74 6f 20 61 6e 20 69 6e 74 65 solve to an inte
0cb0: 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ger.**
0cc0: 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 with the value (
0cd0: 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 X*1000000 + Y*10
0ce0: 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 00 + Z) where X,
0cf0: 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20 20 20 20 Y, and Z.**
0d00: 20 20 20 20 20 20 61 72 65 20 74 68 65 20 6d 61 are the ma
0d10: 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20 6d 69 6e jor version, min
0d20: 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61 6e 64 20 or version, and
0d30: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 0a release number..
0d40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
0d50: 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20 E_VERSION
0d60: 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 "--VERS--".#de
0d70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 fine SQLITE_VERS
0d80: 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 2d 2d 56 45 ION_NUMBER --VE
0d90: 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 0a RSION-NUMBER--..
0da0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
0db0: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 Run-Time Library
0dc0: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 Version Numbers
0dd0: 20 7b 48 31 30 30 32 30 7d 20 3c 53 36 30 31 30 {H10020} <S6010
0de0: 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 0>.** KEYWORDS:
0df0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a sqlite3_version.
0e00: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 65 61 74 **.** These feat
0e10: 75 72 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 ures provide the
0e20: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f same informatio
0e30: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 n as the [SQLITE
0e40: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 _VERSION].** and
0e50: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
0e60: 5f 4e 55 4d 42 45 52 5d 20 23 64 65 66 69 6e 65 _NUMBER] #define
0e70: 73 20 69 6e 20 74 68 65 20 68 65 61 64 65 72 2c s in the header,
0e80: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 but are associa
0e90: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ted.** with the
0ea0: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 library instead
0eb0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69 of the header fi
0ec0: 6c 65 2e 20 20 43 61 75 74 69 6f 75 73 20 70 72 le. Cautious pr
0ed0: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 0a ogrammers might.
0ee0: 2a 2a 20 69 6e 63 6c 75 64 65 20 61 20 63 68 65 ** include a che
0ef0: 63 6b 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c ck in their appl
0f00: 69 63 61 74 69 6f 6e 20 74 6f 20 76 65 72 69 66 ication to verif
0f10: 79 20 74 68 61 74 0a 2a 2a 20 73 71 6c 69 74 65 y that.** sqlite
0f20: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 3_libversion_num
0f30: 62 65 72 28 29 20 61 6c 77 61 79 73 20 72 65 74 ber() always ret
0f40: 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 0a 2a urns the value.*
0f50: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f * [SQLITE_VERSIO
0f60: 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a N_NUMBER]..**.**
0f70: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 The sqlite3_lib
0f80: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 version() functi
0f90: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 on returns the s
0fa0: 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 ame information
0fb0: 61 73 20 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20 as is.** in the
0fc0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b sqlite3_version[
0fd0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e ] string constan
0fe0: 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e t. The function
0ff0: 20 69 73 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 is provided.**
1000: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 for use in DLLs
1010: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 since DLL users
1020: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 usually do not h
1030: 61 76 65 20 64 69 72 65 63 74 20 61 63 63 65 73 ave direct acces
1040: 73 20 74 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63 s to string.** c
1050: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 onstants within
1060: 74 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 the DLL..**.** I
1070: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
1080: 20 7b 48 31 30 30 32 31 7d 20 54 68 65 20 5b 73 {H10021} The [s
1090: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
10a0: 6e 5f 6e 75 6d 62 65 72 28 29 5d 20 69 6e 74 65 n_number()] inte
10b0: 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75 rface shall retu
10c0: 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 rn.** a
10d0: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 n integer equal
10e0: 74 6f 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 to [SQLITE_VERSI
10f0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a ON_NUMBER]..**.*
1100: 2a 20 7b 48 31 30 30 32 32 7d 20 54 68 65 20 5b * {H10022} The [
1110: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5d sqlite3_version]
1120: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 string constant
1130: 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 0a 2a shall contain.*
1140: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74 * the t
1150: 65 78 74 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 ext of the [SQLI
1160: 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73 74 72 69 TE_VERSION] stri
1170: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 ng..**.** {H1002
1180: 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 3} The [sqlite3_
1190: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 66 75 libversion()] fu
11a0: 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 nction shall ret
11b0: 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 urn.**
11c0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
11d0: 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f [sqlite3_versio
11e0: 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 n] string consta
11f0: 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 nt..*/.SQLITE_EX
1200: 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 TERN const char
1210: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b sqlite3_version[
1220: 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 ];.const char *s
1230: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1240: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c n(void);.int sql
1250: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f ite3_libversion_
1260: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f number(void);../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
1280: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 est To See If Th
1290: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 e Library Is Thr
12a0: 65 61 64 73 61 66 65 20 7b 48 31 30 31 30 30 7d eadsafe {H10100}
12b0: 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S60100>.**.**
12c0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f SQLite can be co
12d0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 mpiled with or w
12e0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 ithout mutexes.
12f0: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 When.** the [SQ
1300: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d LITE_THREADSAFE]
1310: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C preprocessor
1320: 6d 61 63 72 6f 20 69 73 20 74 72 75 65 2c 20 6d macro is true, m
1330: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e utexes.** are en
1340: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 abled and SQLite
1350: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 is threadsafe.
1360: 20 57 68 65 6e 20 74 68 61 74 20 6d 61 63 72 6f When that macro
1370: 20 69 73 20 66 61 6c 73 65 2c 0a 2a 2a 20 74 68 is false,.** th
1380: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d e mutexes are om
1390: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 itted. Without
13a0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 the mutexes, it
13b0: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 is not safe.** t
13c0: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e o use SQLite con
13d0: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d currently from m
13e0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 ore than one thr
13f0: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c ead..**.** Enabl
1400: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 ing mutexes incu
1410: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 rs a measurable
1420: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 performance pena
1430: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 lty..** So if sp
1440: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 eed is of utmost
1450: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 importance, it
1460: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 makes sense to d
1470: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 isable.** the mu
1480: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 texes. But for
1490: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 maximum safety,
14a0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 mutexes should b
14b0: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 e enabled..** Th
14c0: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 e default behavi
14d0: 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 or is for mutexe
14e0: 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e s to be enabled.
14f0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
1500: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
1510: 64 20 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74 d by a program t
1520: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 o make sure that
1530: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 the.** version
1540: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 of SQLite that i
1550: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 t is linking aga
1560: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 inst was compile
1570: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 d with.** the de
1580: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 sired setting of
1590: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
15a0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a EADSAFE] macro..
15b0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
15c0: 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 face only report
15d0: 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 s on the compile
15e0: 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 -time mutex sett
15f0: 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 ing.** of the [S
1600: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
1610: 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 ] flag. If SQLi
1620: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
1630: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 ith.** SQLITE_TH
1640: 52 45 41 44 53 41 46 45 3d 31 20 74 68 65 6e 20 READSAFE=1 then
1650: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 mutexes are enab
1660: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 led by default b
1670: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c ut.** can be ful
1680: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 ly or partially
1690: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 disabled using a
16a0: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
16b0: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 3_config()].** w
16c0: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 ith the verbs [S
16d0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
16e0: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c GLETHREAD], [SQL
16f0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
1700: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b THREAD],.** or [
1710: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
1720: 54 45 58 5d 2e 20 20 54 68 65 20 72 65 74 75 72 TEX]. The retur
1730: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 n value of this
1740: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a function shows.*
1750: 2a 20 6f 6e 6c 79 20 74 68 65 20 64 65 66 61 75 * only the defau
1760: 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 lt compile-time
1770: 73 65 74 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79 setting, not any
1780: 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 run-time change
1790: 73 0a 2a 2a 20 74 6f 20 74 68 61 74 20 73 65 74 s.** to that set
17a0: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 ting..**.** INVA
17b0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
17c0: 31 30 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 10101} The [sqli
17d0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 te3_threadsafe()
17e0: 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c ] function shall
17f0: 20 72 65 74 75 72 6e 20 6e 6f 6e 7a 65 72 6f 20 return nonzero
1800: 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 if.** S
1810: 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c QLite was compil
1820: 65 64 20 77 69 74 68 20 74 68 65 20 69 74 73 20 ed with the its
1830: 6d 75 74 65 78 65 73 20 65 6e 61 62 6c 65 64 20 mutexes enabled
1840: 62 79 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 by default.**
1850: 20 20 20 20 20 20 20 6f 72 20 7a 65 72 6f 20 69 or zero i
1860: 66 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d f SQLite was com
1870: 70 69 6c 65 64 20 73 75 63 68 20 74 68 61 74 20 piled such that
1880: 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 20 mutexes are.**
1890: 20 20 20 20 20 20 20 20 70 65 72 6d 61 6e 65 6e permanen
18a0: 74 6c 79 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a tly disabled..**
18b0: 0a 2a 2a 20 7b 48 31 30 31 30 32 7d 20 54 68 65 .** {H10102} The
18c0: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
18d0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
18e0: 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 66 75 threadsafe()] fu
18f0: 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 nction.**
1900: 20 20 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61 shall not cha
1910: 6e 67 65 20 77 68 65 6e 20 6d 75 74 65 78 20 73 nge when mutex s
1920: 65 74 74 69 6e 67 20 61 72 65 20 6d 6f 64 69 66 etting are modif
1930: 69 65 64 20 61 74 0a 2a 2a 20 20 20 20 20 20 20 ied at.**
1940: 20 20 20 72 75 6e 74 69 6d 65 20 75 73 69 6e 67 runtime using
1950: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
1960: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
1970: 65 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 e and .**
1980: 20 20 20 65 73 70 65 63 69 61 6c 6c 79 20 74 68 especially th
1990: 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 e [SQLITE_CONFIG
19a0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 0a _SINGLETHREAD],.
19b0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c ** [SQL
19c0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
19d0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 THREAD], [SQLITE
19e0: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a _CONFIG_SERIALIZ
19f0: 45 44 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ED],.**
1a00: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e and [SQLITE_CON
1a10: 46 49 47 5f 4d 55 54 45 58 5d 20 76 65 72 62 73 FIG_MUTEX] verbs
1a20: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
1a30: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 _threadsafe(void
1a40: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1a50: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
1a60: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b nection Handle {
1a70: 48 31 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e H12000} <S40200>
1a80: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 .** KEYWORDS: {d
1a90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1aa0: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f on} {database co
1ab0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a nnections}.**.**
1ac0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 Each open SQLit
1ad0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 e database is re
1ae0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 presented by a p
1af0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
1b00: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 tance of.** the
1b10: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 opaque structure
1b20: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 named "sqlite3"
1b30: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 . It is useful
1b40: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 to think of an s
1b50: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 qlite3.** pointe
1b60: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 r as an object.
1b70: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 The [sqlite3_op
1b80: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
1b90: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a open16()], and.*
1ba0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f * [sqlite3_open_
1bb0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 v2()] interfaces
1bc0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 are its constru
1bd0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 ctors, and [sqli
1be0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 te3_close()].**
1bf0: 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f is its destructo
1c00: 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 r. There are ma
1c10: 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 ny other interfa
1c20: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 ces (such as.**
1c30: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1c40: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 _v2()], [sqlite3
1c50: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
1c60: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
1c70: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
1c80: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 t()] to name but
1c90: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65 three) that are
1ca0: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a methods on an.*
1cb0: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 * sqlite3 object
1cc0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
1cd0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 uct sqlite3 sqli
1ce0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 te3;../*.** CAPI
1cf0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 3REF: 64-Bit Int
1d00: 65 67 65 72 20 54 79 70 65 73 20 7b 48 31 30 32 eger Types {H102
1d10: 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20 00} <S10110>.**
1d20: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 KEYWORDS: sqlite
1d30: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 _int64 sqlite_ui
1d40: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 nt64.**.** Becau
1d50: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 se there is no c
1d60: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 ross-platform wa
1d70: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d y to specify 64-
1d80: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 bit integer type
1d90: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c s.** SQLite incl
1da0: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f udes typedefs fo
1db0: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 r 64-bit signed
1dc0: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 and unsigned int
1dd0: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 egers..**.** The
1de0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 sqlite3_int64 a
1df0: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 nd sqlite3_uint6
1e00: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 4 are the prefer
1e10: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 red type definit
1e20: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c ions..** The sql
1e30: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 ite_int64 and sq
1e40: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 lite_uint64 type
1e50: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 s are supported
1e60: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a for backwards.**
1e70: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f compatibility o
1e80: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 nly..**.** INVAR
1e90: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
1ea0: 30 32 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 0201} The [sqlit
1eb0: 65 5f 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 e_int64] and [sq
1ec0: 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20 74 79 70 lite3_int64] typ
1ed0: 65 20 73 68 61 6c 6c 20 73 70 65 63 69 66 79 0a e shall specify.
1ee0: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 36 34 ** a 64
1ef0: 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
1f00: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 ger..**.** {H102
1f10: 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 02} The [sqlite_
1f20: 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c uint64] and [sql
1f30: 69 74 65 33 5f 75 69 6e 74 36 34 5d 20 74 79 70 ite3_uint64] typ
1f40: 65 20 73 68 61 6c 6c 20 73 70 65 63 69 66 79 0a e shall specify.
1f50: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 36 34 ** a 64
1f60: 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e -bit unsigned in
1f70: 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66 64 65 66 teger..*/.#ifdef
1f80: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 SQLITE_INT64_TY
1f90: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c PE. typedef SQL
1fa0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 ITE_INT64_TYPE s
1fb0: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 qlite_int64;. t
1fc0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 ypedef unsigned
1fd0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 SQLITE_INT64_TYP
1fe0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b E sqlite_uint64;
1ff0: 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f .#elif defined(_
2000: 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 MSC_VER) || defi
2010: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f ned(__BORLANDC__
2020: 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e ). typedef __in
2030: 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 t64 sqlite_int64
2040: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 ;. typedef unsi
2050: 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c gned __int64 sql
2060: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 ite_uint64;.#els
2070: 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 e. typedef long
2080: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 long int sqlite
2090: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 _int64;. typede
20a0: 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 f unsigned long
20b0: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f long int sqlite_
20c0: 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 uint64;.#endif.t
20d0: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e ypedef sqlite_in
20e0: 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 t64 sqlite3_int6
20f0: 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 4;.typedef sqlit
2100: 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e_uint64 sqlite3
2110: 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 _uint64;../*.**
2120: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 If compiling for
2130: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 a processor tha
2140: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 t lacks floating
2150: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a point support,.
2160: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e ** substitute in
2170: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 teger for floati
2180: 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 ng-point..*/.#if
2190: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f def SQLITE_OMIT_
21a0: 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 FLOATING_POINT.#
21b0: 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 define double s
21c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e qlite3_int64.#en
21d0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
21e0: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 REF: Closing A D
21f0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
2200: 6f 6e 20 7b 48 31 32 30 31 30 7d 20 3c 53 33 30 on {H12010} <S30
2210: 31 30 30 3e 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 100><S40200>.**.
2220: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
2230: 69 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f is the destructo
2240: 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 r for the [sqlit
2250: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a e3] object..**.*
2260: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 * Applications s
2270: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 hould [sqlite3_f
2280: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 inalize | finali
2290: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 ze] all [prepare
22a0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a d statements].**
22b0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c and [sqlite3_bl
22c0: 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 ob_close | close
22d0: 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 ] all [BLOB hand
22e0: 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 les] associated
22f0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 73 71 6c with.** the [sql
2300: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 ite3] object pri
2310: 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 or to attempting
2320: 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 to close the ob
2330: 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 ject..** The [sq
2340: 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 lite3_next_stmt(
2350: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e )] interface can
2360: 20 62 65 20 75 73 65 64 20 74 6f 20 6c 6f 63 61 be used to loca
2370: 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 72 65 70 61 te all.** [prepa
2380: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 red statements]
2390: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
23a0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
23b0: 65 63 74 69 6f 6e 5d 20 69 66 20 64 65 73 69 72 ection] if desir
23c0: 65 64 2e 0a 2a 2a 20 54 79 70 69 63 61 6c 20 63 ed..** Typical c
23d0: 6f 64 65 20 6d 69 67 68 74 20 6c 6f 6f 6b 20 6c ode might look l
23e0: 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 ike this:.**.**
23f0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
2400: 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d >.** sqlite3_stm
2410: 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a 20 77 68 69 t *pStmt;.** whi
2420: 6c 65 28 20 28 70 53 74 6d 74 20 3d 20 73 71 6c le( (pStmt = sql
2430: 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 64 ite3_next_stmt(d
2440: 62 2c 20 30 29 29 21 3d 30 20 29 7b 0a 2a 2a 20 b, 0))!=0 ){.**
2450: 26 6e 62 73 70 3b 20 20 20 73 71 6c 69 74 65 33 sqlite3
2460: 5f 66 69 6e 61 6c 69 7a 65 28 70 53 74 6d 74 29 _finalize(pStmt)
2470: 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f 70 72 65 3e ;.** }.** </pre>
2480: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
2490: 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f .** If [sqlite3_
24a0: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f close()] is invo
24b0: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e ked while a tran
24c0: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c saction is open,
24d0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 .** the transact
24e0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ion is automatic
24f0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b ally rolled back
2500: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
2510: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 TS:.**.** {H1201
2520: 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 1} A successful
2530: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
2540: 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68 61 6c 6c _close(C)] shall
2550: 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20 destroy the.**
2560: 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 [databa
2570: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f se connection] o
2580: 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b bject C..**.** {
2590: 48 31 32 30 31 32 7d 20 41 20 73 75 63 63 65 73 H12012} A succes
25a0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
25b0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 lite3_close(C)]
25c0: 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c shall return SQL
25d0: 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ITE_OK..**.** {H
25e0: 31 32 30 31 33 7d 20 41 20 73 75 63 63 65 73 73 12013} A success
25f0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
2600: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73 ite3_close(C)] s
2610: 68 61 6c 6c 20 72 65 6c 65 61 73 65 20 61 6c 6c hall release all
2620: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d .** mem
2630: 6f 72 79 20 61 6e 64 20 73 79 73 74 65 6d 20 72 ory and system r
2640: 65 73 6f 75 72 63 65 73 20 61 73 73 6f 63 69 61 esources associa
2650: 74 65 64 20 77 69 74 68 20 5b 64 61 74 61 62 61 ted with [databa
2660: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a se connection].*
2670: 2a 20 20 20 20 20 20 20 20 20 20 43 2e 0a 2a 2a * C..**
2680: 0a 2a 2a 20 7b 48 31 32 30 31 34 7d 20 41 20 63 .** {H12014} A c
2690: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
26a0: 63 6c 6f 73 65 28 43 29 5d 20 6f 6e 20 61 20 5b close(C)] on a [
26b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
26c0: 69 6f 6e 5d 20 43 20 74 68 61 74 0a 2a 2a 20 20 ion] C that.**
26d0: 20 20 20 20 20 20 20 20 68 61 73 20 6f 6e 65 20 has one
26e0: 6f 72 20 6d 6f 72 65 20 6f 70 65 6e 20 5b 70 72 or more open [pr
26f0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2700: 73 5d 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 s] shall fail wi
2710: 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 th.** a
2720: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 n [SQLITE_BUSY]
2730: 65 72 72 6f 72 20 63 6f 64 65 2e 0a 2a 2a 0a 2a error code..**.*
2740: 2a 20 7b 48 31 32 30 31 35 7d 20 41 20 63 61 6c * {H12015} A cal
2750: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c l to [sqlite3_cl
2760: 6f 73 65 28 43 29 5d 20 77 68 65 72 65 20 43 20 ose(C)] where C
2770: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
2780: 72 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 r shall.**
2790: 20 20 20 20 72 65 74 75 72 6e 20 53 51 4c 49 54 return SQLIT
27a0: 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 E_OK..**.** {H12
27b0: 30 31 39 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74 019} When [sqlit
27c0: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 69 73 20 e3_close(C)] is
27d0: 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 5b 64 61 invoked on a [da
27e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
27f0: 6e 5d 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 20 n] C.**
2800: 20 74 68 61 74 20 68 61 73 20 61 20 70 65 6e 64 that has a pend
2810: 69 6e 67 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c ing transaction,
2820: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
2830: 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 shall be.**
2840: 20 20 20 20 20 20 72 6f 6c 6c 65 64 20 62 61 63 rolled bac
2850: 6b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 k..**.** ASSUMPT
2860: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 IONS:.**.** {A12
2870: 30 31 36 7d 20 54 68 65 20 43 20 70 61 72 61 6d 016} The C param
2880: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
2890: 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75 73 74 20 _close(C)] must
28a0: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c be either a NULL
28b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 .** poi
28c0: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 nter or an [sqli
28d0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e te3] object poin
28e0: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 ter obtained.**
28f0: 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 5b 73 from [s
2900: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
2910: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
2920: 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 )], or.**
2930: 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e [sqlite3_open
2940: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 _v2()], and not
2950: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 previously close
2960: 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 d..*/.int sqlite
2970: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 3_close(sqlite3
2980: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 *);../*.** The t
2990: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 ype for a callba
29a0: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 ck function..**
29b0: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 This is legacy a
29c0: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 nd deprecated.
29d0: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 It is included f
29e0: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a or historical.**
29f0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 compatibility a
2a00: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 nd is not docume
2a10: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 nted..*/.typedef
2a20: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 int (*sqlite3_c
2a30: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 allback)(void*,i
2a40: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a nt,char**, char*
2a50: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
2a60: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 REF: One-Step Qu
2a70: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e ery Execution In
2a80: 74 65 72 66 61 63 65 20 7b 48 31 32 31 30 30 7d terface {H12100}
2a90: 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S10000>.**.**
2aa0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 The sqlite3_exec
2ab0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
2ac0: 61 20 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 a convenient way
2ad0: 20 6f 66 20 72 75 6e 6e 69 6e 67 20 6f 6e 65 20 of running one
2ae0: 6f 72 20 6d 6f 72 65 0a 2a 2a 20 53 51 4c 20 73 or more.** SQL s
2af0: 74 61 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 tatements withou
2b00: 74 20 68 61 76 69 6e 67 20 74 6f 20 77 72 69 74 t having to writ
2b10: 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 e a lot of C cod
2b20: 65 2e 20 20 54 68 65 20 55 54 46 2d 38 20 65 6e e. The UTF-8 en
2b30: 63 6f 64 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 coded.** SQL sta
2b40: 74 65 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73 tements are pass
2b50: 65 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63 ed in as the sec
2b60: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ond parameter to
2b70: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2e sqlite3_exec().
2b80: 0a 2a 2a 20 54 68 65 20 73 74 61 74 65 6d 65 6e .** The statemen
2b90: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 ts are evaluated
2ba0: 20 6f 6e 65 20 62 79 20 6f 6e 65 20 75 6e 74 69 one by one unti
2bb0: 6c 20 65 69 74 68 65 72 20 61 6e 20 65 72 72 6f l either an erro
2bc0: 72 20 6f 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 r or.** an inter
2bd0: 72 75 70 74 20 69 73 20 65 6e 63 6f 75 6e 74 65 rupt is encounte
2be0: 72 65 64 2c 20 6f 72 20 75 6e 74 69 6c 20 74 68 red, or until th
2bf0: 65 79 20 61 72 65 20 61 6c 6c 20 64 6f 6e 65 2e ey are all done.
2c00: 20 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 The 3rd parame
2c10: 74 65 72 0a 2a 2a 20 69 73 20 61 6e 20 6f 70 74 ter.** is an opt
2c20: 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 74 ional callback t
2c30: 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f hat is invoked o
2c40: 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 nce for each row
2c50: 20 6f 66 20 61 6e 79 20 71 75 65 72 79 0a 2a 2a of any query.**
2c60: 20 72 65 73 75 6c 74 73 20 70 72 6f 64 75 63 65 results produce
2c70: 64 20 62 79 20 74 68 65 20 53 51 4c 20 73 74 61 d by the SQL sta
2c80: 74 65 6d 65 6e 74 73 2e 20 20 54 68 65 20 35 74 tements. The 5t
2c90: 68 20 70 61 72 61 6d 65 74 65 72 20 74 65 6c 6c h parameter tell
2ca0: 73 20 77 68 65 72 65 0a 2a 2a 20 74 6f 20 77 72 s where.** to wr
2cb0: 69 74 65 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 ite any error me
2cc0: 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ssages..**.** Th
2cd0: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 e error message
2ce0: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f passed back thro
2cf0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 ugh the 5th para
2d00: 6d 65 74 65 72 20 69 73 20 68 65 6c 64 0a 2a 2a meter is held.**
2d10: 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 in memory obtai
2d20: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
2d30: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 3_malloc()]. To
2d40: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 avoid a memory
2d50: 6c 65 61 6b 2c 0a 2a 2a 20 74 68 65 20 63 61 6c leak,.** the cal
2d60: 6c 69 6e 67 20 61 70 70 6c 69 63 61 74 69 6f 6e ling application
2d70: 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 5b 73 71 should call [sq
2d80: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e lite3_free()] on
2d90: 20 61 6e 79 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 any error.** me
2da0: 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 74 ssage returned t
2db0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 hrough the 5th p
2dc0: 61 72 61 6d 65 74 65 72 20 77 68 65 6e 20 69 74 arameter when it
2dd0: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 has finished us
2de0: 69 6e 67 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 ing.** the error
2df0: 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 message..**.**
2e00: 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 If the SQL state
2e10: 6d 65 6e 74 20 69 6e 20 74 68 65 20 32 6e 64 20 ment in the 2nd
2e20: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c parameter is NUL
2e30: 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 L or an empty st
2e40: 72 69 6e 67 0a 2a 2a 20 6f 72 20 61 20 73 74 72 ring.** or a str
2e50: 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6f ing containing o
2e60: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61 nly whitespace a
2e70: 6e 64 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 nd comments, the
2e80: 6e 20 6e 6f 20 53 51 4c 0a 2a 2a 20 73 74 61 74 n no SQL.** stat
2e90: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 ements are evalu
2ea0: 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 ated and the dat
2eb0: 61 62 61 73 65 20 69 73 20 6e 6f 74 20 63 68 61 abase is not cha
2ec0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nged..**.** The
2ed0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
2ee0: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c nterface is impl
2ef0: 65 6d 65 6e 74 65 64 20 69 6e 20 74 65 72 6d 73 emented in terms
2f00: 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f of.** [sqlite3_
2f10: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b prepare_v2()], [
2f20: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c sqlite3_step()],
2f30: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 and [sqlite3_fi
2f40: 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 nalize()]..** Th
2f50: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
2f60: 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f routine does no
2f70: 74 68 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74 thing to the dat
2f80: 61 62 61 73 65 20 74 68 61 74 20 63 61 6e 6e 6f abase that canno
2f90: 74 20 62 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 t be done.** by
2fa0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2fb0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 _v2()], [sqlite3
2fc0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 _step()], and [s
2fd0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2fe0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 )]..**.** INVARI
2ff0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ANTS:.**.** {H12
3000: 31 30 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 101} A successfu
3010: 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 l invocation of
3020: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c [sqlite3_exec(D,
3030: 53 2c 43 2c 41 2c 45 29 5d 0a 2a 2a 20 20 20 20 S,C,A,E)].**
3040: 20 20 20 20 20 20 73 68 61 6c 6c 20 73 65 71 75 shall sequ
3050: 65 6e 74 69 61 6c 6c 79 20 65 76 61 6c 75 61 74 entially evaluat
3060: 65 20 61 6c 6c 20 6f 66 20 74 68 65 20 55 54 46 e all of the UTF
3070: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 20 -8 encoded,.**
3080: 20 20 20 20 20 20 20 20 73 65 6d 69 63 6f 6c 6f semicolo
3090: 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 n-separated SQL
30a0: 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 statements in th
30b0: 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 e zero-terminate
30c0: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 d.** st
30d0: 72 69 6e 67 20 53 20 77 69 74 68 69 6e 20 74 68 ring S within th
30e0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 e context of the
30f0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
3100: 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 ction] D..**.**
3110: 7b 48 31 32 31 30 32 7d 20 49 66 20 74 68 65 20 {H12102} If the
3120: 53 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b S parameter to [
3130: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 sqlite3_exec(D,S
3140: 2c 43 2c 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c ,C,A,E)] is NULL
3150: 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 then.**
3160: 20 20 74 68 65 20 61 63 74 69 6f 6e 73 20 6f 66 the actions of
3170: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 73 the interface s
3180: 68 61 6c 6c 20 62 65 20 74 68 65 20 73 61 6d 65 hall be the same
3190: 20 61 73 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 as if the.**
31a0: 20 20 20 20 20 20 20 53 20 70 61 72 61 6d 65 74 S paramet
31b0: 65 72 20 77 65 72 65 20 61 6e 20 65 6d 70 74 79 er were an empty
31c0: 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b string..**.** {
31d0: 48 31 32 31 30 34 7d 20 54 68 65 20 72 65 74 75 H12104} The retu
31e0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c rn value of [sql
31f0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 ite3_exec()] sha
3200: 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 4f 4b ll be [SQLITE_OK
3210: 5d 20 69 66 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 ] if all.**
3220: 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 SQL stateme
3230: 6e 74 73 20 72 75 6e 20 73 75 63 63 65 73 73 66 nts run successf
3240: 75 6c 6c 79 20 61 6e 64 20 74 6f 20 63 6f 6d 70 ully and to comp
3250: 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 letion..**.** {H
3260: 31 32 31 30 35 7d 20 54 68 65 20 72 65 74 75 72 12105} The retur
3270: 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 n value of [sqli
3280: 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c te3_exec()] shal
3290: 6c 20 62 65 20 61 6e 20 61 70 70 72 6f 70 72 69 l be an appropri
32a0: 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ate.**
32b0: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 non-zero [error
32c0: 63 6f 64 65 5d 20 69 66 20 61 6e 79 20 53 51 4c code] if any SQL
32d0: 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 73 statement fails
32e0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 37 7d ..**.** {H12107}
32f0: 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 If one or more
3300: 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 of the SQL state
3310: 6d 65 6e 74 73 20 68 61 6e 64 65 64 20 74 6f 20 ments handed to
3320: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
3330: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 .** ret
3340: 75 72 6e 20 72 65 73 75 6c 74 73 20 61 6e 64 20 urn results and
3350: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
3360: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 r is not NULL, t
3370: 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hen.**
3380: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e the callback fun
3390: 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 ction specified
33a0: 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d by the 3rd param
33b0: 65 74 65 72 20 73 68 61 6c 6c 20 62 65 0a 2a 2a eter shall be.**
33c0: 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 6b 65 invoke
33d0: 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 d once for each
33e0: 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 0a 2a row of result..*
33f0: 2a 0a 2a 2a 20 7b 48 31 32 31 31 30 7d 20 49 66 *.** {H12110} If
3400: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
3410: 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f turns a non-zero
3420: 20 76 61 6c 75 65 20 74 68 65 6e 20 5b 73 71 6c value then [sql
3430: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 ite3_exec()].**
3440: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 61 shall a
3450: 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 bort the SQL sta
3460: 74 65 6d 65 6e 74 20 69 74 20 69 73 20 63 75 72 tement it is cur
3470: 72 65 6e 74 6c 79 20 65 76 61 6c 75 61 74 69 6e rently evaluatin
3480: 67 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 g,.** s
3490: 6b 69 70 20 61 6c 6c 20 73 75 62 73 65 71 75 65 kip all subseque
34a0: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 nt SQL statement
34b0: 73 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 s, and return [S
34c0: 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a QLITE_ABORT]..**
34d0: 0a 2a 2a 20 7b 48 31 32 31 31 33 7d 20 54 68 65 .** {H12113} The
34e0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
34f0: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 ] routine shall
3500: 70 61 73 73 20 69 74 73 20 34 74 68 20 70 61 72 pass its 4th par
3510: 61 6d 65 74 65 72 20 74 68 72 6f 75 67 68 0a 2a ameter through.*
3520: 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68 * as th
3530: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 e 1st parameter
3540: 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e of the callback.
3550: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 36 7d 20 .**.** {H12116}
3560: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 The [sqlite3_exe
3570: 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 c()] routine sha
3580: 6c 6c 20 73 65 74 20 74 68 65 20 32 6e 64 20 70 ll set the 2nd p
3590: 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a arameter of its.
35a0: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c ** call
35b0: 62 61 63 6b 20 74 6f 20 62 65 20 74 68 65 20 6e back to be the n
35c0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
35d0: 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 in the current
35e0: 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 row of.**
35f0: 20 20 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a result..**.**
3600: 20 7b 48 31 32 31 31 39 7d 20 54 68 65 20 5b 73 {H12119} The [s
3610: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 qlite3_exec()] r
3620: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 outine shall set
3630: 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 the 3rd paramet
3640: 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 er of its.**
3650: 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 callback t
3660: 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20 6f 66 o be an array of
3670: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
3680: 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 ings holding the
3690: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c .** val
36a0: 75 65 73 20 66 6f 72 20 65 61 63 68 20 63 6f 6c ues for each col
36b0: 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 umn in the curre
36c0: 6e 74 20 72 65 73 75 6c 74 20 73 65 74 20 72 6f nt result set ro
36d0: 77 20 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 w as.**
36e0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
36f0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
3700: 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ext()]..**.** {H
3710: 31 32 31 32 32 7d 20 54 68 65 20 5b 73 71 6c 69 12122} The [sqli
3720: 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 te3_exec()] rout
3730: 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68 ine shall set th
3740: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
3750: 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 of its.**
3760: 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 callback to b
3770: 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f e an array of po
3780: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 inters to string
3790: 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a s holding the.**
37a0: 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 73 20 names
37b0: 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e of result column
37c0: 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72 s as obtained fr
37d0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 om [sqlite3_colu
37e0: 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a mn_name()]..**.*
37f0: 2a 20 7b 48 31 32 31 32 35 7d 20 49 66 20 74 68 * {H12125} If th
3800: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
3810: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 to [sqlite3_exec
3820: 28 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e ()] is NULL then
3830: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
3840: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 lite3_exec()] sh
3850: 61 6c 6c 20 73 69 6c 65 6e 74 6c 79 20 64 69 73 all silently dis
3860: 63 61 72 64 20 71 75 65 72 79 20 72 65 73 75 6c card query resul
3870: 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 ts..**.** {H1213
3880: 31 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 1} If an error o
3890: 63 63 75 72 73 20 77 68 69 6c 65 20 70 61 72 73 ccurs while pars
38a0: 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e ing or evaluatin
38b0: 67 20 61 6e 79 20 6f 66 20 74 68 65 20 53 51 4c g any of the SQL
38c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 .** sta
38d0: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 53 tements in the S
38e0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 parameter of [s
38f0: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c qlite3_exec(D,S,
3900: 43 2c 41 2c 45 29 5d 20 61 6e 64 20 69 66 0a 2a C,A,E)] and if.*
3910: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 45 * the E
3920: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f parameter is no
3930: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 73 71 t NULL, then [sq
3940: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 lite3_exec()] sh
3950: 61 6c 6c 20 73 74 6f 72 65 0a 2a 2a 20 20 20 20 all store.**
3960: 20 20 20 20 20 20 69 6e 20 2a 45 20 61 6e 20 61 in *E an a
3970: 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 ppropriate error
3980: 20 6d 65 73 73 61 67 65 20 77 72 69 74 74 65 6e message written
3990: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 into memory obt
39a0: 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 ained.**
39b0: 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f from [sqlite3_
39c0: 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a malloc()]..**.**
39d0: 20 7b 48 31 32 31 33 34 7d 20 54 68 65 20 5b 73 {H12134} The [s
39e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c qlite3_exec(D,S,
39f0: 43 2c 41 2c 45 29 5d 20 72 6f 75 74 69 6e 65 20 C,A,E)] routine
3a00: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 76 61 shall set the va
3a10: 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 lue of.**
3a20: 20 20 20 2a 45 20 74 6f 20 4e 55 4c 4c 20 69 66 *E to NULL if
3a30: 20 45 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 E is not NULL a
3a40: 6e 64 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 nd there are no
3a50: 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 errors..**.** {H
3a60: 31 32 31 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 12137} The [sqli
3a70: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 te3_exec(D,S,C,A
3a80: 2c 45 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 ,E)] function sh
3a90: 61 6c 6c 20 73 65 74 20 74 68 65 20 5b 65 72 72 all set the [err
3aa0: 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 20 20 20 20 or code].**
3ab0: 20 20 20 20 20 61 6e 64 20 6d 65 73 73 61 67 65 and message
3ac0: 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 accessible via
3ad0: 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 [sqlite3_errcode
3ae0: 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ()],.**
3af0: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
3b00: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
3b10: 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 3_errmsg16()]..*
3b20: 2a 0a 2a 2a 20 7b 48 31 32 31 33 38 7d 20 49 66 *.** {H12138} If
3b30: 20 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 the S parameter
3b40: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 to [sqlite3_exe
3b50: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73 c(D,S,C,A,E)] is
3b60: 20 4e 55 4c 4c 20 6f 72 20 61 6e 0a 2a 2a 20 20 NULL or an.**
3b70: 20 20 20 20 20 20 20 20 65 6d 70 74 79 20 73 74 empty st
3b80: 72 69 6e 67 20 6f 72 20 63 6f 6e 74 61 69 6e 73 ring or contains
3b90: 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74 nothing other t
3ba0: 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 2c 20 han whitespace,
3bb0: 63 6f 6d 6d 65 6e 74 73 2c 0a 2a 2a 20 20 20 20 comments,.**
3bc0: 20 20 20 20 20 20 61 6e 64 2f 6f 72 20 73 65 6d and/or sem
3bd0: 69 63 6f 6c 6f 6e 73 2c 20 74 68 65 6e 20 72 65 icolons, then re
3be0: 73 75 6c 74 73 20 6f 66 20 5b 73 71 6c 69 74 65 sults of [sqlite
3bf0: 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 3_errcode()],.**
3c00: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
3c10: 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e e3_errmsg()], an
3c20: 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 d [sqlite3_errms
3c30: 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 g16()].**
3c40: 20 20 20 73 68 61 6c 6c 20 72 65 73 65 74 20 74 shall reset t
3c50: 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f 20 65 72 o indicate no er
3c60: 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 rors..**.** ASSU
3c70: 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b MPTIONS:.**.** {
3c80: 41 31 32 31 34 31 7d 20 54 68 65 20 66 69 72 73 A12141} The firs
3c90: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b t parameter to [
3ca0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
3cb0: 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64 must be an valid
3cc0: 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 20 and open.**
3cd0: 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 [database
3ce0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a connection]..**.
3cf0: 2a 2a 20 7b 41 31 32 31 34 32 7d 20 54 68 65 20 ** {A12142} The
3d00: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3d10: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 ion must not be
3d20: 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20 closed while.**
3d30: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
3d40: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 3_exec()] is run
3d50: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 ning..**.** {A12
3d60: 31 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 143} The calling
3d70: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 function should
3d80: 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 use [sqlite3_fr
3d90: 65 65 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a ee()] to free.**
3da0: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 the me
3db0: 6d 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73 mory that *errms
3dc0: 67 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 g is left pointi
3dd0: 6e 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65 ng at once the e
3de0: 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 rror.**
3df0: 20 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20 6c message is no l
3e00: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a onger needed..**
3e10: 0a 2a 2a 20 7b 41 31 32 31 34 35 7d 20 54 68 65 .** {A12145} The
3e20: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
3e30: 65 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 ext in the 2nd p
3e40: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
3e50: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 ite3_exec()].**
3e60: 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 72 65 must re
3e70: 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77 main unchanged w
3e80: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 hile [sqlite3_ex
3e90: 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 ec()] is running
3ea0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
3eb0: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 _exec(. sqlite3
3ec0: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *,
3ed0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3ee0: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 /* An open d
3ef0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e atabase */. con
3f00: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 st char *sql,
3f10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3f20: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 /* SQL t
3f30: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a o be evaluated *
3f40: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 /. int (*callba
3f50: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 ck)(void*,int,ch
3f60: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f ar**,char**), /
3f70: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 * Callback funct
3f80: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c ion */. void *,
3f90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3fa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3fb0: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d /* 1st argum
3fc0: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 ent to callback
3fd0: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d */. char **errm
3fe0: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 sg
3ff0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4000: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 /* Error msg wri
4010: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a tten here */.);.
4020: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
4030: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 Result Codes {H
4040: 31 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 10210} <S10700>.
4050: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c ** KEYWORDS: SQL
4060: 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f ITE_OK {error co
4070: 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 de} {error codes
4080: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
4090: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 result code} {re
40a0: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a sult codes}.**.*
40b0: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 * Many SQLite fu
40c0: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 nctions return a
40d0: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 n integer result
40e0: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 code from the s
40f0: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 et shown.** here
4100: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 in order to ind
4110: 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f icates success o
4120: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a r failure..**.**
4130: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 New error codes
4140: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
4150: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 future versions
4160: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
4170: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c * See also: [SQL
4180: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c ITE_IOERR_READ |
4190: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
41a0: 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 codes].*/.#defi
41b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 ne SQLITE_OK
41c0: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 0 /* Su
41d0: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 ccessful result
41e0: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d */./* beginning-
41f0: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a of-error-codes *
4200: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4210: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 _ERROR 1
4220: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f /* SQL error o
4230: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 r missing databa
4240: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 se */.#define SQ
4250: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 LITE_INTERNAL
4260: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 2 /* Interna
4270: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e l logic error in
4280: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 SQLite */.#defi
4290: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 ne SQLITE_PERM
42a0: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 3 /* Ac
42b0: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 cess permission
42c0: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e denied */.#defin
42d0: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 e SQLITE_ABORT
42e0: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 4 /* Cal
42f0: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 lback routine re
4300: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 quested an abort
4310: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4320: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 TE_BUSY
4330: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 5 /* The datab
4340: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b ase file is lock
4350: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
4360: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 LITE_LOCKED
4370: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 6 /* A table
4380: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 in the database
4390: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 is locked */.#d
43a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d efine SQLITE_NOM
43b0: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a EM 7 /*
43c0: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c A malloc() fail
43d0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
43e0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 LITE_READONLY
43f0: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 8 /* Attempt
4400: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 to write a read
4410: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f only database */
4420: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4430: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 INTERRUPT 9
4440: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 /* Operation te
4450: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 rminated by sqli
4460: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a te3_interrupt()*
4470: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4480: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 _IOERR 10
4490: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f /* Some kind o
44a0: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 f disk I/O error
44b0: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 occurred */.#de
44c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 fine SQLITE_CORR
44d0: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 UPT 11 /*
44e0: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 The database dis
44f0: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f k image is malfo
4500: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rmed */.#define
4510: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 SQLITE_NOTFOUND
4520: 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 12 /* NOT U
4530: 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 SED. Table or re
4540: 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a cord not found *
4550: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4560: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 _FULL 13
4570: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 /* Insertion f
4580: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 ailed because da
4590: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a tabase is full *
45a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
45b0: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 _CANTOPEN 14
45c0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f /* Unable to o
45d0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 pen the database
45e0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 file */.#define
45f0: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c SQLITE_PROTOCOL
4600: 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 15 /* NOT
4610: 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c USED. Database l
4620: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 ock protocol err
4630: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
4640: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 LITE_EMPTY
4650: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 16 /* Databas
4660: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 e is empty */.#d
4670: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 efine SQLITE_SCH
4680: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a EMA 17 /*
4690: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 The database sc
46a0: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a hema changed */.
46b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
46c0: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 OOBIG 18
46d0: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f /* String or BLO
46e0: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c B exceeds size l
46f0: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 imit */.#define
4700: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
4710: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 T 19 /* Abort
4720: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 due to constrai
4730: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a nt violation */.
4740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
4750: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 ISMATCH 20
4760: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 /* Data type mis
4770: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 match */.#define
4780: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 SQLITE_MISUSE
4790: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 21 /* Libr
47a0: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 ary used incorre
47b0: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ctly */.#define
47c0: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 SQLITE_NOLFS
47d0: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 22 /* Uses
47e0: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 OS features not
47f0: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 supported on hos
4800: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
4810: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 ITE_AUTH
4820: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 23 /* Authoriz
4830: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a ation denied */.
4840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
4850: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 ORMAT 24
4860: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 /* Auxiliary dat
4870: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 abase format err
4880: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
4890: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 LITE_RANGE
48a0: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 25 /* 2nd par
48b0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
48c0: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 3_bind out of ra
48d0: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nge */.#define S
48e0: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 QLITE_NOTADB
48f0: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 26 /* File o
4900: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f pened that is no
4910: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c t a database fil
4920: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
4930: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 ITE_ROW
4940: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 100 /* sqlite3_
4950: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 step() has anoth
4960: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a er row ready */.
4970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
4980: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 ONE 101
4990: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 /* sqlite3_step(
49a0: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 ) has finished e
49b0: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 xecuting */./* e
49c0: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 nd-of-error-code
49d0: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 s */../*.** CAPI
49e0: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 3REF: Extended R
49f0: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 30 esult Codes {H10
4a00: 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 220} <S10700>.**
4a10: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 KEYWORDS: {exte
4a20: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d nded error code}
4a30: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 {extended error
4a40: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f codes}.** KEYWO
4a50: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 RDS: {extended r
4a60: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 esult code} {ext
4a70: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
4a80: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 es}.**.** In its
4a90: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 default configu
4aa0: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 ration, SQLite A
4ab0: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 PI routines retu
4ac0: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 rn one of 26 int
4ad0: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f eger.** [SQLITE_
4ae0: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 OK | result code
4af0: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 s]. However, ex
4b00: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f perience has sho
4b10: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a wn that many of.
4b20: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 ** these result
4b30: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f codes are too co
4b40: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 arse-grained. T
4b50: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 hey do not provi
4b60: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e de as.** much in
4b70: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 formation about
4b80: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 problems as prog
4b90: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 rammers might li
4ba0: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 ke. In an effor
4bb0: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 t to.** address
4bc0: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 this, newer vers
4bd0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 ions of SQLite (
4be0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e version 3.3.8 an
4bf0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 d later) include
4c00: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 .** support for
4c10: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c additional resul
4c20: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f t codes that pro
4c30: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c vide more detail
4c40: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a ed information.*
4c50: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 * about errors.
4c60: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 The extended res
4c70: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e ult codes are en
4c80: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 abled or disable
4c90: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 d.** on a per da
4ca0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
4cb0: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 n basis using th
4cc0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 e.** [sqlite3_ex
4cd0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
4ce0: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a des()] API..**.*
4cf0: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 * Some of the av
4d00: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 ailable extended
4d10: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 result codes ar
4d20: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a e listed here..*
4d30: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 * One may expect
4d40: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 the number of e
4d50: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
4d60: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 odes will be exp
4d70: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 and.** over time
4d80: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 . Software that
4d90: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 uses extended r
4da0: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 esult codes shou
4db0: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 ld expect.** to
4dc0: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 see new result c
4dd0: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 odes in future r
4de0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
4df0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c e..**.** The SQL
4e00: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f ITE_OK result co
4e10: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 de will never be
4e20: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 extended. It w
4e30: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 ill always.** be
4e40: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a exactly zero..*
4e50: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
4e60: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 33 7d 20 .**.** {H10223}
4e70: 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d The symbolic nam
4e80: 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 e for an extende
4e90: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73 68 d result code sh
4ea0: 61 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 all contains.**
4eb0: 20 20 20 20 20 20 20 20 20 61 20 72 65 6c 61 74 a relat
4ec0: 65 64 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c ed primary resul
4ed0: 74 20 63 6f 64 65 20 61 73 20 61 20 70 72 65 66 t code as a pref
4ee0: 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 ix..**.** {H1022
4ef0: 34 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c 4} Primary resul
4f00: 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61 t code names sha
4f10: 6c 6c 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e ll contain a sin
4f20: 67 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 65 gle "_" characte
4f30: 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 35 r..**.** {H10225
4f40: 7d 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c } Extended resul
4f50: 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61 t code names sha
4f60: 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f ll contain two o
4f70: 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 r more "_" chara
4f80: 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 cters..**.** {H1
4f90: 30 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69 0226} The numeri
4fa0: 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78 c value of an ex
4fb0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
4fc0: 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e de shall contain
4fd0: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
4fe0: 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f numeric value o
4ff0: 66 20 69 74 73 20 63 6f 72 72 65 73 70 6f 6e 64 f its correspond
5000: 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73 75 ing primary resu
5010: 6c 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 20 lt code in.**
5020: 20 20 20 20 20 20 20 69 74 73 20 6c 65 61 73 74 its least
5030: 20 73 69 67 6e 69 66 69 63 61 6e 74 20 38 20 62 significant 8 b
5040: 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 its..*/.#define
5050: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 SQLITE_IOERR_REA
5060: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 D (
5070: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5080: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
5090: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 QLITE_IOERR_SHOR
50a0: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 T_READ (S
50b0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 QLITE_IOERR | (2
50c0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
50d0: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 LITE_IOERR_WRITE
50e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
50f0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c LITE_IOERR | (3<
5100: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5110: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 ITE_IOERR_FSYNC
5120: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5130: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c ITE_IOERR | (4<<
5140: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5150: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 TE_IOERR_DIR_FSY
5160: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 NC (SQLI
5170: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 TE_IOERR | (5<<8
5180: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5190: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 E_IOERR_TRUNCATE
51a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
51b0: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 E_IOERR | (6<<8)
51c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
51d0: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 _IOERR_FSTAT
51e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
51f0: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 _IOERR | (7<<8))
5200: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5210: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 IOERR_UNLOCK
5220: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5230: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a IOERR | (8<<8)).
5240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5250: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 OERR_RDLOCK
5260: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5270: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 OERR | (9<<8)).#
5280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5290: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 ERR_DELETE
52a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
52b0: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 ERR | (10<<8)).#
52c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
52d0: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 ERR_BLOCKED
52e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
52f0: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 ERR | (11<<8)).#
5300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5310: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 ERR_NOMEM
5320: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5330: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 ERR | (12<<8)).#
5340: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5350: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 ERR_ACCESS
5360: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5370: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 ERR | (13<<8)).#
5380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5390: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 ERR_CHECKRESERVE
53a0: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f DLOCK (SQLITE_IO
53b0: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 0a ERR | (14<<8))..
53c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
53d0: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f Flags For File O
53e0: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b pen Operations {
53f0: 48 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e H10230} <H11120>
5400: 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 <H12700>.**.**
5410: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 These bit values
5420: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f are intended fo
5430: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 r use in the.**
5440: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
5450: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 the [sqlite3_op
5460: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 en_v2()] interfa
5470: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 ce and.** in the
5480: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
5490: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 o the xOpen meth
54a0: 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 od of the.** [sq
54b0: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
54c0: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 t..*/.#define SQ
54d0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
54e0: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 LY 0x000
54f0: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 00001.#define SQ
5500: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
5510: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 ITE 0x000
5520: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 00002.#define SQ
5530: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
5540: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
5550: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 00004.#define SQ
5560: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
5570: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 ONCLOSE 0x000
5580: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 00008.#define SQ
5590: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 LITE_OPEN_EXCLUS
55a0: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 IVE 0x000
55b0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 00010.#define SQ
55c0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 LITE_OPEN_MAIN_D
55d0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 B 0x000
55e0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 00100.#define SQ
55f0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 LITE_OPEN_TEMP_D
5600: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 B 0x000
5610: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 00200.#define SQ
5620: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 LITE_OPEN_TRANSI
5630: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 ENT_DB 0x000
5640: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 00400.#define SQ
5650: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a LITE_OPEN_MAIN_J
5660: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 OURNAL 0x000
5670: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 00800.#define SQ
5680: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a LITE_OPEN_TEMP_J
5690: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 OURNAL 0x000
56a0: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 01000.#define SQ
56b0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 LITE_OPEN_SUBJOU
56c0: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 RNAL 0x000
56d0: 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 02000.#define SQ
56e0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 LITE_OPEN_MASTER
56f0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 _JOURNAL 0x000
5700: 30 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 04000.#define SQ
5710: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 LITE_OPEN_NOMUTE
5720: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 X 0x000
5730: 30 38 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 08000../*.** CAP
5740: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 I3REF: Device Ch
5750: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48 aracteristics {H
5760: 31 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a 10240} <H11120>.
5770: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 **.** The xDevic
5780: 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 eCapabilities me
5790: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c thod of the [sql
57a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
57b0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 .** object retur
57c0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 ns an integer wh
57d0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 ich is a vector
57e0: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 of the these.**
57f0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 bit values expre
5800: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 ssing I/O charac
5810: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 teristics of the
5820: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a mass storage.**
5830: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c device that hol
5840: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 ds the file that
5850: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f the [sqlite3_io
5860: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 _methods].** ref
5870: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 ers to..**.** Th
5880: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
5890: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d TOMIC property m
58a0: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 eans that all wr
58b0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 ites of.** any s
58c0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 ize are atomic.
58d0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
58e0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 P_ATOMICnnn valu
58f0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 es.** mean that
5900: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 writes of blocks
5910: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 that are nnn by
5920: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a tes in size and.
5930: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 ** are aligned t
5940: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 o an address whi
5950: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ch is an integer
5960: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 multiple of.**
5970: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 nnn are atomic.
5980: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
5990: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 P_SAFE_APPEND va
59a0: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 lue means.** tha
59b0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 t when data is a
59c0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c ppended to a fil
59d0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 e, the data is a
59e0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 ppended.** first
59f0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f then the size o
5a00: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 f the file is ex
5a10: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 tended, never th
5a20: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 e other.** way a
5a30: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 round. The SQLI
5a40: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
5a50: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 IAL property mea
5a60: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 ns that.** infor
5a70: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 mation is writte
5a80: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 n to disk in the
5a90: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 same order as c
5aa0: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 alls.** to xWrit
5ab0: 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 e()..*/.#define
5ac0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5ad0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 MIC 0x0
5ae0: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 0000001.#define
5af0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5b00: 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 MIC512 0x0
5b10: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 0000002.#define
5b20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5b30: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 MIC1K 0x0
5b40: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 0000004.#define
5b50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5b60: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 MIC2K 0x0
5b70: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 0000008.#define
5b80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5b90: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 MIC4K 0x0
5ba0: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 0000010.#define
5bb0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5bc0: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 MIC8K 0x0
5bd0: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 0000020.#define
5be0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5bf0: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 MIC16K 0x0
5c00: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 0000040.#define
5c10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5c20: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 MIC32K 0x0
5c30: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 0000080.#define
5c40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5c50: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 MIC64K 0x0
5c60: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 0000100.#define
5c70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 SQLITE_IOCAP_SAF
5c80: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 E_APPEND 0x0
5c90: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 0000200.#define
5ca0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 SQLITE_IOCAP_SEQ
5cb0: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 UENTIAL 0x0
5cc0: 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 0000400../*.** C
5cd0: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f API3REF: File Lo
5ce0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31 cking Levels {H1
5cf0: 30 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 0250} <H11120> <
5d00: 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 H11310>.**.** SQ
5d10: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 Lite uses one of
5d20: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 these integer v
5d30: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 alues as the sec
5d40: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 ond.** argument
5d50: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 to calls it make
5d60: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 s to the xLock()
5d70: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d and xUnlock() m
5d80: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 ethods.** of an
5d90: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
5da0: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a ods] object..*/.
5db0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
5dc0: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 OCK_NONE
5dd0: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
5de0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 TE_LOCK_SHARED
5df0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
5e00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
5e10: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 RVED 2.#def
5e20: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ine SQLITE_LOCK_
5e30: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a PENDING 3.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
5e50: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 OCK_EXCLUSIVE
5e60: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 4../*.** CAPI3
5e70: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 REF: Synchroniza
5e80: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 tion Type Flags
5e90: 7b 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30 {H10260} <H11120
5ea0: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c >.**.** When SQL
5eb0: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 ite invokes the
5ec0: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f xSync() method o
5ed0: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 f an.** [sqlite3
5ee0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
5ef0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f ect it uses a co
5f00: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 mbination of.**
5f10: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 these integer va
5f20: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f lues as the seco
5f30: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a nd argument..**.
5f40: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 ** When the SQLI
5f50: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
5f60: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 flag is used, i
5f70: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 t means that the
5f80: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 .** sync operati
5f90: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f on only needs to
5fa0: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d flush data to m
5fb0: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e ass storage. In
5fc0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 ode.** informati
5fd0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 on need not be f
5fe0: 6c 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49 lushed. The SQLI
5ff0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66 TE_SYNC_NORMAL f
6000: 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 lag means.** to
6010: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 use normal fsync
6020: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68 () semantics. Th
6030: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 e SQLITE_SYNC_FU
6040: 4c 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a LL flag means.**
6050: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d 58 to use Mac OS-X
6060: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 style fullsync
6070: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 instead of fsync
6080: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ()..*/.#define S
6090: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 QLITE_SYNC_NORMA
60a0: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 L 0x00002
60b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
60c0: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 SYNC_FULL
60d0: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 0x00003.#defi
60e0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 ne SQLITE_SYNC_D
60f0: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 ATAONLY 0x0
6100: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 0010../*.** CAPI
6110: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 3REF: OS Interfa
6120: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e ce Open File Han
6130: 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32 dle {H11110} <S2
6140: 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 0110>.**.** An [
6150: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
6160: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 ject represents
6170: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 an open file in
6180: 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 the OS.** interf
6190: 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 ace layer. Indi
61a0: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 vidual OS interf
61b0: 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ace implementati
61c0: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 ons will.** want
61d0: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 to subclass thi
61e0: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 s object by appe
61f0: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c nding additional
6200: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 fields.** for t
6210: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 heir own use. T
6220: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 he pMethods entr
6230: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 y is a pointer t
6240: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 o an.** [sqlite3
6250: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
6260: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 ect that defines
6270: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 methods for per
6280: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f forming.** I/O o
6290: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 perations on the
62a0: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 open file..*/.t
62b0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
62c0: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 lite3_file sqlit
62d0: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 e3_file;.struct
62e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 sqlite3_file {.
62f0: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 const struct sq
6300: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
6310: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 *pMethods; /*
6320: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f Methods for an o
6330: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a pen file */.};..
6340: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
6350: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c OS Interface Fil
6360: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 e Virtual Method
6370: 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 30 s Object {H11120
6380: 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a } <S20110>.**.**
6390: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e Every file open
63a0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 ed by the [sqlit
63b0: 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 e3_vfs] xOpen me
63c0: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 thod populates a
63d0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 n.** [sqlite3_fi
63e0: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 le] object (or,
63f0: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 more commonly, a
6400: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 subclass of the
6410: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
6420: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 e] object) with
6430: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
6440: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
6450: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 object..** This
6460: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 object defines
6470: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 the methods used
6480: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 to perform vari
6490: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a ous operations.*
64a0: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 * against the op
64b0: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e en file represen
64c0: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 ted by the [sqli
64d0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
64e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
64f0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 s argument to xS
6500: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f ync may be one o
6510: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e f [SQLITE_SYNC_N
6520: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 ORMAL] or.** [SQ
6530: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e LITE_SYNC_FULL].
6540: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 The first choi
6550: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c ce is the normal
6560: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 fsync()..** The
6570: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 second choice i
6580: 73 20 61 20 4d 61 63 20 4f 53 2d 58 20 73 74 79 s a Mac OS-X sty
6590: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 le fullsync. Th
65a0: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 e [SQLITE_SYNC_D
65b0: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 ATAONLY].** flag
65c0: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 may be ORed in
65d0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 to indicate that
65e0: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f only the data o
65f0: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e f the file.** an
6600: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 d not its inode
6610: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 needs to be sync
6620: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e ed..**.** The in
6630: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 teger values to
6640: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c xLock() and xUnl
6650: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 ock() are one of
6660: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
6670: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f [SQLITE_LOCK_NO
6680: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 NE],.** <li> [SQ
6690: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
66a0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
66b0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 TE_LOCK_RESERVED
66c0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
66d0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d TE_LOCK_PENDING]
66e0: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 , or.** <li> [SQ
66f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 LITE_LOCK_EXCLUS
6700: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a IVE]..** </ul>.*
6710: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 * xLock() increa
6720: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 ses the lock. xU
6730: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 nlock() decrease
6740: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 s the lock..** T
6750: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 he xCheckReserve
6760: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 dLock() method c
6770: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e hecks whether an
6780: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 y database conne
6790: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 ction,.** either
67a0: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 in this process
67b0: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 or in some othe
67c0: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f r process, is ho
67d0: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 lding a RESERVED
67e0: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 ,.** PENDING, or
67f0: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 EXCLUSIVE lock
6800: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 on the file. It
6810: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a returns true.**
6820: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 if such a lock
6830: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 exists and false
6840: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a otherwise..**.*
6850: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 * The xFileContr
6860: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 ol() method is a
6870: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 generic interfa
6880: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 ce that allows c
6890: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 ustom.** VFS imp
68a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 lementations to
68b0: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c directly control
68c0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 an open file us
68d0: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 ing the.** [sqli
68e0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
68f0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ()] interface.
6900: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 The second "op"
6910: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a argument is an.*
6920: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 * integer opcode
6930: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 . The third arg
6940: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 ument is a gener
6950: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e ic pointer inten
6960: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 ded to.** point
6970: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 to a structure t
6980: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 hat may contain
6990: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 arguments or spa
69a0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a ce in which to.*
69b0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 * write return v
69c0: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 alues. Potentia
69d0: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 l uses for xFile
69e0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 Control() might
69f0: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 be.** functions
6a00: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 to enable blocki
6a10: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 ng locks with ti
6a20: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 meouts, to chang
6a30: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 e the.** locking
6a40: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 strategy (for e
6a50: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f xample to use do
6a60: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 t-file locks), t
6a70: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f o inquire.** abo
6a80: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 ut the status of
6a90: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 a lock, or to b
6aa0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 reak stale locks
6ab0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a . The SQLite.**
6ac0: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 core reserves a
6ad0: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 ll opcodes less
6ae0: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 than 100 for its
6af0: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b own use..** A [
6b00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 SQLITE_FCNTL_LOC
6b10: 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 KSTATE | list of
6b20: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 opcodes] less t
6b30: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c han 100 is avail
6b40: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 able..** Applica
6b50: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e tions that defin
6b60: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 e a custom xFile
6b70: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 Control method s
6b80: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 hould use opcode
6b90: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 s.** greater tha
6ba0: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 n 100 to avoid c
6bb0: 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 onflicts..**.**
6bc0: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 The xSectorSize(
6bd0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 ) method returns
6be0: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 the sector size
6bf0: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 of the.** devic
6c00: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 e that underlies
6c10: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 the file. The
6c20: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 sector size is t
6c30: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 he.** minimum wr
6c40: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 ite that can be
6c50: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 performed withou
6c60: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 t disturbing.**
6c70: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 other bytes in t
6c80: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 he file. The xD
6c90: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 eviceCharacteris
6ca0: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 tics().** method
6cb0: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 returns a bit v
6cc0: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 ector describing
6cd0: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 behaviors of th
6ce0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 e.** underlying
6cf0: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 device:.**.** <u
6d00: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 l>.** <li> [SQLI
6d10: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d TE_IOCAP_ATOMIC]
6d20: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
6d30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 _IOCAP_ATOMIC512
6d40: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
6d50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b E_IOCAP_ATOMIC1K
6d60: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
6d70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b E_IOCAP_ATOMIC2K
6d80: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
6d90: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b E_IOCAP_ATOMIC4K
6da0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
6db0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b E_IOCAP_ATOMIC8K
6dc0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
6dd0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 E_IOCAP_ATOMIC16
6de0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
6df0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 TE_IOCAP_ATOMIC3
6e00: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 2K].** <li> [SQL
6e10: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
6e20: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 64K].** <li> [SQ
6e30: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
6e40: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 APPEND].** <li>
6e50: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 [SQLITE_IOCAP_SE
6e60: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 QUENTIAL].** </u
6e70: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c l>.**.** The SQL
6e80: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
6e90: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 property means
6ea0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 that all writes
6eb0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 of.** any size a
6ec0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 re atomic. The
6ed0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6ee0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a MICnnn values.**
6ef0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 mean that write
6f00: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 s of blocks that
6f10: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 are nnn bytes i
6f20: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 n size and.** ar
6f30: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
6f40: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 address which is
6f50: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 an integer mult
6f60: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 iple of.** nnn a
6f70: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 re atomic. The
6f80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 SQLITE_IOCAP_SAF
6f90: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d E_APPEND value m
6fa0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 eans.** that whe
6fb0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 n data is append
6fc0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 ed to a file, th
6fd0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 e data is append
6fe0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e ed.** first then
6ff0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
7000: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 file is extende
7010: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 d, never the oth
7020: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 er.** way around
7030: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
7040: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 CAP_SEQUENTIAL p
7050: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
7060: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f at.** informatio
7070: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 n is written to
7080: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 disk in the same
7090: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a order as calls.
70a0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a ** to xWrite()..
70b0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
70c0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 t sqlite3_io_met
70d0: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f hods sqlite3_io_
70e0: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 methods;.struct
70f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
7100: 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 ds {. int iVers
7110: 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c ion;. int (*xCl
7120: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ose)(sqlite3_fil
7130: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 e*);. int (*xRe
7140: 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ad)(sqlite3_file
7150: 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 *, void*, int iA
7160: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 mt, sqlite3_int6
7170: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 4 iOfst);. int
7180: 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 (*xWrite)(sqlite
7190: 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 3_file*, const v
71a0: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 oid*, int iAmt,
71b0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f sqlite3_int64 iO
71c0: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 fst);. int (*xT
71d0: 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 runcate)(sqlite3
71e0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f _file*, sqlite3_
71f0: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 int64 size);. i
7200: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 nt (*xSync)(sqli
7210: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 te3_file*, int f
7220: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 lags);. int (*x
7230: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 FileSize)(sqlite
7240: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 3_file*, sqlite3
7250: 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a _int64 *pSize);.
7260: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 int (*xLock)(s
7270: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
7280: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c t);. int (*xUnl
7290: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ock)(sqlite3_fil
72a0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 e*, int);. int
72b0: 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 (*xCheckReserved
72c0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 Lock)(sqlite3_fi
72d0: 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 le*, int *pResOu
72e0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c t);. int (*xFil
72f0: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 eControl)(sqlite
7300: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 3_file*, int op,
7310: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 void *pArg);.
7320: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a int (*xSectorSiz
7330: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
7340: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 );. int (*xDevi
7350: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 ceCharacteristic
7360: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a s)(sqlite3_file*
7370: 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e );. /* Addition
7380: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 al methods may b
7390: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
73a0: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b e releases */.};
73b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
73c0: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 : Standard File
73d0: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20 Control Opcodes
73e0: 7b 48 31 31 33 31 30 7d 20 3c 53 33 30 38 30 30 {H11310} <S30800
73f0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e >.**.** These in
7400: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 teger constants
7410: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 are opcodes for
7420: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
7430: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 method.** of th
7440: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
7450: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e thods] object an
7460: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 d for the [sqlit
7470: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
7480: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e )].** interface.
7490: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
74a0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
74b0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 TE] opcode is us
74c0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 ed for debugging
74d0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 . This.** opcod
74e0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 e causes the xFi
74f0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
7500: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 to write the cu
7510: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a rrent state of.*
7520: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 * the lock (one
7530: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f of [SQLITE_LOCK_
7540: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c NONE], [SQLITE_L
7550: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 OCK_SHARED],.**
7560: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 [SQLITE_LOCK_RES
7570: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f ERVED], [SQLITE_
7580: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f LOCK_PENDING], o
7590: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 r [SQLITE_LOCK_E
75a0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e XCLUSIVE]).** in
75b0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 to an integer th
75c0: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 at the pArg argu
75d0: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 ment points to.
75e0: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a This capability.
75f0: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e ** is used durin
7600: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e g testing and on
7610: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 ly needs to be s
7620: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 upported when SQ
7630: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 LITE_TEST.** is
7640: 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 defined..*/.#def
7650: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
7660: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 _LOCKSTATE
7670: 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 1../*.** CAPI3
7680: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c REF: Mutex Handl
7690: 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30 31 e {H17110} <S201
76a0: 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 30>.**.** The mu
76b0: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 tex module withi
76c0: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 n SQLite defines
76d0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d [sqlite3_mutex]
76e0: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 to be an.** abs
76f0: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 tract type for a
7700: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 mutex object.
7710: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
7720: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 never looks.** a
7730: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 t the internal r
7740: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 epresentation of
7750: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 an [sqlite3_mut
7760: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a ex]. It only.**
7770: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e deals with poin
7780: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c ters to the [sql
7790: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 ite3_mutex] obje
77a0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 ct..**.** Mutexe
77b0: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 s are created us
77c0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
77d0: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a ex_alloc()]..*/.
77e0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
77f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c qlite3_mutex sql
7800: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a ite3_mutex;../*.
7810: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 ** CAPI3REF: OS
7820: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 Interface Object
7830: 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31 30 {H11140} <S2010
7840: 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 0>.**.** An inst
7850: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 ance of the sqli
7860: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 te3_vfs object d
7870: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 efines the inter
7880: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 face between.**
7890: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 the SQLite core
78a0: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 and the underlyi
78b0: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 ng operating sys
78c0: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a tem. The "vfs".
78d0: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f ** in the name o
78e0: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 f the object sta
78f0: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c nds for "virtual
7900: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a file system"..*
7910: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f *.** The value o
7920: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 f the iVersion f
7930: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c ield is initiall
7940: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c y 1 but may be l
7950: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 arger in.** futu
7960: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
7970: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e QLite. Addition
7980: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 al fields may be
7990: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 appended to thi
79a0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e s.** object when
79b0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 the iVersion va
79c0: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 lue is increased
79d0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 . Note that the
79e0: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 structure.** of
79f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
7a00: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 object changes
7a10: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 in the transacti
7a20: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 on between.** SQ
7a30: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
7a40: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 .9 and 3.6.0 and
7a50: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f yet the iVersio
7a60: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a n field was not.
7a70: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a ** modified..**.
7a80: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 ** The szOsFile
7a90: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a field is the siz
7aa0: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 e of the subclas
7ab0: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c sed [sqlite3_fil
7ac0: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 e].** structure
7ad0: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 used by this VFS
7ae0: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 . mxPathname is
7af0: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e the maximum len
7b00: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 gth of.** a path
7b10: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 name in this VFS
7b20: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 ..**.** Register
7b30: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f ed sqlite3_vfs o
7b40: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 bjects are kept
7b50: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 on a linked list
7b60: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 formed by.** th
7b70: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
7b80: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 The [sqlite3_v
7b90: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a fs_register()].*
7ba0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 * and [sqlite3_v
7bb0: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d fs_unregister()]
7bc0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 interfaces mana
7bd0: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 ge this list.**
7be0: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 in a thread-safe
7bf0: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 way. The [sqli
7c00: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 te3_vfs_find()]
7c10: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 interface.** sea
7c20: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 rches the list.
7c30: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 Neither the app
7c40: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f lication code no
7c50: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 r the VFS.** imp
7c60: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 lementation shou
7c70: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 ld use the pNext
7c80: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
7c90: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 The pNext field
7ca0: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c is the only fiel
7cb0: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 d in the sqlite3
7cc0: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 _vfs.** structur
7cd0: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 e that SQLite wi
7ce0: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 ll ever modify.
7cf0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c SQLite will onl
7d00: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d y access.** or m
7d10: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 odify this field
7d20: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 while holding a
7d30: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 particular stat
7d40: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 ic mutex..** The
7d50: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
7d60: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 uld never modify
7d70: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e anything within
7d80: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
7d90: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 .** object once
7da0: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 the object has b
7db0: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a een registered..
7dc0: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 **.** The zName
7dd0: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 field holds the
7de0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 name of the VFS
7df0: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d module. The nam
7e00: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 e must.** be uni
7e10: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 que across all V
7e20: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a FS modules..**.*
7e30: 2a 20 7b 48 31 31 31 34 31 7d 20 53 51 4c 69 74 * {H11141} SQLit
7e40: 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 e will guarantee
7e50: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e that the zFilen
7e60: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f ame parameter to
7e70: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 xOpen.** is eit
7e80: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 her a NULL point
7e90: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 er or string obt
7ea0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 ained.** from xF
7eb0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20 ullPathname().
7ec0: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 SQLite further g
7ed0: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a uarantees that.*
7ee0: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c * the string wil
7ef0: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 l be valid and u
7f00: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 nchanged until x
7f10: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 Close() is.** ca
7f20: 6c 6c 65 64 2e 20 7b 45 4e 44 7d 20 20 42 65 63 lled. {END} Bec
7f30: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 ause of the prev
7f40: 69 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a 2a ious sentense,.*
7f50: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 * the [sqlite3_f
7f60: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 ile] can safely
7f70: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 store a pointer
7f80: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 to the.** filena
7f90: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 me if it needs t
7fa0: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 o remember the f
7fb0: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 ilename for some
7fc0: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 reason..** If t
7fd0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 he zFilename par
7fe0: 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20 ameter is xOpen
7ff0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
8000: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 r then xOpen.**
8010: 6d 75 73 74 20 69 6e 76 69 74 65 20 69 74 73 20 must invite its
8020: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 own temporary na
8030: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e me for the file.
8040: 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a Whenever the .
8050: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 ** xFilename par
8060: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 ameter is NULL i
8070: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 t will also be t
8080: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 he case that the
8090: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 .** flags parame
80a0: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 ter will include
80b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
80c0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a LETEONCLOSE]..**
80d0: 0a 2a 2a 20 7b 48 31 31 31 34 32 7d 20 54 68 65 .** {H11142} The
80e0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
80f0: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 to xOpen() inclu
8100: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 des all bits set
8110: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 in.** the flags
8120: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 argument to [sq
8130: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
8140: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 . Or if [sqlite
8150: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 3_open()].** or
8160: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
8170: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e )] is used, then
8180: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 flags includes
8190: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c at least.** [SQL
81a0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
81b0: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 TE] | [SQLITE_OP
81c0: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 7b 45 4e 44 EN_CREATE]. {END
81d0: 7d 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 }.** If xOpen()
81e0: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 opens a file rea
81f0: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 d-only then it s
8200: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 ets *pOutFlags t
8210: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 o.** include [SQ
8220: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
8230: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 LY]. Other bits
8240: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d in *pOutFlags m
8250: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a ay be set..**.**
8260: 20 7b 48 31 31 31 34 33 7d 20 53 51 4c 69 74 65 {H11143} SQLite
8270: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f will also add o
8280: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
8290: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 ing flags to the
82a0: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c xOpen().** call
82b0: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 , depending on t
82c0: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 he object being
82d0: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 opened:.**.** <u
82e0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c l>.** <li> [SQL
82f0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
8300: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
8310: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 TE_OPEN_MAIN_JOU
8320: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
8330: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
8340: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
8350: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
8360: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
8370: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 [SQLITE_OPEN_T
8380: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 RANSIENT_DB].**
8390: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
83a0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a EN_SUBJOURNAL].*
83b0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
83c0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
83d0: 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 NAL].** </ul> {E
83e0: 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 ND}.**.** The fi
83f0: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 le I/O implement
8400: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 ation can use th
8410: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c e object type fl
8420: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 ags to.** change
8430: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c the way it deal
8440: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 s with files. F
8450: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 or example, an a
8460: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 pplication.** th
8470: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 at does not care
8480: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 about crash rec
8490: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 overy or rollbac
84a0: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 k might make.**
84b0: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f the open of a jo
84c0: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d urnal file a no-
84d0: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 op. Writes to t
84e0: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c his journal woul
84f0: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d d.** also be no-
8500: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 ops, and any att
8510: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 empt to read the
8520: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 journal would r
8530: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f eturn.** SQLITE_
8540: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 IOERR. Or the i
8550: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 mplementation mi
8560: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 ght recognize th
8570: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a at a database.**
8580: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f file will be do
8590: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 ing page-aligned
85a0: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e sector reads an
85b0: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 d writes in a ra
85c0: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e ndom.** order an
85d0: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f d set up its I/O
85e0: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 subsystem accor
85f0: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 dingly..**.** SQ
8600: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 Lite might also
8610: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 add one of the f
8620: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 ollowing flags t
8630: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 o the xOpen meth
8640: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a od:.**.** <ul>.*
8650: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f * <li> [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 3c 6c 69 3e 20 5b 53 51 4c 49 E].** <li> [SQLI
8680: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 TE_OPEN_EXCLUSIV
8690: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a E].** </ul>.**.*
86a0: 2a 20 7b 48 31 31 31 34 35 7d 20 54 68 65 20 5b * {H11145} The [
86b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
86c0: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 TEONCLOSE] flag
86d0: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 means the file s
86e0: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 hould be.** dele
86f0: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 ted when it is c
8700: 6c 6f 73 65 64 2e 20 20 7b 48 31 31 31 34 36 7d losed. {H11146}
8710: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 The [SQLITE_OPE
8720: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
8730: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 .** will be set
8740: 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61 for TEMP databa
8750: 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e ses, journals an
8760: 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c d for subjournal
8770: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 37 s..**.** {H11147
8780: 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 } The [SQLITE_OP
8790: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c EN_EXCLUSIVE] fl
87a0: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c ag means the fil
87b0: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e e should be open
87c0: 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 ed.** for exclus
87d0: 69 76 65 20 61 63 63 65 73 73 2e 20 20 54 68 69 ive access. Thi
87e0: 73 20 66 6c 61 67 20 69 73 20 73 65 74 20 66 6f s flag is set fo
87f0: 72 20 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 65 r all files exce
8800: 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61 pt.** for the ma
8810: 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 in database file
8820: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 38 7d ..**.** {H11148}
8830: 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 At least szOsFi
8840: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f le bytes of memo
8850: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 ry are allocated
8860: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f by SQLite.** to
8870: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 hold the [sqli
8880: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 te3_file] struct
8890: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 ure passed as th
88a0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d e third.** argum
88b0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 7b 45 ent to xOpen. {E
88c0: 4e 44 7d 20 20 54 68 65 20 78 4f 70 65 6e 20 6d ND} The xOpen m
88d0: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 ethod does not h
88e0: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 ave to.** alloca
88f0: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 te the structure
8900: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 ; it should just
8910: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 0a fill it in..**.
8920: 2a 2a 20 7b 48 31 31 31 34 39 7d 20 54 68 65 20 ** {H11149} The
8930: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 flags argument t
8940: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 o xAccess() may
8950: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 be [SQLITE_ACCES
8960: 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 S_EXISTS].** to
8970: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 test for the exi
8980: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 stence of a file
8990: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 , or [SQLITE_ACC
89a0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 ESS_READWRITE] t
89b0: 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 o.** test whethe
89c0: 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 r a file is read
89d0: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c able and writabl
89e0: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 e, or [SQLITE_AC
89f0: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f CESS_READ].** to
8a00: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 test whether a
8a10: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 file is at least
8a20: 20 72 65 61 64 61 62 6c 65 2e 20 7b 45 4e 44 7d readable. {END}
8a30: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 The file can b
8a40: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 e a.** directory
8a50: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 35 30 7d ..**.** {H11150}
8a60: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 SQLite will alw
8a70: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 ays allocate at
8a80: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 least mxPathname
8a90: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 +1 bytes for the
8aa0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 .** output buffe
8ab0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e r xFullPathname.
8ac0: 20 7b 48 31 31 31 35 31 7d 20 54 68 65 20 65 78 {H11151} The ex
8ad0: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 act size of the
8ae0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a output buffer.**
8af0: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 is also passed
8b00: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 as a parameter t
8b10: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e o both methods.
8b20: 20 7b 45 4e 44 7d 20 20 49 66 20 74 68 65 20 6f {END} If the o
8b30: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 utput buffer.**
8b40: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f is not large eno
8b50: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e ugh, [SQLITE_CAN
8b60: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 TOPEN] should be
8b70: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 returned. Since
8b80: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 this is.** hand
8b90: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 led as a fatal e
8ba0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 rror by SQLite,
8bb0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 vfs implementati
8bc0: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 ons should endea
8bd0: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e vor.** to preven
8be0: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e t this by settin
8bf0: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 g mxPathname to
8c00: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c a sufficiently l
8c10: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a arge value..**.*
8c20: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 * The xRandomnes
8c30: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61 s(), xSleep(), a
8c40: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 nd xCurrentTime(
8c50: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ) interfaces.**
8c60: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 are not strictly
8c70: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 a part of the f
8c80: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 ilesystem, but t
8c90: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 hey are.** inclu
8ca0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 ded in the VFS s
8cb0: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d tructure for com
8cc0: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 pleteness..** Th
8cd0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 e xRandomness()
8ce0: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 function attempt
8cf0: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 s to return nByt
8d00: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 es bytes.** of g
8d10: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 ood-quality rand
8d20: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 omness into zOut
8d30: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 . The return va
8d40: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 lue is.** the ac
8d50: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 tual number of b
8d60: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 ytes of randomne
8d70: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 ss obtained..**
8d80: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 The xSleep() met
8d90: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 hod causes the c
8da0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f alling thread to
8db0: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a sleep for at.**
8dc0: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 least the numbe
8dd0: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 r of microsecond
8de0: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43 s given. The xC
8df0: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 urrentTime().**
8e00: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 method returns a
8e10: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 Julian Day Numb
8e20: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 er for the curre
8e30: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 nt date and time
8e40: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
8e50: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 uct sqlite3_vfs
8e60: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 sqlite3_vfs;.str
8e70: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 uct sqlite3_vfs
8e80: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e {. int iVersion
8e90: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ; /*
8ea0: 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f Structure versio
8eb0: 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e n number */. in
8ec0: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 t szOsFile;
8ed0: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f /* Size o
8ee0: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c f subclassed sql
8ef0: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 ite3_file */. i
8f00: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 nt mxPathname;
8f10: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
8f20: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 um file pathname
8f30: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c length */. sql
8f40: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b ite3_vfs *pNext;
8f50: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 /* Next re
8f60: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a gistered VFS */.
8f70: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
8f80: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 ame; /* Na
8f90: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 me of this virtu
8fa0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a al file system *
8fb0: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 /. void *pAppDa
8fc0: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ta; /*
8fd0: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 Pointer to appli
8fe0: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 cation-specific
8ff0: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a data */. int (*
9000: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 xOpen)(sqlite3_v
9010: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
9020: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f *zName, sqlite3_
9030: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 file*,.
9040: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c int flags,
9050: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 int *pOutFlags)
9060: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 ;. int (*xDelet
9070: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
9080: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
9090: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 me, int syncDir)
90a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 ;. int (*xAcces
90b0: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c s)(sqlite3_vfs*,
90c0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
90d0: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 me, int flags, i
90e0: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 nt *pResOut);.
90f0: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e int (*xFullPathn
9100: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ame)(sqlite3_vfs
9110: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
9120: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 Name, int nOut,
9130: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 char *zOut);. v
9140: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 oid *(*xDlOpen)(
9150: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
9160: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e nst char *zFilen
9170: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 ame);. void (*x
9180: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 DlError)(sqlite3
9190: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 _vfs*, int nByte
91a0: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 , char *zErrMsg)
91b0: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53 ;. void *(*xDlS
91c0: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ym)(sqlite3_vfs*
91d0: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 ,void*, const ch
91e0: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 ar *zSymbol);.
91f0: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 void (*xDlClose)
9200: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 (sqlite3_vfs*, v
9210: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 oid*);. int (*x
9220: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 Randomness)(sqli
9230: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 te3_vfs*, int nB
9240: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 yte, char *zOut)
9250: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 ;. int (*xSleep
9260: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
9270: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 int microseconds
9280: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 );. int (*xCurr
9290: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 entTime)(sqlite3
92a0: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b _vfs*, double*);
92b0: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 . int (*xGetLas
92c0: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f tError)(sqlite3_
92d0: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 vfs*, int, char
92e0: 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 *);. /* New fie
92f0: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e lds may be appen
9300: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 ded in figure ve
9310: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 rsions. The iVe
9320: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 rsion. ** value
9330: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 will increment
9340: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 whenever this ha
9350: 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a ppens. */.};../*
9360: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c .** CAPI3REF: Fl
9370: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 ags for the xAcc
9380: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b ess VFS method {
9390: 48 31 31 31 39 30 7d 20 3c 48 31 31 31 34 30 3e H11190} <H11140>
93a0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 39 31 7d 20 .**.** {H11191}
93b0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f These integer co
93c0: 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 nstants can be u
93d0: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 sed as the third
93e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
93f0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
9400: 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 hod of an [sqlit
9410: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 e3_vfs] object.
9420: 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 65 74 65 {END} They dete
9430: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 rmine.** what ki
9440: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e nd of permission
9450: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 s the xAccess me
9460: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 thod is looking
9470: 66 6f 72 2e 0a 2a 2a 20 7b 48 31 31 31 39 32 7d for..** {H11192}
9480: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 With SQLITE_ACC
9490: 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 ESS_EXISTS, the
94a0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a xAccess method.*
94b0: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 * simply checks
94c0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 whether the file
94d0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 7b 48 31 31 exists..** {H11
94e0: 31 39 33 7d 20 57 69 74 68 20 53 51 4c 49 54 45 193} With SQLITE
94f0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
9500: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d E, the xAccess m
9510: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 ethod.** checks
9520: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 whether the file
9530: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c is both readabl
9540: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a e and writable..
9550: 2a 2a 20 7b 48 31 31 31 39 34 7d 20 57 69 74 68 ** {H11194} With
9560: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
9570: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 EAD, the xAccess
9580: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b method.** check
9590: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 s whether the fi
95a0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a le is readable..
95b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
95c0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 E_ACCESS_EXISTS
95d0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0.#define SQL
95e0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
95f0: 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 RITE 1.#define S
9600: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
9610: 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 D 2../*.**
9620: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 CAPI3REF: Initia
9630: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 lize The SQLite
9640: 4c 69 62 72 61 72 79 20 7b 48 31 30 31 33 30 7d Library {H10130}
9650: 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 31 30 30 <S20000><S30100
9660: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
9670: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
9680: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c routine initial
9690: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 izes the.** SQLi
96a0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 te library. The
96b0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
96c0: 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 n() routine.** d
96d0: 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 eallocates any r
96e0: 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 esources that we
96f0: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 re allocated by
9700: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9710: 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 ze()..**.** A ca
9720: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e ll to sqlite3_in
9730: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e itialize() is an
9740: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c "effective" cal
9750: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 l if it is.** th
9760: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c e first time sql
9770: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
9780: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 ) is invoked dur
9790: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 ing the lifetime
97a0: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 of.** the proce
97b0: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 ss, or if it is
97c0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 the first time s
97d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
97e0: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a e() is invoked.*
97f0: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 * following a ca
9800: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
9810: 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20 utdown(). Only
9820: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c an effective cal
9830: 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f l.** of sqlite3_
9840: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 initialize() doe
9850: 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 s any initializa
9860: 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 tion. All other
9870: 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 calls.** are ha
9880: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a rmless no-ops..*
9890: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 *.** Among other
98a0: 20 74 68 69 6e 67 73 2c 20 73 71 6c 69 74 65 33 things, sqlite3
98b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 68 _initialize() sh
98c0: 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 all invoke.** sq
98d0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e lite3_os_init().
98e0: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 73 71 6c Similarly, sql
98f0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a ite3_shutdown().
9900: 2a 2a 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 20 ** shall invoke
9910: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
9920: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
9930: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
9940: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
9950: 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 SQLITE_OK on su
9960: 63 63 65 73 73 2e 0a 2a 2a 20 49 66 20 66 6f 72 ccess..** If for
9970: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 some reason, sq
9980: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
9990: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 () is unable to
99a0: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 initialize.** th
99b0: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 e library (perha
99c0: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 ps it is unable
99d0: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 to allocate a ne
99e0: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 eded resource su
99f0: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 ch.** as a mutex
9a00: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 ) it returns an
9a10: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 [error code] oth
9a20: 65 72 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4f er than SQLITE_O
9a30: 4b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c K..**.** The sql
9a40: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
9a50: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c ) routine is cal
9a60: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 led internally b
9a70: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 y many other.**
9a80: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
9a90: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 s so that an app
9aa0: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 lication usually
9ab0: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
9ac0: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 o.** invoke sqli
9ad0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
9ae0: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 directly. For
9af0: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 example, [sqlite
9b00: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 3_open()].** cal
9b10: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ls sqlite3_initi
9b20: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 alize() so the S
9b30: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 QLite library wi
9b40: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 ll be automatica
9b50: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a lly.** initializ
9b60: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 ed when [sqlite3
9b70: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c _open()] is call
9b80: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 ed if it has not
9b90: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a be initialized.
9ba0: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77 ** already. How
9bb0: 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 ever, if SQLite
9bc0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
9bd0: 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 the SQLITE_OMIT
9be0: 5f 41 55 54 4f 49 4e 49 54 0a 2a 2a 20 63 6f 6d _AUTOINIT.** com
9bf0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
9c00: 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d , then the autom
9c10: 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 atic calls to sq
9c20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
9c30: 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 ().** are omitte
9c40: 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 d and the applic
9c50: 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 ation must call
9c60: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9c70: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a ze() directly.**
9c80: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 prior to using
9c90: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 any other SQLite
9ca0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 interface. For
9cb0: 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 maximum portabi
9cc0: 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 lity,.** it is r
9cd0: 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
9ce0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 applications alw
9cf0: 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 ays invoke sqlit
9d00: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a e3_initialize().
9d10: 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f ** directly prio
9d20: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f r to using any o
9d30: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 ther SQLite inte
9d40: 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 rface. Future r
9d50: 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 eleases.** of SQ
9d60: 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 Lite may require
9d70: 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 this. In other
9d80: 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 words, the beha
9d90: 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a vior exhibited.*
9da0: 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 * when SQLite is
9db0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 53 compiled with S
9dc0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 QLITE_OMIT_AUTOI
9dd0: 4e 49 54 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 NIT might become
9de0: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 the.** default
9df0: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 behavior in some
9e00: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 future release
9e10: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
9e20: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f The sqlite3_os_
9e30: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 init() routine d
9e40: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 oes operating-sy
9e50: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a stem specific.**
9e60: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
9e70: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 of the SQLite li
9e80: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 brary. The sqli
9e90: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
9ea0: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 routine undoes t
9eb0: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c he effect of sql
9ec0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 ite3_os_init().
9ed0: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a Typical tasks.*
9ee0: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 * performed by t
9ef0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e hese routines in
9f00: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e clude allocation
9f10: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e or deallocation
9f20: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 .** of static re
9f30: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c sources, initial
9f40: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 ization of globa
9f50: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 l variables,.**
9f60: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 setting up a def
9f70: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
9f80: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 s] module, or se
9f90: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 tting up.** a de
9fa0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 fault configurat
9fb0: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ion using [sqlit
9fc0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a e3_config()]..**
9fd0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
9fe0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
9ff0: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 invoke either s
a000: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
a010: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f .** or sqlite3_o
a020: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 s_end() directly
a030: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 . The applicati
a040: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 on should only i
a050: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 nvoke.** sqlite3
a060: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e _initialize() an
a070: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f d sqlite3_shutdo
a080: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 wn(). The sqlit
a090: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 e3_os_init().**
a0a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c interface is cal
a0b0: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c led automaticall
a0c0: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 y by sqlite3_ini
a0d0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a tialize() and.**
a0e0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
a0f0: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 ) is called by s
a100: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
a110: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a ). Appropriate.
a120: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
a130: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f ns for sqlite3_o
a140: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c s_init() and sql
a150: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
a160: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 are built into
a170: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 SQLite when it i
a180: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75 s compiled for u
a190: 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72 nix, windows, or
a1a0: 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62 os/2..** When b
a1b0: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 uilt for other p
a1c0: 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e 67 20 latforms (using
a1d0: 74 68 65 20 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 the SQLITE_OS_OT
a1e0: 48 45 52 3d 31 20 63 6f 6d 70 69 6c 65 2d 74 69 HER=1 compile-ti
a1f0: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 me.** option) th
a200: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
a210: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 st supply a suit
a220: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 able implementat
a230: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 ion for.** sqlit
a240: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 e3_os_init() and
a250: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
a260: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 ). An applicati
a270: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 on-supplied.** i
a280: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
a290: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
a2a0: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 () or sqlite3_os
a2b0: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 _end().** must r
a2c0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 eturn SQLITE_OK
a2d0: 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 on success and s
a2e0: 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 ome other [error
a2f0: 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 code] upon.** f
a300: 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 ailure..*/.int s
a310: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
a320: 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c e(void);.int sql
a330: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f ite3_shutdown(vo
a340: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 id);.int sqlite3
a350: 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a _os_init(void);.
a360: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 int sqlite3_os_e
a370: 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a nd(void);../*.**
a380: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 CAPI3REF: Confi
a390: 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 guring The SQLit
a3a0: 65 20 4c 69 62 72 61 72 79 20 7b 48 31 30 31 34 e Library {H1014
a3b0: 35 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 32 5} <S20000><S302
a3c0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 00>.**.** The sq
a3d0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
a3e0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
a3f0: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 to make global
a400: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a configuration.**
a410: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 changes to SQLi
a420: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 te in order to t
a430: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 une SQLite to th
a440: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 e specific needs
a450: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 of.** the appli
a460: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 cation. The def
a470: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 ault configurati
a480: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 on is recommende
a490: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 d for most.** ap
a4a0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 plications and s
a4b0: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 o this routine i
a4c0: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 s usually not ne
a4d0: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a cessary. It is.
a4e0: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 ** provided to s
a4f0: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c upport rare appl
a500: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e ications with un
a510: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a usual needs..**.
a520: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
a530: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
a540: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 e is not threads
a550: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 afe. The applic
a560: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e ation.** must in
a570: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 sure that no oth
a580: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
a590: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 aces are invoked
a5a0: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 by other.** thr
a5b0: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 eads while sqlit
a5c0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 e3_config() is r
a5d0: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 unning. Further
a5e0: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f more, sqlite3_co
a5f0: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e nfig().** may on
a600: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 ly be invoked pr
a610: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 ior to library i
a620: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 nitialization us
a630: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
a640: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 initialize()] or
a650: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 after shutdown
a660: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 by [sqlite3_shut
a670: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65 down()]..** Note
a680: 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 , however, that
a690: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
a6a0: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 can be called a
a6b0: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a s part of the.**
a6c0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
a6d0: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f of an applicatio
a6e0: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 n-defined [sqlit
a6f0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a e3_os_init()]..*
a700: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
a710: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
a720: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 e3_config() is a
a730: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 n integer.** [SQ
a740: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
a750: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 LETHREAD | confi
a760: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d guration option]
a770: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 that determines
a780: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 .** what propert
a790: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 y of SQLite is t
a7a0: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e o be configured.
a7b0: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 Subsequent arg
a7c0: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 uments.** vary d
a7d0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
a7e0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
a7f0: 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f INGLETHREAD | co
a800: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
a810: 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 on].** in the fi
a820: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a rst argument..**
a830: 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e 66 69 .** When a confi
a840: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
a850: 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f is set, sqlite3_
a860: 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 config() returns
a870: 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 SQLITE_OK..** I
a880: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 f the option is
a890: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 unknown or SQLit
a8a0: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 e is unable to s
a8b0: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a et the option.**
a8c0: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 then this routi
a8d0: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e ne returns a non
a8e0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 -zero [error cod
a8f0: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 e]..**.** The sq
a900: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
a910: 6e 74 65 72 66 61 63 65 20 69 73 20 63 6f 6e 73 nterface is cons
a920: 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e idered experimen
a930: 74 61 6c 20 69 6e 20 74 68 61 74 0a 2a 2a 20 6e tal in that.** n
a940: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ew configuration
a950: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 options may be
a960: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
a970: 72 65 6c 65 61 73 65 73 20 61 6e 64 20 65 78 69 releases and exi
a980: 73 74 69 6e 67 0a 2a 2a 20 63 6f 6e 66 69 67 75 sting.** configu
a990: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
a9a0: 61 79 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 ay be discontinu
a9b0: 65 64 20 6f 72 20 6d 6f 64 69 66 69 65 64 2e 0a ed or modified..
a9c0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
a9d0: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b onfig(int, ...);
a9e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
a9f0: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 : Configure data
aa00: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
aa10: 20 20 7b 48 31 30 31 38 30 7d 20 3c 53 32 30 30 {H10180} <S200
aa20: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 00>.**.** The sq
aa30: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
aa40: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 ) interface is u
aa50: 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 sed to make conf
aa60: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 iguration.** cha
aa70: 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 nges to a [datab
aa80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
aa90: 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 The interface
aaa0: 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a is similar to.**
aab0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
aac0: 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 ()] except that
aad0: 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c the changes appl
aae0: 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a y to a single.**
aaf0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
ab00: 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 ction] (specifie
ab10: 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 d in the first a
ab20: 72 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a rgument). The.*
ab30: 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e * sqlite3_db_con
ab40: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
ab50: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 can only be used
ab60: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 immediately aft
ab70: 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 er.** the databa
ab80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
ab90: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b created using [
aba0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
abb0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 .** [sqlite3_ope
abc0: 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 n16()], or [sqli
abd0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 te3_open_v2()].
abe0: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f .**.** The seco
abf0: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 nd argument to s
ac00: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
ac10: 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 (D,V,...) is th
ac20: 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 e.** configurati
ac30: 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 on verb - an int
ac40: 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 69 eger code that i
ac50: 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a ndicates what.**
ac60: 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b aspect of the [
ac70: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
ac80: 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f ion] is being co
ac90: 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 43 68 6f nfigured..** Cho
aca0: 69 63 65 73 20 66 6f 72 20 74 68 69 73 20 76 61 ices for this va
acb0: 6c 75 65 20 61 72 65 20 5b 53 51 4c 49 54 45 5f lue are [SQLITE_
acc0: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
acd0: 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 ]..** New verbs
ace0: 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 are likely to be
acf0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
ad00: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
ad10: 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ite..*/.int sqli
ad20: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 te3_db_config(sq
ad30: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 lite3*, int op,
ad40: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ...);../*.** CAP
ad50: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c I3REF: Memory Al
ad60: 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 location Routine
ad70: 73 20 7b 48 31 30 31 35 35 7d 20 3c 53 32 30 31 s {H10155} <S201
ad80: 32 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 20>.**.** An ins
ad90: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
ada0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 ject defines the
adb0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 interface betwe
adc0: 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 en SQLite.** and
add0: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 low-level memor
ade0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 y allocation rou
adf0: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 tines..**.** Thi
ae00: 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 s object is used
ae10: 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 in only one pla
ae20: 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 ce in the SQLite
ae30: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 interface..** A
ae40: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
ae50: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
ae60: 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 object is the ar
ae70: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 gument to.** [sq
ae80: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
ae90: 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 when the configu
aea0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
aeb0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
aec0: 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20 IG_MALLOC]. By
aed0: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 creating an inst
aee0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
aef0: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 ect.** and passi
af00: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 ng it to [sqlite
af10: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 64 75 72 69 3_config()] duri
af20: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ng configuration
af30: 2c 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 , an.** applicat
af40: 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 ion can specify
af50: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d an alternative m
af60: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
af70: 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 66 6f subsystem.** fo
af80: 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 r SQLite to use
af90: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 for all of its d
afa0: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 ynamic memory ne
afb0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 eds..**.** Note
afc0: 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 that SQLite come
afd0: 73 20 77 69 74 68 20 61 20 62 75 69 6c 74 2d 69 s with a built-i
afe0: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
aff0: 6f 72 20 74 68 61 74 20 69 73 0a 2a 2a 20 70 65 or that is.** pe
b000: 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 rfectly adequate
b010: 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 for the overwhe
b020: 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f lming majority o
b030: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a f applications.*
b040: 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 * and that this
b050: 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 object is only u
b060: 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 seful to a tiny
b070: 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c minority of appl
b080: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 ications.** with
b090: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d specialized mem
b0a0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
b0b0: 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 equirements. Th
b0c0: 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 is object is.**
b0d0: 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 also used during
b0e0: 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 testing of SQLi
b0f0: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 te in order to s
b100: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e pecify an altern
b110: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 ative.** memory
b120: 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 allocator that s
b130: 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 imulates memory
b140: 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f out-of-memory co
b150: 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f nditions in.** o
b160: 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 rder to verify t
b170: 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 hat SQLite recov
b180: 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 ers gracefully f
b190: 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 rom such.** cond
b1a0: 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 itions..**.** Th
b1b0: 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 46 72 65 65 e xMalloc, xFree
b1c0: 2c 20 61 6e 64 20 78 52 65 61 6c 6c 6f 63 20 6d , and xRealloc m
b1d0: 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b ethods must work
b1e0: 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c like the.** mal
b1f0: 6c 6f 63 28 29 2c 20 66 72 65 65 28 29 2c 20 61 loc(), free(), a
b200: 6e 64 20 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e nd realloc() fun
b210: 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 ctions from the
b220: 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 standard library
b230: 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 ..**.** xSize sh
b240: 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 ould return the
b250: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f allocated size o
b260: 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
b270: 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 ation.** previou
b280: 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f sly obtained fro
b290: 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 m xMalloc or xRe
b2a0: 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f alloc. The allo
b2b0: 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 cated size.** is
b2c0: 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 always at least
b2d0: 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 as big as the r
b2e0: 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 equested size bu
b2f0: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e t may be larger.
b300: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e .**.** The xRoun
b310: 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 dup method retur
b320: 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 ns what would be
b330: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 the allocated s
b340: 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f ize of.** a memo
b350: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 ry allocation gi
b360: 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 ven a particular
b370: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e requested size.
b380: 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a Most memory.**
b390: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e allocators roun
b3a0: 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f d up memory allo
b3b0: 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 cations at least
b3c0: 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c to the next mul
b3d0: 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 tiple.** of 8.
b3e0: 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 Some allocators
b3f0: 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 round up to a la
b400: 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 rger multiple or
b410: 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 to a power of 2
b420: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 ..**.** The xIni
b430: 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c t method initial
b440: 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 izes the memory
b450: 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 allocator. (For
b460: 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 example,.** it
b470: 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 might allocate a
b480: 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 ny require mutex
b490: 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 es or initialize
b4a0: 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a internal data.*
b4b0: 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 * structures. T
b4c0: 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 he xShutdown met
b4d0: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 hod is invoked (
b4e0: 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a indirectly) by.*
b4f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 * [sqlite3_shutd
b500: 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c own()] and shoul
b510: 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 d deallocate any
b520: 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 resources acqui
b530: 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e red.** by xInit.
b540: 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 The pAppData p
b550: 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 ointer is used a
b560: 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d s the only param
b570: 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 eter to.** xInit
b580: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a and xShutdown..
b590: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
b5a0: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 t sqlite3_mem_me
b5b0: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 thods sqlite3_me
b5c0: 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 m_methods;.struc
b5d0: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 t sqlite3_mem_me
b5e0: 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a thods {. void *
b5f0: 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b (*xMalloc)(int);
b600: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f /* Memo
b610: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 ry allocation fu
b620: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 nction */. void
b630: 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 (*xFree)(void*)
b640: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 ; /* Fr
b650: 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 ee a prior alloc
b660: 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 ation */. void
b670: 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 *(*xRealloc)(voi
b680: 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 d*,int); /* Res
b690: 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f ize an allocatio
b6a0: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 n */. int (*xSi
b6b0: 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 ze)(void*);
b6c0: 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 /* Return
b6d0: 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 the size of an a
b6e0: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 llocation */. i
b6f0: 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 nt (*xRoundup)(i
b700: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a nt); /*
b710: 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 Round up reques
b720: 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 t size to alloca
b730: 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 tion size */. i
b740: 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 nt (*xInit)(void
b750: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a *); /*
b760: 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 Initialize the
b770: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
b780: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 */. void (*xSh
b790: 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 utdown)(void*);
b7a0: 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 /* Deinitia
b7b0: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 lize the memory
b7c0: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 allocator */. v
b7d0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 oid *pAppData;
b7e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
b7f0: 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e Argument to xIn
b800: 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f it() and xShutdo
b810: 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a wn() */.};../*.*
b820: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
b830: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e iguration Option
b840: 73 20 7b 48 31 30 31 36 30 7d 20 3c 53 32 30 30 s {H10160} <S200
b850: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 00>.**.** These
b860: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 constants are th
b870: 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 e available inte
b880: 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ger configuratio
b890: 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a n options that.*
b8a0: 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 * can be passed
b8b0: 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
b8c0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 ument to the [sq
b8d0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
b8e0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
b8f0: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 New configurati
b900: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 on options may b
b910: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
b920: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
b930: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e Lite..** Existin
b940: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 g configuration
b950: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 options might be
b960: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 discontinued.
b970: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 Applications.**
b980: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 should check the
b990: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f return code fro
b9a0: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 m [sqlite3_confi
b9b0: 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 g()] to make sur
b9c0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 e that.** the ca
b9d0: 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 ll worked. The
b9e0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
b9f0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c )] interface wil
ba00: 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f l return a.** no
ba10: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f n-zero [error co
ba20: 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 de] if a discont
ba30: 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f inued or unsuppo
ba40: 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 rted configurati
ba50: 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 on option.** is
ba60: 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c invoked..**.** <
ba70: 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 dl>.** <dt>SQLIT
ba80: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
ba90: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 HREAD</dt>.** <d
baa0: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 d>There are no a
bab0: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 rguments to this
bac0: 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f option. This o
bad0: 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a ption disables.*
bae0: 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 * all mutexing a
baf0: 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 nd puts SQLite i
bb00: 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 nto a mode where
bb10: 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 it can only be
bb20: 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e used.** by a sin
bb30: 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e gle thread.</dd>
bb40: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
bb50: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
bb60: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 READ</dt>.** <dd
bb70: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 >There are no ar
bb80: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
bb90: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 option. This op
bba0: 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a tion disables.**
bbb0: 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 mutexing on [da
bbc0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
bbd0: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 n] and [prepared
bbe0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 statement] obje
bbf0: 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c cts..** The appl
bc00: 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f ication is respo
bc10: 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 nsible for seria
bc20: 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f lizing access to
bc30: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
bc40: 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b nnections] and [
bc50: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
bc60: 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 nts]. But other
bc70: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 mutexes.** are
bc80: 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 enabled so that
bc90: 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 SQLite will be s
bca0: 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 afe to use in a
bcb0: 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a multi-threaded.*
bcc0: 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2e 3c 2f * environment.</
bcd0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
bce0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
bcf0: 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c ALIZED</dt>.** <
bd00: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 dd>There are no
bd10: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 arguments to thi
bd20: 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 s option. This
bd30: 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a option enables.*
bd40: 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e * all mutexes in
bd50: 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 cluding the recu
bd60: 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 rsive.** mutexes
bd70: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
bd80: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 nnection] and [p
bd90: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
bda0: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 t] objects..** I
bdb0: 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 n this mode (whi
bdc0: 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c ch is the defaul
bdd0: 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 t when SQLite is
bde0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
bdf0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 * [SQLITE_THREAD
be00: 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c SAFE=1]) the SQL
be10: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c ite library will
be20: 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a itself serializ
be30: 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b e access.** to [
be40: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
be50: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 ions] and [prepa
be60: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 red statements]
be70: 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 so that the.** a
be80: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 pplication is fr
be90: 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 ee to use the sa
bea0: 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e me [database con
beb0: 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a nection] or the.
bec0: 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 ** same [prepare
bed0: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 d statement] in
bee0: 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
bef0: 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 s at the same ti
bf00: 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 54 68 69 me..**.** <p>Thi
bf10: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 s configuration
bf20: 6f 70 74 69 6f 6e 20 6d 65 72 65 6c 79 20 73 65 option merely se
bf30: 74 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d ts the default m
bf40: 75 74 65 78 20 0a 2a 2a 20 62 65 68 61 76 69 6f utex .** behavio
bf50: 72 20 74 6f 20 73 65 72 69 61 6c 69 7a 65 20 61 r to serialize a
bf60: 63 63 65 73 73 20 74 6f 20 5b 64 61 74 61 62 61 ccess to [databa
bf70: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e se connections].
bf80: 20 20 49 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 Individual.**
bf90: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
bfa0: 74 69 6f 6e 73 5d 20 63 61 6e 20 6f 76 65 72 72 tions] can overr
bfb0: 69 64 65 20 74 68 69 73 20 73 65 74 74 69 6e 67 ide this setting
bfc0: 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 53 .** using the [S
bfd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
bfe0: 45 58 5d 20 66 6c 61 67 20 74 6f 20 5b 73 71 6c EX] flag to [sql
bff0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e ite3_open_v2()].
c000: 3c 2f 70 3e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 </p></dd>.**.**
c010: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
c020: 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a G_MALLOC</dt>.**
c030: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e <dd>This option
c040: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
c050: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
c060: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
c070: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 n.** instance of
c080: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 the [sqlite3_me
c090: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 m_methods] struc
c0a0: 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d ture. The argum
c0b0: 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a ent specifies.**
c0c0: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 alternative low
c0d0: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c -level memory al
c0e0: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 location routine
c0f0: 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 s to be used in
c100: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 place of.** the
c110: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
c120: 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 n routines built
c130: 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 into SQLite.</d
c140: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
c150: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 ITE_CONFIG_GETMA
c160: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 LLOC</dt>.** <dd
c170: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b >This option tak
c180: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
c190: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
c1a0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
c1b0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
c1c0: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
c1d0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
c1e0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
c1f0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 mem_methods].**
c200: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c structure is fil
c210: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 led with the cur
c220: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d rently defined m
c230: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
c240: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 routines..** Th
c250: 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 is option can be
c260: 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 used to overloa
c270: 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 d the default me
c280: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a mory allocation.
c290: 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 ** routines with
c2a0: 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 a wrapper that
c2b0: 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f simulations memo
c2c0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 ry allocation fa
c2d0: 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 ilure or.** trac
c2e0: 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c ks memory usage,
c2f0: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 for example.</d
c300: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
c310: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
c320: 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ATUS</dt>.** <dd
c330: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b >This option tak
c340: 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 es single argume
c350: 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 nt of type int,
c360: 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
c370: 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 .** boolean, wh
c380: 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 ich enables or d
c390: 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c isables the coll
c3a0: 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 ection of memory
c3b0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 allocation .**
c3c0: 73 74 61 74 69 73 74 69 63 73 2e 20 57 68 65 6e statistics. When
c3d0: 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 disabled, the f
c3e0: 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 ollowing SQLite
c3f0: 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d interfaces becom
c400: 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74 e .** non-operat
c410: 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e ional:.** <ul>
c420: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 .** <li> [sqli
c430: 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
c440: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 )].** <li> [sq
c450: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
c460: 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c hwater()].** <
c470: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 li> [sqlite3_sof
c480: 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a t_heap_limit()].
c490: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
c4a0: 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 e3_status()].**
c4b0: 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e </ul>.** </dd>
c4c0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
c4d0: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
c4e0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
c4f0: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 s option specifi
c500: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f es a static memo
c510: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 ry buffer that S
c520: 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f QLite can use fo
c530: 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d r.** scratch mem
c540: 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 ory. There are
c550: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a three arguments:
c560: 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 A pointer to t
c570: 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 0a 2a he memory, the.*
c580: 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 * size of each s
c590: 63 72 61 74 63 68 20 62 75 66 66 65 72 20 28 73 cratch buffer (s
c5a0: 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 z), and the numb
c5b0: 65 72 20 6f 66 20 62 75 66 66 65 72 73 20 28 4e er of buffers (N
c5c0: 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 ). The sz.** ar
c5d0: 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 gument must be a
c5e0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e multiple of 16.
c5f0: 20 54 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 The sz paramete
c600: 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65 r should be a fe
c610: 77 20 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 w bytes.** large
c620: 72 20 74 68 61 6e 20 74 68 65 20 61 63 74 75 61 r than the actua
c630: 6c 20 73 63 72 61 74 63 68 20 73 70 61 63 65 20 l scratch space
c640: 72 65 71 75 69 72 65 64 20 64 75 65 20 69 6e 74 required due int
c650: 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a ernal overhead..
c660: 2a 2a 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 ** The first.**
c670: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
c680: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f point to an allo
c690: 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 cation of at lea
c6a0: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 st sz*N bytes of
c6b0: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 memory..** SQLi
c6c0: 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d te will use no m
c6d0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 ore than one scr
c6e0: 61 74 63 68 20 62 75 66 66 65 72 20 61 74 20 6f atch buffer at o
c6f0: 6e 63 65 20 70 65 72 20 74 68 72 65 61 64 2c 20 nce per thread,
c700: 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 so.** N should b
c710: 65 20 73 65 74 20 74 6f 20 74 68 65 20 65 78 70 e set to the exp
c720: 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 ected maximum nu
c730: 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e mber of threads.
c740: 20 20 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61 The sz.** para
c750: 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 meter should be
c760: 36 20 74 69 6d 65 73 20 74 68 65 20 73 69 7a 65 6 times the size
c770: 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 of the largest
c780: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 database page si
c790: 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20 62 ze..** Scratch b
c7a0: 75 66 66 65 72 73 20 61 72 65 20 75 73 65 64 20 uffers are used
c7b0: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 as part of the b
c7c0: 74 72 65 65 20 62 61 6c 61 6e 63 65 20 6f 70 65 tree balance ope
c7d0: 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 ration. If.** T
c7e0: 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 he btree balance
c7f0: 72 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e r needs addition
c800: 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 al memory beyond
c810: 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 what is provide
c820: 64 20 62 79 0a 2a 2a 20 73 63 72 61 74 63 68 20 d by.** scratch
c830: 62 75 66 66 65 72 73 20 6f 72 20 69 66 20 6e 6f buffers or if no
c840: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 scratch buffer
c850: 73 70 61 63 65 20 69 73 20 73 70 65 63 69 66 69 space is specifi
c860: 65 64 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a ed, then SQLite.
c870: 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 ** goes to [sqli
c880: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f te3_malloc()] to
c890: 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f obtain the memo
c8a0: 72 79 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64 ry it needs.</dd
c8b0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
c8c0: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
c8d0: 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e CHE</dt>.** <dd>
c8e0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 This option spec
c8f0: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d ifies a static m
c900: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 emory buffer tha
c910: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 t SQLite can use
c920: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 for.** the data
c930: 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 2e base page cache.
c940: 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 There are thre
c950: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 e arguments: A p
c960: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a ointer to the.**
c970: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a memory, the siz
c980: 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 e of each page b
c990: 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 uffer (sz), and
c9a0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 the number of pa
c9b0: 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 ges (N)..** The
c9c0: 73 7a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 sz argument must
c9d0: 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66 20 74 be a power of t
c9e0: 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 wo between 512 a
c9f0: 6e 64 20 33 32 37 36 38 2e 20 20 54 68 65 20 66 nd 32768. The f
ca00: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 irst.** argument
ca10: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f should point to
ca20: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f an allocation o
ca30: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 f at least sz*N
ca40: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e bytes of memory.
ca50: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 .** SQLite will
ca60: 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 use the memory p
ca70: 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 rovided by the f
ca80: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
ca90: 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 satisfy its.**
caa0: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 memory needs for
cab0: 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 the first N pag
cac0: 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 es that it adds
cad0: 74 6f 20 63 61 63 68 65 2e 20 20 49 66 20 61 64 to cache. If ad
cae0: 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 ditional.** page
caf0: 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 cache memory is
cb00: 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 needed beyond w
cb10: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 hat is provided
cb20: 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 by this option,
cb30: 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 then.** SQLite g
cb40: 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f oes to [sqlite3_
cb50: 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 malloc()] for th
cb60: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f e additional sto
cb70: 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 rage space..** T
cb80: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
cb90: 6e 20 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20 n might use one
cba0: 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e or more of the N
cbb0: 20 62 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64 buffers to hold
cbc0: 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f .** memory acco
cbd0: 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69 unting informati
cbe0: 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 on. </dd>.**.**
cbf0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
cc00: 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c G_HEAP</dt>.** <
cc10: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 dd>This option s
cc20: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 pecifies a stati
cc30: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 c memory buffer
cc40: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c that SQLite will
cc50: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 use.** for all
cc60: 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d of its dynamic m
cc70: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
cc80: 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 needs beyond th
cc90: 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 ose provided.**
cca0: 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 for by [SQLITE_C
ccb0: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 ONFIG_SCRATCH] a
ccc0: 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 nd [SQLITE_CONFI
ccd0: 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a G_PAGECACHE]..**
cce0: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 There are three
ccf0: 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f arguments: A po
cd00: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d inter to the mem
cd10: 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 ory, the number
cd20: 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 of.** bytes in t
cd30: 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 he memory buffer
cd40: 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 , and the minimu
cd50: 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a m allocation siz
cd60: 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 66 69 e. If.** the fi
cd70: 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 rst pointer (the
cd80: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 memory pointer)
cd90: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 is NULL, then S
cda0: 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a QLite reverts.**
cdb0: 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 to using its de
cdc0: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c fault memory all
cdd0: 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 ocator (the syst
cde0: 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c em malloc() impl
cdf0: 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 ementation),.**
ce00: 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f undoing any prio
ce10: 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 r invocation of
ce20: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
ce30: 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a ALLOC]. If the.
ce40: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 ** memory pointe
ce50: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e r is not NULL an
ce60: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 d either [SQLITE
ce70: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d _ENABLE_MEMSYS3]
ce80: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 or.** [SQLITE_E
ce90: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 NABLE_MEMSYS5] a
cea0: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e re defined, then
ceb0: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 the alternative
cec0: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
ced0: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 ator is engaged
cee0: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 to handle all of
cef0: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 SQLites memory
cf00: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
cf10: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
cf20: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
cf30: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 UTEX</dt>.** <dd
cf40: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b >This option tak
cf50: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
cf60: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
cf70: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
cf80: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
cf90: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
cfa0: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
cfb0: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e re. The argumen
cfc0: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 t specifies.** a
cfd0: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c lternative low-l
cfe0: 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 evel mutex routi
cff0: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 nes to be used i
d000: 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d n place.** the m
d010: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 utex routines bu
d020: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e ilt into SQLite.
d030: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
d040: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
d050: 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c TMUTEX</dt>.** <
d060: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 dd>This option t
d070: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
d080: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
d090: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
d0a0: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 ** instance of t
d0b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
d0c0: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 x_methods] struc
d0d0: 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 ture. The.** [s
d0e0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
d0f0: 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 hods].** structu
d100: 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 re is filled wit
d110: 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 h the currently
d120: 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f defined mutex ro
d130: 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 utines..** This
d140: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 option can be us
d150: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 ed to overload t
d160: 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 he default mutex
d170: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 allocation.** r
d180: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 outines with a w
d190: 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 rapper used to t
d1a0: 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 rack mutex usage
d1b0: 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 for performance
d1c0: 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 .** profiling or
d1d0: 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 testing, for ex
d1e0: 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ample.</dd>.**.*
d1f0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
d200: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 FIG_LOOKASIDE</d
d210: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f t>.** <dd>This o
d220: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 ption takes two
d230: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 arguments that d
d240: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 etermine the def
d250: 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 ault.** memory a
d260: 6c 6c 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69 llcation lookasi
d270: 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e de optimization.
d280: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 The first argu
d290: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 ment is the.** s
d2a0: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b ize of each look
d2b0: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f aside buffer slo
d2c0: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 t and the second
d2d0: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
d2e0: 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 f.** slots alloc
d2f0: 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 ated to each dat
d300: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
d310: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 .</dd>.**.** </d
d320: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
d330: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
d340: 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 LETHREAD 1 /*
d350: 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nil */.#define S
d360: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
d370: 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a TITHREAD 2 /*
d380: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nil */.#define
d390: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
d3a0: 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f RIALIZED 3 /
d3b0: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 * nil */.#define
d3c0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
d3d0: 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 ALLOC 4
d3e0: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d /* sqlite3_mem_m
d3f0: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 ethods* */.#defi
d400: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
d410: 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 _GETMALLOC 5
d420: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d /* sqlite3_mem
d430: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
d440: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
d450: 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 IG_SCRATCH
d460: 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 6 /* void*, in
d470: 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 t sz, int N */.#
d480: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
d490: 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 NFIG_PAGECACHE
d4a0: 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 7 /* void*,
d4b0: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f int sz, int N */
d4c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d4d0: 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 CONFIG_HEAP
d4e0: 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 8 /* void*
d4f0: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 , int nByte, int
d500: 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 min */.#define
d510: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
d520: 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f MSTATUS 9 /
d530: 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 * boolean */.#de
d540: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
d550: 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 IG_MUTEX
d560: 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 10 /* sqlite3_m
d570: 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f utex_methods* */
d580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d590: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 CONFIG_GETMUTEX
d5a0: 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 11 /* sqlit
d5b0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
d5c0: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
d5d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b ITE_CONFIG_CHUNK
d5e0: 41 4c 4c 4f 43 20 20 20 31 32 20 20 2f 2a 20 69 ALLOC 12 /* i
d5f0: 6e 74 20 74 68 72 65 73 68 6f 6c 64 20 2a 2f 0a nt threshold */.
d600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
d610: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 ONFIG_LOOKASIDE
d620: 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 13 /* int in
d630: 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 t */.../*.** CAP
d640: 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 I3REF: Enable Or
d650: 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 Disable Extende
d660: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b d Result Codes {
d670: 48 31 32 32 30 30 7d 20 3c 53 31 30 37 30 30 3e H12200} <S10700>
d680: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
d690: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
d6a0: 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 lt_codes() routi
d6b0: 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 ne enables or di
d6c0: 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 sables the.** [e
d6d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
d6e0: 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 odes] feature of
d6f0: 20 53 51 4c 69 74 65 2e 20 54 68 65 20 65 78 74 SQLite. The ext
d700: 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 ended result.**
d710: 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c codes are disabl
d720: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f ed by default fo
d730: 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d r historical com
d740: 70 61 74 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 patibility consi
d750: 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a derations..**.**
d760: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
d770: 2a 2a 20 7b 48 31 32 32 30 31 7d 20 45 61 63 68 ** {H12201} Each
d780: 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 new [database c
d790: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 68 61 6c 6c onnection] shall
d7a0: 20 68 61 76 65 20 74 68 65 0a 2a 2a 20 20 20 20 have the.**
d7b0: 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20 [extended
d7c0: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 result codes] fe
d7d0: 61 74 75 72 65 20 64 69 73 61 62 6c 65 64 20 62 ature disabled b
d7e0: 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a y default..**.**
d7f0: 20 7b 48 31 32 32 30 32 7d 20 54 68 65 20 5b 73 {H12202} The [s
d800: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
d810: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 44 2c 46 result_codes(D,F
d820: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 )] interface sha
d830: 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 ll enable.**
d840: 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20 [extended
d850: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 6f result codes] fo
d860: 72 20 74 68 65 20 20 5b 64 61 74 61 62 61 73 65 r the [database
d870: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a connection] D.*
d880: 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74 68 * if th
d890: 65 20 46 20 70 61 72 61 6d 65 74 65 72 20 69 73 e F parameter is
d8a0: 20 74 72 75 65 2c 20 6f 72 20 64 69 73 61 62 6c true, or disabl
d8b0: 65 20 74 68 65 6d 20 69 66 20 46 20 69 73 20 66 e them if F is f
d8c0: 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c alse..*/.int sql
d8d0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 ite3_extended_re
d8e0: 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 sult_codes(sqlit
d8f0: 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b e3*, int onoff);
d900: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
d910: 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f : Last Insert Ro
d920: 77 69 64 20 7b 48 31 32 32 32 30 7d 20 3c 53 31 wid {H12220} <S1
d930: 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68 0700>.**.** Each
d940: 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c entry in an SQL
d950: 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 ite table has a
d960: 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 unique 64-bit si
d970: 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 gned.** integer
d980: 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 22 key called the "
d990: 72 6f 77 69 64 22 2e 20 54 68 65 20 72 6f 77 69 rowid". The rowi
d9a0: 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 d is always avai
d9b0: 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 lable.** as an u
d9c0: 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e ndeclared column
d9d0: 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 named ROWID, OI
d9e0: 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 D, or _ROWID_ as
d9f0: 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a long as those.*
da00: 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 * names are not
da10: 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 also used by exp
da20: 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 licitly declared
da30: 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 columns. If.**
da40: 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 the table has a
da50: 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 49 column of type I
da60: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b NTEGER PRIMARY K
da70: 45 59 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c EY then that col
da80: 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 umn.** is anothe
da90: 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 r alias for the
daa0: 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 rowid..**.** Thi
dab0: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
dac0: 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 s the rowid of t
dad0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a he most recent.*
dae0: 2a 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53 * successful INS
daf0: 45 52 54 20 69 6e 74 6f 20 74 68 65 20 64 61 74 ERT into the dat
db00: 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b abase from the [
db10: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
db20: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 ion].** in the f
db30: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 irst argument.
db40: 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c If no successful
db50: 20 49 4e 53 45 52 54 73 0a 2a 2a 20 68 61 76 65 INSERTs.** have
db60: 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f ever occurred o
db70: 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 n that database
db80: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f connection, zero
db90: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
dba0: 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45 52 54 .** If an INSERT
dbb0: 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 occurs within a
dbc0: 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 trigger, then t
dbd0: 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 he rowid of the
dbe0: 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 inserted.** row
dbf0: 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 is returned by t
dc00: 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c his routine as l
dc10: 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 ong as the trigg
dc20: 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a er is running..*
dc30: 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 * But once the t
dc40: 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 rigger terminate
dc50: 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 s, the value ret
dc60: 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f urned by this ro
dc70: 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 utine.** reverts
dc80: 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c to the last val
dc90: 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f ue inserted befo
dca0: 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 66 re the trigger f
dcb0: 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 49 ired..**.** An I
dcc0: 4e 53 45 52 54 20 74 68 61 74 20 66 61 69 6c 73 NSERT that fails
dcd0: 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 due to a constr
dce0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 aint violation i
dcf0: 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 s not a.** succe
dd00: 73 73 66 75 6c 20 49 4e 53 45 52 54 20 61 6e 64 ssful INSERT and
dd10: 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 does not change
dd20: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
dd30: 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 ned by this.** r
dd40: 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20 49 4e outine. Thus IN
dd50: 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e SERT OR FAIL, IN
dd60: 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 SERT OR IGNORE,
dd70: 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 INSERT OR ROLLBA
dd80: 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 CK,.** and INSER
dd90: 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 T OR ABORT make
dda0: 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 no changes to th
ddb0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
ddc0: 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e f this.** routin
ddd0: 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 e when their ins
dde0: 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57 ertion fails. W
ddf0: 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 hen INSERT OR RE
de00: 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 PLACE.** encount
de10: 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 ers a constraint
de20: 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 violation, it d
de30: 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 oes not fail. T
de40: 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e he.** INSERT con
de50: 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 tinues to comple
de60: 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 tion after delet
de70: 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 ing rows that ca
de80: 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 used.** the cons
de90: 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 traint problem s
dea0: 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c o INSERT OR REPL
deb0: 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 ACE will always
dec0: 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 change.** the re
ded0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
dee0: 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a is interface..**
def0: 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 .** For the purp
df00: 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 oses of this rou
df10: 74 69 6e 65 2c 20 61 6e 20 49 4e 53 45 52 54 20 tine, an INSERT
df20: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f is considered to
df30: 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 .** be successfu
df40: 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 l even if it is
df50: 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c subsequently rol
df60: 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 led back..**.**
df70: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
df80: 2a 20 7b 48 31 32 32 32 31 7d 20 54 68 65 20 5b * {H12221} The [
df90: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
dfa0: 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e ert_rowid()] fun
dfb0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
dfc0: 65 20 72 6f 77 69 64 0a 2a 2a 20 20 20 20 20 20 e rowid.**
dfd0: 20 20 20 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 of the most
dfe0: 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 recent successfu
dff0: 6c 20 49 4e 53 45 52 54 20 70 65 72 66 6f 72 6d l INSERT perform
e000: 65 64 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a ed on the same.*
e010: 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 * [data
e020: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
e030: 20 61 6e 64 20 77 69 74 68 69 6e 20 74 68 65 20 and within the
e040: 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20 6c same or higher l
e050: 65 76 65 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 evel.**
e060: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 trigger context
e070: 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 , or zero if the
e080: 72 65 20 68 61 76 65 20 62 65 65 6e 20 6e 6f 20 re have been no
e090: 71 75 61 6c 69 66 79 69 6e 67 20 69 6e 73 65 72 qualifying inser
e0a0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 ts..**.** {H1222
e0b0: 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 3} The [sqlite3_
e0c0: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
e0d0: 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 d()] function re
e0e0: 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 turns the.**
e0f0: 20 20 20 20 20 20 73 61 6d 65 20 76 61 6c 75 65 same value
e100: 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f when called fro
e110: 6d 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 m the same trigg
e120: 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 er context.**
e130: 20 20 20 20 20 20 20 69 6d 6d 65 64 69 61 74 65 immediate
e140: 6c 79 20 62 65 66 6f 72 65 20 61 6e 64 20 61 66 ly before and af
e150: 74 65 72 20 61 20 52 4f 4c 4c 42 41 43 4b 2e 0a ter a ROLLBACK..
e160: 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e **.** ASSUMPTION
e170: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 33 32 S:.**.** {A12232
e180: 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 } If a separate
e190: 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 thread performs
e1a0: 61 20 6e 65 77 20 49 4e 53 45 52 54 20 6f 6e 20 a new INSERT on
e1b0: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 the same.**
e1c0: 20 20 20 20 20 64 61 74 61 62 61 73 65 20 63 6f database co
e1d0: 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 nnection while t
e1e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 he [sqlite3_last
e1f0: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d _insert_rowid()]
e200: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e .** fun
e210: 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
e220: 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 and thus change
e230: 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 s the last inser
e240: 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 20 20 20 20 t rowid,.**
e250: 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 76 61 then the va
e260: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
e270: 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e [sqlite3_last_in
e280: 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 sert_rowid()] is
e290: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 70 .** unp
e2a0: 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d redictable and m
e2b0: 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 ight not equal e
e2c0: 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 ither the old or
e2d0: 20 74 68 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20 the new.**
e2e0: 20 20 20 20 20 6c 61 73 74 20 69 6e 73 65 72 74 last insert
e2f0: 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74 rowid..*/.sqlit
e300: 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e3_int64 sqlite3
e310: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
e320: 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f id(sqlite3*);../
e330: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
e340: 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 ount The Number
e350: 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 Of Rows Modified
e360: 20 7b 48 31 32 32 34 30 7d 20 3c 53 31 30 36 30 {H12240} <S1060
e370: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 0>.**.** This fu
e380: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 nction returns t
e390: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 he number of dat
e3a0: 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 abase rows that
e3b0: 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 were changed.**
e3c0: 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 or inserted or d
e3d0: 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f eleted by the mo
e3e0: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 st recently comp
e3f0: 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d leted SQL statem
e400: 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 ent.** on the [d
e410: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
e420: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 on] specified by
e430: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
e440: 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68 eter..** Only ch
e450: 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 anges that are d
e460: 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 irectly specifie
e470: 64 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c d by the INSERT,
e480: 20 55 50 44 41 54 45 2c 0a 2a 2a 20 6f 72 20 44 UPDATE,.** or D
e490: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 ELETE statement
e4a0: 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 are counted. Au
e4b0: 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 xiliary changes
e4c0: 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 caused by.** tri
e4d0: 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f ggers are not co
e4e0: 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b unted. Use the [
e4f0: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
e500: 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f anges()] functio
e510: 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 n.** to find the
e520: 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 total number of
e530: 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 changes includi
e540: 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 ng changes cause
e550: 64 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a d by triggers..*
e560: 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e *.** A "row chan
e570: 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 ge" is a change
e580: 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 to a single row
e590: 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c of a single tabl
e5a0: 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 e.** caused by a
e5b0: 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 n INSERT, DELETE
e5c0: 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 , or UPDATE stat
e5d0: 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 ement. Rows tha
e5e0: 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 t.** are changed
e5f0: 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 as side effects
e600: 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 of REPLACE cons
e610: 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f traint resolutio
e620: 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 n,.** rollback,
e630: 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 ABORT processing
e640: 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72 , DROP TABLE, or
e650: 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a by any other.**
e660: 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e mechanisms do n
e670: 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 ot count as dire
e680: 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a ct row changes..
e690: 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 **.** A "trigger
e6a0: 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 context" is a s
e6b0: 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f cope of executio
e6c0: 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e n that begins an
e6d0: 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 d.** ends with t
e6e0: 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 74 he script of a t
e6f0: 72 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 53 51 rigger. Most SQ
e700: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 L statements are
e710: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 .** evaluated ou
e720: 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 tside of any tri
e730: 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 gger. This is t
e740: 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a he "top level".*
e750: 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 * trigger contex
e760: 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 t. If a trigger
e770: 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 fires from the
e780: 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 top level, a.**
e790: 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 new trigger cont
e7a0: 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 ext is entered f
e7b0: 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 or the duration
e7c0: 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 of that one.** t
e7d0: 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 rigger. Subtrig
e7e0: 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 gers create subc
e7f0: 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 ontexts for thei
e800: 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a r duration..**.*
e810: 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 * Calling [sqlit
e820: 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 e3_exec()] or [s
e830: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 qlite3_step()] r
e840: 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a ecursively does.
e850: 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 ** not create a
e860: 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 new trigger cont
e870: 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ext..**.** This
e880: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
e890: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 the number of d
e8a0: 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 irect row change
e8b0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 s in the.** most
e8c0: 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 recent INSERT,
e8d0: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 UPDATE, or DELET
e8e0: 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 E statement with
e8f0: 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 in the same.** t
e900: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a rigger context..
e910: 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e **.** Thus, when
e920: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
e930: 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 top level, this
e940: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
e950: 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
e960: 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 of changes in th
e970: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e e most recent IN
e980: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 SERT, UPDATE, or
e990: 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 DELETE.** that
e9a0: 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 also occurred at
e9b0: 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 the top level.
e9c0: 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 Within the body
e9d0: 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a of a trigger,.*
e9e0: 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 * the sqlite3_ch
e9f0: 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 anges() interfac
ea00: 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 e can be called
ea10: 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 to find the numb
ea20: 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 er of.** changes
ea30: 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 in the most rec
ea40: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 ently completed
ea50: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
ea60: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 or DELETE.** sta
ea70: 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 tement within th
ea80: 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 e body of the sa
ea90: 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 me trigger..** H
eaa0: 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 owever, the numb
eab0: 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 er returned does
eac0: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 not include cha
ead0: 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 nges.** caused b
eae0: 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 y subtriggers si
eaf0: 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 nce those have t
eb00: 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 heir own context
eb10: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 ..**.** SQLite i
eb20: 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f mplements the co
eb30: 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 mmand "DELETE FR
eb40: 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 OM table" withou
eb50: 74 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 t a WHERE clause
eb60: 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 .** by dropping
eb70: 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 and recreating t
eb80: 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 he table. (This
eb90: 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 is much faster
eba0: 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 than going.** th
ebb0: 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 rough and deleti
ebc0: 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c ng individual el
ebd0: 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 ements from the
ebe0: 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 table.) Because
ebf0: 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 of this.** opti
ec00: 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 mization, the de
ec10: 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 letions in "DELE
ec20: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 TE FROM table" a
ec30: 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 re not row chang
ec40: 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e es and.** will n
ec50: 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 ot be counted by
ec60: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 the sqlite3_cha
ec70: 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 nges() or [sqlit
ec80: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
ec90: 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 ()].** functions
eca0: 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 , regardless of
ecb0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c the number of el
ecc0: 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 ements that were
ecd0: 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 originally.** i
ece0: 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f n the table. To
ecf0: 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 get an accurate
ed00: 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 count of the nu
ed10: 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c mber of rows del
ed20: 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 eted, use.** "DE
ed30: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 LETE FROM table
ed40: 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 WHERE 1" instead
ed50: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
ed60: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 TS:.**.** {H1224
ed70: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 1} The [sqlite3_
ed80: 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 changes()] funct
ed90: 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e ion shall return
eda0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
edb0: 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77 20 63 * row c
edc0: 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 hanges caused by
edd0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
ede0: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c INSERT, UPDATE,
edf0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
ee00: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 DELETE statement
ee10: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 on the same dat
ee20: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
ee30: 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
ee40: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 within the same
ee50: 20 6f 72 20 68 69 67 68 65 72 20 74 72 69 67 67 or higher trigg
ee60: 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a er context, or z
ee70: 65 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 ero if there hav
ee80: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f e.** no
ee90: 74 20 62 65 65 6e 20 61 6e 79 20 71 75 61 6c 69 t been any quali
eea0: 66 79 69 6e 67 20 72 6f 77 20 63 68 61 6e 67 65 fying row change
eeb0: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 33 s..**.** {H12243
eec0: 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 } Statements of
eed0: 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 the form "DELETE
eee0: 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 FROM tablename"
eef0: 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 with no.**
ef00: 20 20 20 20 20 57 48 45 52 45 20 63 6c 61 75 73 WHERE claus
ef10: 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20 73 75 e shall cause su
ef20: 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 bsequent calls t
ef30: 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 o.** [s
ef40: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
ef50: 5d 20 74 6f 20 72 65 74 75 72 6e 20 7a 65 72 6f ] to return zero
ef60: 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 , regardless of
ef70: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
ef80: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6f number of rows o
ef90: 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 riginally in the
efa0: 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 53 table..**.** AS
efb0: 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a SUMPTIONS:.**.**
efc0: 20 7b 41 31 32 32 35 32 7d 20 49 66 20 61 20 73 {A12252} If a s
efd0: 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d eparate thread m
efe0: 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 akes changes on
eff0: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
f000: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
f010: 20 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b while [
f020: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
f030: 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 )] is running th
f040: 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 en the value ret
f050: 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 urned.**
f060: 20 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 is unpredictab
f070: 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 le and not meani
f080: 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ngful..*/.int sq
f090: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 lite3_changes(sq
f0a0: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
f0b0: 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 CAPI3REF: Total
f0c0: 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d Number Of Rows M
f0d0: 6f 64 69 66 69 65 64 20 7b 48 31 32 32 36 30 7d odified {H12260}
f0e0: 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S10600>.**.**
f0f0: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
f100: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
f110: 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 of row changes
f120: 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 54 caused by INSERT
f130: 2c 0a 2a 2a 20 55 50 44 41 54 45 20 6f 72 20 44 ,.** UPDATE or D
f140: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 ELETE statements
f150: 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 since the [data
f160: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
f170: 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 was opened..**
f180: 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64 The count includ
f190: 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 66 es all changes f
f1a0: 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72 20 rom all trigger
f1b0: 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77 65 76 contexts. Howev
f1c0: 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 er,.** the count
f1d0: 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 does not includ
f1e0: 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 e changes used t
f1f0: 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50 4c o implement REPL
f200: 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c ACE constraints,
f210: 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 .** do rollbacks
f220: 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 or ABORT proces
f230: 73 69 6e 67 2c 20 6f 72 20 44 52 4f 50 20 74 61 sing, or DROP ta
f240: 62 6c 65 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a ble processing..
f250: 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 73 20 61 ** The changes a
f260: 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f re counted as so
f270: 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74 65 6d on as the statem
f280: 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 ent that makes t
f290: 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65 hem is.** comple
f2a0: 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 ted (when the st
f2b0: 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 atement handle i
f2c0: 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c s passed to [sql
f2d0: 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
f2e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e .** [sqlite3_fin
f2f0: 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a alize()])..**.**
f300: 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e SQLite implemen
f310: 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 ts the command "
f320: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c DELETE FROM tabl
f330: 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45 e" without a WHE
f340: 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 RE clause.** by
f350: 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 dropping and rec
f360: 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c reating the tabl
f370: 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 e. (This is muc
f380: 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f h faster than go
f390: 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 ing.** through a
f3a0: 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 nd deleting indi
f3b0: 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 vidual elements
f3c0: 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 from the table.)
f3d0: 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 69 Because of thi
f3e0: 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f s.** optimizatio
f3f0: 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 n, the deletions
f400: 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f 4d in "DELETE FROM
f410: 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 table" are not
f420: 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64 0a row changes and.
f430: 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 ** will not be c
f440: 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20 73 71 ounted by the sq
f450: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 lite3_changes()
f460: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 or [sqlite3_tota
f470: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 l_changes()].**
f480: 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 functions, regar
f490: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d dless of the num
f4a0: 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 ber of elements
f4b0: 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e that were origin
f4c0: 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 ally.** in the t
f4d0: 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 6e able. To get an
f4e0: 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 accurate count
f4f0: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 of the number of
f500: 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 rows deleted, u
f510: 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 se.** "DELETE FR
f520: 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 OM table WHERE 1
f530: 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a " instead..**.**
f540: 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 See also the [s
f550: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
f560: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a ] interface..**.
f570: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
f580: 2a 0a 2a 2a 20 7b 48 31 32 32 36 31 7d 20 54 68 *.** {H12261} Th
f590: 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c e [sqlite3_total
f5a0: 5f 63 68 61 6e 67 65 73 28 29 5d 20 72 65 74 75 _changes()] retu
f5b0: 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 rns the total nu
f5c0: 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 mber.**
f5d0: 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 of row changes
f5e0: 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 54 caused by INSERT
f5f0: 2c 20 55 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72 , UPDATE, and/or
f600: 20 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20 DELETE.**
f610: 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20 6f statements o
f620: 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 n the same [data
f630: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
f640: 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20 20 20 , in any.**
f650: 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e trigger con
f660: 74 65 78 74 2c 20 73 69 6e 63 65 20 74 68 65 20 text, since the
f670: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
f680: 69 6f 6e 20 77 61 73 20 63 72 65 61 74 65 64 2e ion was created.
f690: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 33 7d 20 .**.** {H12263}
f6a0: 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 Statements of th
f6b0: 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 e form "DELETE F
f6c0: 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 ROM tablename" w
f6d0: 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 ith no.**
f6e0: 20 20 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 WHERE clause
f6f0: 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 shall not change
f700: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
f710: 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ned.**
f720: 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 by [sqlite3_tota
f730: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 2e 0a 2a 2a l_changes()]..**
f740: 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a .** ASSUMPTIONS:
f750: 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 36 34 7d 20 .**.** {A12264}
f760: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
f770: 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 read makes chang
f780: 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 es on the same d
f790: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
f7a0: 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 on.** w
f7b0: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f hile [sqlite3_to
f7c0: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 tal_changes()] i
f7d0: 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 s running then t
f7e0: 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 he value.**
f7f0: 20 20 20 20 20 72 65 74 75 72 6e 65 64 20 69 73 returned is
f800: 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 unpredictable a
f810: 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 nd not meaningfu
f820: 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 l..*/.int sqlite
f830: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
f840: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
f850: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 * CAPI3REF: Inte
f860: 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e rrupt A Long-Run
f870: 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31 32 32 ning Query {H122
f880: 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a 70} <S30500>.**.
f890: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
f8a0: 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 causes any pend
f8b0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 ing database ope
f8c0: 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 ration to abort
f8d0: 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 and.** return at
f8e0: 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 its earliest op
f8f0: 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 portunity. This
f900: 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 routine is typic
f910: 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 ally.** called i
f920: 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 n response to a
f930: 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 user action such
f940: 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 as pressing "Ca
f950: 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c ncel".** or Ctrl
f960: 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 -C where the use
f970: 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 r wants a long q
f980: 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 uery operation t
f990: 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 o halt.** immedi
f9a0: 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 ately..**.** It
f9b0: 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 is safe to call
f9c0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f this routine fro
f9d0: 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 m a thread diffe
f9e0: 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a rent from the.**
f9f0: 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 thread that is
fa00: 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e currently runnin
fa10: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f g the database o
fa20: 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 peration. But i
fa30: 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 t.** is not safe
fa40: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f to call this ro
fa50: 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 utine with a [da
fa60: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
fa70: 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c n] that.** is cl
fa80: 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c osed or might cl
fa90: 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 ose before sqlit
faa0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 e3_interrupt() r
fab0: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 eturns..**.** If
fac0: 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f an SQL operatio
fad0: 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 n is very nearly
fae0: 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 finished at the
faf0: 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 time when.** sq
fb00: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
fb10: 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 ) is called, the
fb20: 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 n it might not h
fb30: 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 ave an opportuni
fb40: 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 ty.** to be inte
fb50: 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 rrupted and migh
fb60: 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f t continue to co
fb70: 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 mpletion..**.**
fb80: 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e An SQL operation
fb90: 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 that is interru
fba0: 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e pted will return
fbb0: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 [SQLITE_INTERRU
fbc0: 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 PT]..** If the i
fbd0: 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f nterrupted SQL o
fbe0: 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 peration is an I
fbf0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f NSERT, UPDATE, o
fc00: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 r DELETE.** that
fc10: 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 is inside an ex
fc20: 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 plicit transacti
fc30: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 on, then the ent
fc40: 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a ire transaction.
fc50: 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 ** will be rolle
fc60: 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 d back automatic
fc70: 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 ally..**.** A ca
fc80: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e ll to sqlite3_in
fc90: 74 65 72 72 75 70 74 28 29 20 68 61 73 20 6e 6f terrupt() has no
fca0: 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 effect on SQL s
fcb0: 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 tatements.** tha
fcc0: 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 t are started af
fcd0: 74 65 72 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 ter sqlite3_inte
fce0: 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e rrupt() returns.
fcf0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
fd00: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 31 S:.**.** {H12271
fd10: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 } The [sqlite3_i
fd20: 6e 74 65 72 72 75 70 74 28 29 5d 20 69 6e 74 65 nterrupt()] inte
fd30: 72 66 61 63 65 20 77 69 6c 6c 20 66 6f 72 63 65 rface will force
fd40: 20 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 all running.**
fd50: 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61 SQL sta
fd60: 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 tements associat
fd70: 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 ed with the same
fd80: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
fd90: 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 tion.**
fda0: 20 74 6f 20 68 61 6c 74 20 61 66 74 65 72 20 70 to halt after p
fdb0: 72 6f 63 65 73 73 69 6e 67 20 61 74 20 6d 6f 73 rocessing at mos
fdc0: 74 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c t one additional
fdd0: 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a row of data..**
fde0: 0a 2a 2a 20 7b 48 31 32 32 37 32 7d 20 41 6e 79 .** {H12272} Any
fdf0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
fe00: 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 hat is interrupt
fe10: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 69 ed by [sqlite3_i
fe20: 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 nterrupt()].**
fe30: 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74 will ret
fe40: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 urn [SQLITE_INTE
fe50: 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 RRUPT]..**.** AS
fe60: 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a SUMPTIONS:.**.**
fe70: 20 7b 41 31 32 32 37 39 7d 20 49 66 20 74 68 65 {A12279} If the
fe80: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
fe90: 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c tion closes whil
fea0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 e [sqlite3_inter
feb0: 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 rupt()].**
fec0: 20 20 20 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 is running t
fed0: 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 hen bad things w
fee0: 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 ill likely happe
fef0: 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 n..*/.void sqlit
ff00: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c e3_interrupt(sql
ff10: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
ff20: 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 API3REF: Determi
ff30: 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 ne If An SQL Sta
ff40: 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 tement Is Comple
ff50: 74 65 20 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 te {H10510} <S70
ff60: 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 200>.**.** These
ff70: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 routines are us
ff80: 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 eful for command
ff90: 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 -line input to d
ffa0: 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a etermine if the.
ffb0: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 ** currently ent
ffc0: 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 ered text seems
ffd0: 74 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 to form complete
ffe0: 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 a SQL statement
fff0: 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 or.** if additi
10000 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 onal input is ne
10010 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 eded before send
10020 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 ing the text int
10030 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 o.** SQLite for
10040 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 parsing. These
10050 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
10060 74 72 75 65 20 69 66 20 74 68 65 20 69 6e 70 75 true if the inpu
10070 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 t string.** appe
10080 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 ars to be a comp
10090 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 lete SQL stateme
100a0 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 nt. A statement
100b0 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 is judged to be
100c0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 .** complete if
100d0 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 it ends with a s
100e0 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 emicolon token a
100f0 6e 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67 nd is not a frag
10100 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 ment of a.** CRE
10110 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 ATE TRIGGER stat
10120 65 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f ement. Semicolo
10130 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 ns that are embe
10140 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 dded within.** s
10150 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f tring literals o
10160 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 r quoted identif
10170 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d ier names or com
10180 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a ments are not.**
10190 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b independent tok
101a0 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 ens (they are pa
101b0 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 rt of the token
101c0 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 in which they ar
101d0 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 e.** embedded) a
101e0 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 nd thus do not c
101f0 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d ount as a statem
10200 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a ent terminator..
10210 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
10220 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 ines do not pars
10230 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d e the SQL statem
10240 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c ents thus.** wil
10250 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e l not detect syn
10260 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 tactically incor
10270 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 rect SQL..**.**
10280 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
10290 2a 20 7b 48 31 30 35 31 31 7d 20 41 20 73 75 63 * {H10511} A suc
102a0 63 65 73 73 66 75 6c 20 65 76 61 6c 75 61 74 69 cessful evaluati
102b0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63 on of [sqlite3_c
102c0 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 0a 2a 2a omplete()] or.**
102d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
102e0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d e3_complete16()]
102f0 20 66 75 6e 63 74 69 6f 6e 73 20 73 68 61 6c 6c functions shall
10300 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 .** ret
10310 75 72 6e 20 61 20 6e 75 6d 65 72 69 63 20 31 20 urn a numeric 1
10320 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 if and only if t
10330 68 65 20 6c 61 73 74 20 6e 6f 6e 2d 77 68 69 74 he last non-whit
10340 65 73 70 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 espace.**
10350 20 20 20 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69 token in thei
10360 72 20 69 6e 70 75 74 20 69 73 20 61 20 73 65 6d r input is a sem
10370 69 63 6f 6c 6f 6e 20 74 68 61 74 20 69 73 20 6e icolon that is n
10380 6f 74 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a ot in between.**
10390 20 20 20 20 20 20 20 20 20 20 74 68 65 20 42 45 the BE
103a0 47 49 4e 20 61 6e 64 20 45 4e 44 20 6f 66 20 61 GIN and END of a
103b0 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 CREATE TRIGGER
103c0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a statement..**.**
103d0 20 7b 48 31 30 35 31 32 7d 20 49 66 20 61 20 6d {H10512} If a m
103e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
103f0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 error occurs du
10400 72 69 6e 67 20 61 6e 20 69 6e 76 6f 63 61 74 69 ring an invocati
10410 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f on.** o
10420 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c f [sqlite3_compl
10430 65 74 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 ete()] or [sqlit
10440 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d e3_complete16()]
10450 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 then the.**
10460 20 20 20 20 20 20 72 6f 75 74 69 6e 65 20 73 68 routine sh
10470 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 all return [SQLI
10480 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a TE_NOMEM]..**.**
10490 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a ASSUMPTIONS:.**
104a0 0a 2a 2a 20 7b 41 31 30 35 31 32 7d 20 54 68 65 .** {A10512} The
104b0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 input to [sqlit
104c0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d e3_complete()] m
104d0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 ust be a zero-te
104e0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 rminated.**
104f0 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e UTF-8 strin
10500 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 33 g..**.** {A10513
10510 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b } The input to [
10520 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
10530 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 16()] must be a
10540 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
10550 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d ** UTF-
10560 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 16 string in nat
10570 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a ive byte order..
10580 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
10590 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 omplete(const ch
105a0 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 ar *sql);.int sq
105b0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
105c0 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c (const void *sql
105d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
105e0 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 EF: Register A C
105f0 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c allback To Handl
10600 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 e SQLITE_BUSY Er
10610 72 6f 72 73 20 7b 48 31 32 33 31 30 7d 20 3c 53 rors {H12310} <S
10620 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 40400>.**.** Thi
10630 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 s routine sets a
10640 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
10650 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 on that might be
10660 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 invoked wheneve
10670 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 r.** an attempt
10680 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 is made to open
10690 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 a database table
106a0 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 that another th
106b0 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 read.** or proce
106c0 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a ss has locked..*
106d0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 *.** If the busy
106e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c callback is NUL
106f0 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f L, then [SQLITE_
10700 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 BUSY] or [SQLITE
10710 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a _IOERR_BLOCKED].
10720 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 ** is returned i
10730 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 mmediately upon
10740 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 encountering the
10750 20 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20 62 75 lock. If the bu
10760 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 sy callback.** i
10770 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e s not NULL, then
10780 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 the callback wi
10790 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 ll be invoked wi
107a0 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 th two arguments
107b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
107c0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
107d0 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 e handler is a c
107e0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a opy of the void*
107f0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a pointer which.*
10800 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 * is the third a
10810 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
10820 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
10830 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 ). The second a
10840 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 rgument to.** th
10850 65 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 e handler callba
10860 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 ck is the number
10870 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 of times that t
10880 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
10890 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f has.** been invo
108a0 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 ked for this loc
108b0 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 49 66 20 king event. If
108c0 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c the.** busy call
108d0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 back returns 0,
108e0 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e then no addition
108f0 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 al attempts are
10900 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 made to.** acces
10910 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 s the database a
10920 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d nd [SQLITE_BUSY]
10930 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 or [SQLITE_IOER
10940 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 R_BLOCKED] is re
10950 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 turned..** If th
10960 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
10970 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 ns non-zero, the
10980 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 n another attemp
10990 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 t.** is made to
109a0 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 open the databas
109b0 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e e for reading an
109c0 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 d the cycle repe
109d0 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 ats..**.** The p
109e0 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 resence of a bus
109f0 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e y handler does n
10a00 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 ot guarantee tha
10a10 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 t it will be inv
10a20 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 oked.** when the
10a30 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 re is lock conte
10a40 6e 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 ntion. If SQLite
10a50 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 determines that
10a60 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 invoking the bu
10a70 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f sy.** handler co
10a80 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 uld result in a
10a90 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c deadlock, it wil
10aa0 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 l go ahead and r
10ab0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 eturn [SQLITE_BU
10ac0 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 SY].** or [SQLIT
10ad0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
10ae0 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f instead of invo
10af0 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 king the busy ha
10b00 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 ndler..** Consid
10b10 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 er a scenario wh
10b20 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 ere one process
10b30 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 is holding a rea
10b40 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 d lock that.** i
10b50 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 t is trying to p
10b60 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 romote to a rese
10b70 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a rved lock and.**
10b80 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 a second proces
10b90 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 s is holding a r
10ba0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 eserved lock tha
10bb0 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a t it is trying.*
10bc0 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 * to promote to
10bd0 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 an exclusive loc
10be0 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 k. The first pr
10bf0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f ocess cannot pro
10c00 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 ceed.** because
10c10 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 it is blocked by
10c20 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 the second and
10c30 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 the second proce
10c40 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f ss cannot.** pro
10c50 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 ceed because it
10c60 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 is blocked by th
10c70 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 e first. If bot
10c80 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 h processes.** i
10c90 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 nvoke the busy h
10ca0 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 andlers, neither
10cb0 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 will make any p
10cc0 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 rogress. Theref
10cd0 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 ore,.** SQLite r
10ce0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 eturns [SQLITE_B
10cf0 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 USY] for the fir
10d00 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 st process, hopi
10d10 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 ng that this.**
10d20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 will induce the
10d30 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f first process to
10d40 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 release its rea
10d50 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 d lock and allow
10d60 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 .** the second p
10d70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 rocess to procee
10d80 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 d..**.** The def
10d90 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 ault busy callba
10da0 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a ck is NULL..**.*
10db0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 * The [SQLITE_BU
10dc0 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e SY] error is con
10dd0 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 verted to [SQLIT
10de0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
10df0 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 .** when SQLite
10e00 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 is in the middle
10e10 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e of a large tran
10e20 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c saction where al
10e30 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 l the.** changes
10e40 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e will not fit in
10e50 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 to the in-memory
10e60 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 cache. SQLite
10e70 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 will.** already
10e80 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 hold a RESERVED
10e90 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 lock on the data
10ea0 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 base file, but i
10eb0 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 t needs.** to pr
10ec0 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 omote this lock
10ed0 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 to EXCLUSIVE so
10ee0 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c that it can spil
10ef0 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 l cache.** pages
10f00 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 into the databa
10f10 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 se file without
10f20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 harm to concurre
10f30 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 nt.** readers.
10f40 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 If it is unable
10f50 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c to promote the l
10f60 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e ock, then the in
10f70 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 -memory.** cache
10f80 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e will be left in
10f90 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 an inconsistent
10fa0 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 state and so th
10fb0 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 e error.** code
10fc0 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d is promoted from
10fd0 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 the relatively
10fe0 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 benign [SQLITE_B
10ff0 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d USY] to.** the m
11000 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 ore severe [SQLI
11010 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
11020 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 63 ]. This error c
11030 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a ode promotion.**
11040 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d forces an autom
11050 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 atic rollback of
11060 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 the changes. S
11070 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 ee the.** <a hre
11080 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 f="/cvstrac/wiki
11090 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c ?p=CorruptionFol
110a0 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 lowingBusyError"
110b0 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 >.** CorruptionF
110c0 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f ollowingBusyErro
110d0 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 r</a> wiki page
110e0 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e for a discussion
110f0 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 of why.** this
11100 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a is important..**
11110 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e .** There can on
11120 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 ly be a single b
11130 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 usy handler defi
11140 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 ned for each.**
11150 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
11160 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 tion]. Setting
11170 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c a new busy handl
11180 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a er clears any.**
11190 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 previously set
111a0 68 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 handler. Note t
111b0 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c hat calling [sql
111c0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
111d0 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 t()].** will als
111e0 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 o set or clear t
111f0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e he busy handler.
11200 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
11210 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 31 S:.**.** {H12311
11220 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 } The [sqlite3_b
11230 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 43 2c usy_handler(D,C,
11240 41 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 A)] function sha
11250 6c 6c 20 72 65 70 6c 61 63 65 0a 2a 2a 20 20 20 ll replace.**
11260 20 20 20 20 20 20 20 62 75 73 79 20 63 61 6c 6c busy call
11270 62 61 63 6b 20 69 6e 20 74 68 65 20 5b 64 61 74 back in the [dat
11280 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
11290 5d 20 44 20 77 69 74 68 20 61 20 6e 65 77 0a 2a ] D with a new.*
112a0 2a 20 20 20 20 20 20 20 20 20 20 61 20 6e 65 77 * a new
112b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 43 20 busy handler C
112c0 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 and application
112d0 64 61 74 61 20 70 6f 69 6e 74 65 72 20 41 2e 0a data pointer A..
112e0 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 32 7d 20 4e **.** {H12312} N
112f0 65 77 6c 79 20 63 72 65 61 74 65 64 20 5b 64 61 ewly created [da
11300 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
11310 6e 73 5d 20 73 68 61 6c 6c 20 68 61 76 65 20 61 ns] shall have a
11320 20 62 75 73 79 0a 2a 2a 20 20 20 20 20 20 20 20 busy.**
11330 20 20 68 61 6e 64 6c 65 72 20 6f 66 20 4e 55 4c handler of NUL
11340 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 34 L..**.** {H12314
11350 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f } When two or mo
11360 72 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e re [database con
11370 6e 65 63 74 69 6f 6e 73 5d 20 73 68 61 72 65 20 nections] share
11380 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 a.** [s
11390 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 qlite3_enable_sh
113a0 61 72 65 64 5f 63 61 63 68 65 20 7c 20 63 6f 6d ared_cache | com
113b0 6d 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a 2a 20 20 mon cache],.**
113c0 20 20 20 20 20 20 20 20 74 68 65 20 62 75 73 79 the busy
113d0 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 handler for the
113e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
113f0 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 75 tion currently u
11400 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 sing.**
11410 20 74 68 65 20 63 61 63 68 65 20 73 68 61 6c 6c the cache shall
11420 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e be invoked when
11430 20 74 68 65 20 63 61 63 68 65 20 65 6e 63 6f 75 the cache encou
11440 6e 74 65 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a nters a lock..**
11450 0a 2a 2a 20 7b 48 31 32 33 31 36 7d 20 49 66 20 .** {H12316} If
11460 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 a busy handler c
11470 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
11480 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 53 zero, then the S
11490 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a QLite interface.
114a0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 ** that
114b0 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f provoked the lo
114c0 63 6b 69 6e 67 20 65 76 65 6e 74 20 73 68 61 6c cking event shal
114d0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
114e0 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 _BUSY]..**.** {H
114f0 31 32 33 31 38 7d 20 53 51 4c 69 74 65 20 73 68 12318} SQLite sh
11500 61 6c 6c 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 all invokes the
11510 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77 69 74 busy handler wit
11520 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 h two arguments
11530 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 which.**
11540 20 20 61 72 65 20 61 20 63 6f 70 79 20 6f 66 20 are a copy of
11550 74 68 65 20 70 6f 69 6e 74 65 72 20 73 75 70 70 the pointer supp
11560 6c 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20 lied by the 3rd
11570 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
11580 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
11590 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 3_busy_handler()
115a0 5d 20 61 6e 64 20 61 20 63 6f 75 6e 74 20 6f 66 ] and a count of
115b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 the number of p
115c0 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 rior.**
115d0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 invocations of
115e0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
115f0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f for the same lo
11600 63 6b 69 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a cking event..**.
11610 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a ** ASSUMPTIONS:.
11620 2a 2a 0a 2a 2a 20 7b 41 31 32 33 31 39 7d 20 41 **.** {A12319} A
11630 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 busy handler mu
11640 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 st not close the
11650 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
11660 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 tion.**
11670 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 or [prepared st
11680 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e atement] that in
11690 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 voked the busy h
116a0 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 andler..*/.int s
116b0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
116c0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e ler(sqlite3*, in
116d0 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c t(*)(void*,int),
116e0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*);../*.**
116f0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 CAPI3REF: Set A
11700 42 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 Busy Timeout {H1
11710 32 33 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2340} <S40410>.*
11720 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
11730 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 e sets a [sqlite
11740 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 3_busy_handler |
11750 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 busy handler] t
11760 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f hat sleeps.** fo
11770 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d r a specified am
11780 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 ount of time whe
11790 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 n a table is loc
117a0 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 ked. The handle
117b0 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 r.** will sleep
117c0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 multiple times u
117d0 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d ntil at least "m
117e0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 s" milliseconds
117f0 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 of sleeping.** h
11800 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e ave accumulated.
11810 20 7b 48 31 32 33 34 33 7d 20 41 66 74 65 72 20 {H12343} After
11820 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 "ms" millisecond
11830 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a s of sleeping,.*
11840 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 * the handler re
11850 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 turns 0 which ca
11860 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 uses [sqlite3_st
11870 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a ep()] to return.
11880 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ** [SQLITE_BUSY]
11890 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 or [SQLITE_IOER
118a0 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a R_BLOCKED]..**.*
118b0 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 * Calling this r
118c0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 outine with an a
118d0 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 rgument less tha
118e0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 n or equal to ze
118f0 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 ro.** turns off
11900 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 all busy handler
11910 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 s..**.** There c
11920 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e an only be a sin
11930 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 gle busy handler
11940 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 for a particula
11950 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 r.** [database c
11960 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 onnection] any a
11970 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e ny given moment.
11980 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 If another bus
11990 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 y handler.** was
119a0 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 defined (using
119b0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 [sqlite3_busy_h
119c0 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 andler()]) prior
119d0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 to calling.** t
119e0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 his routine, tha
119f0 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e t other busy han
11a00 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e dler is cleared.
11a10 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
11a20 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 31 S:.**.** {H12341
11a30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 } The [sqlite3_b
11a40 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66 usy_timeout()] f
11a50 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 6f 76 unction shall ov
11a60 65 72 72 69 64 65 20 61 6e 79 20 70 72 69 6f 72 erride any prior
11a70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
11a80 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
11a90 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ut()] or [sqlite
11aa0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 3_busy_handler()
11ab0 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 ] setting.**
11ac0 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d on the sam
11ad0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
11ae0 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b ection]..**.** {
11af0 48 31 32 33 34 33 7d 20 49 66 20 74 68 65 20 32 H12343} If the 2
11b00 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
11b10 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 [sqlite3_busy_ti
11b20 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c 65 73 73 meout()] is less
11b30 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 than.**
11b40 20 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 or equal to ze
11b50 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 62 75 73 ro, then the bus
11b60 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20 y handler shall
11b70 62 65 20 63 6c 65 61 72 65 64 20 73 6f 20 74 68 be cleared so th
11b80 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 at.** a
11b90 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6c 6f ll subsequent lo
11ba0 63 6b 69 6e 67 20 65 76 65 6e 74 73 20 69 6d 6d cking events imm
11bb0 65 64 69 61 74 65 6c 79 20 72 65 74 75 72 6e 20 ediately return
11bc0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a [SQLITE_BUSY]..*
11bd0 2a 0a 2a 2a 20 7b 48 31 32 33 34 34 7d 20 49 66 *.** {H12344} If
11be0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
11bf0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 er to [sqlite3_b
11c00 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 usy_timeout()] i
11c10 73 20 61 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 s a positive.**
11c20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 number
11c30 4e 2c 20 74 68 65 6e 20 61 20 62 75 73 79 20 68 N, then a busy h
11c40 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62 65 20 andler shall be
11c50 73 65 74 20 74 68 61 74 20 72 65 70 65 61 74 65 set that repeate
11c60 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 dly calls.**
11c70 20 20 20 20 20 20 74 68 65 20 78 53 6c 65 65 70 the xSleep
11c80 28 29 20 6d 65 74 68 6f 64 20 69 6e 20 74 68 65 () method in the
11c90 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 [sqlite3_vfs |
11ca0 56 46 53 20 69 6e 74 65 72 66 61 63 65 5d 20 75 VFS interface] u
11cb0 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ntil.**
11cc0 20 65 69 74 68 65 72 20 74 68 65 20 6c 6f 63 6b either the lock
11cd0 20 63 6c 65 61 72 73 20 6f 72 20 75 6e 74 69 6c clears or until
11ce0 20 74 68 65 20 63 75 6d 75 6c 61 74 69 76 65 20 the cumulative
11cf0 73 6c 65 65 70 20 74 69 6d 65 0a 2a 2a 20 20 20 sleep time.**
11d00 20 20 20 20 20 20 20 72 65 70 6f 72 74 65 64 20 reported
11d10 62 61 63 6b 20 62 79 20 78 53 6c 65 65 70 28 29 back by xSleep()
11d20 20 65 78 63 65 65 64 73 20 4e 20 6d 69 6c 6c 69 exceeds N milli
11d30 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 seconds..*/.int
11d40 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
11d50 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 eout(sqlite3*, i
11d60 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 nt ms);../*.** C
11d70 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 API3REF: Conveni
11d80 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f ence Routines Fo
11d90 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 r Running Querie
11da0 73 20 7b 48 31 32 33 37 30 7d 20 3c 53 31 30 30 s {H12370} <S100
11db0 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 00>.**.** Defini
11dc0 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c tion: A <b>resul
11dd0 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d t table</b> is m
11de0 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 emory data struc
11df0 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 ture created by
11e00 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
11e10 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 get_table()] int
11e20 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c erface. A resul
11e30 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 t table records
11e40 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 the.** complete
11e50 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 query results fr
11e60 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 om one or more q
11e70 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ueries..**.** Th
11e80 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 e table conceptu
11e90 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 ally has a numbe
11ea0 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f r of rows and co
11eb0 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 lumns. But.** t
11ec0 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 hese numbers are
11ed0 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 not part of the
11ee0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 result table it
11ef0 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 self. These.**
11f00 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 numbers are obta
11f10 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e ined separately.
11f20 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e Let N be the n
11f30 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a umber of rows.**
11f40 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 and M be the nu
11f50 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e mber of columns.
11f60 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 .**.** A result
11f70 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 table is an arra
11f80 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
11f90 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
11fa0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a UTF-8 strings..
11fb0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b ** There are (N+
11fc0 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 1)*M elements in
11fd0 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 the array. The
11fe0 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 first M pointer
11ff0 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 s point.** to ze
12000 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 ro-terminated st
12010 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 rings that cont
12020 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 ain the names of
12030 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a the columns..**
12040 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 The remaining e
12050 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 ntries all point
12060 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 to query result
12070 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 s. NULL values
12080 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c result.** in NUL
12090 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c L pointers. All
120a0 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 other values ar
120b0 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 e in their UTF-8
120c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
120d0 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 .** string repre
120e0 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 sentation as ret
120f0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
12100 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 3_column_text()]
12110 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 ..**.** A result
12120 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e table might con
12130 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d sist of one or m
12140 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ore memory alloc
12150 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 ations..** It is
12160 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 not safe to pas
12170 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 s a result table
12180 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 directly to [sq
12190 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a lite3_free()]..*
121a0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 * A result table
121b0 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c should be deall
121c0 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 ocated using [sq
121d0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
121e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e ()]..**.** As an
121f0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 example of the
12200 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 result table for
12210 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 mat, suppose a q
12220 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 uery result.** i
12230 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a s as follows:.**
12240 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
12250 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 <pre>.**
12260 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 Name | Ag
12270 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d e.** ----
12280 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
12290 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c ---.** Al
122a0 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a ice | 43.*
122b0 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 * Bob
122c0 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 | 28.**
122d0 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 Cindy
122e0 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f | 21.** </pre></
122f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
12300 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 * There are two
12310 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e column (M==2) an
12320 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d d three rows (N=
12330 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a =3). Thus the.*
12340 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 * result table h
12350 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 as 8 entries. S
12360 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c uppose the resul
12370 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 t table is store
12380 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 d.** in an array
12390 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e names azResult.
123a0 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 Then azResult
123b0 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 holds this conte
123c0 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b nt:.**.** <block
123d0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
123e0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
123f0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 91;0] = "Name";.
12400 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
12410 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 lt[1] = "Age
12420 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
12430 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 esult[2] = "
12440 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 Alice";.**
12450 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 azResult[3
12460 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 ] = "43";.**
12470 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
12480 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 ;4] = "Bob";.**
12490 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
124a0 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a #91;5] = "28";.*
124b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
124c0 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 t[6] = "Cind
124d0 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a y";.** az
124e0 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 Result[7] =
124f0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c "21";.** </pre><
12500 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
12510 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 ** The sqlite3_g
12520 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 et_table() funct
12530 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e ion evaluates on
12540 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d e or more.** sem
12550 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 icolon-separated
12560 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
12570 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d in the zero-term
12580 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 inated UTF-8.**
12590 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e string of its 2n
125a0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 74 d parameter. It
125b0 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c returns a resul
125c0 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a t table to the.*
125d0 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 * pointer given
125e0 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d in its 3rd param
125f0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 eter..**.** Afte
12600 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 r the calling fu
12610 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 nction has finis
12620 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 72 65 hed using the re
12630 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 0a sult, it should.
12640 2a 2a 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e ** pass the poin
12650 74 65 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c ter to the resul
12660 74 20 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 t table to sqlit
12670 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 e3_free_table()
12680 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 in order to.** r
12690 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 elease the memor
126a0 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f y that was mallo
126b0 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 ced. Because of
126c0 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 the way the.**
126d0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
126e0 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 )] happens withi
126f0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 n sqlite3_get_ta
12700 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 ble(), the calli
12710 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d ng.** function m
12720 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 ust not try to c
12730 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 all [sqlite3_fre
12740 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 e()] directly.
12750 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 Only.** [sqlite3
12760 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 _free_table()] i
12770 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 s able to releas
12780 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f e the memory pro
12790 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 perly and safely
127a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
127b0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 te3_get_table()
127c0 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 interface is imp
127d0 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 lemented as a wr
127e0 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 apper around.**
127f0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
12800 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 . The sqlite3_g
12810 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 et_table() routi
12820 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 ne does not have
12830 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e access.** to an
12840 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 y internal data
12850 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 structures of SQ
12860 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f Lite. It uses o
12870 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a nly the public.*
12880 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 * interface defi
12890 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 ned here. As a
128a0 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 consequence, err
128b0 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 ors that occur i
128c0 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 n the.** wrapper
128d0 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f layer outside o
128e0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b f the internal [
128f0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
12900 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 call are not.**
12910 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 reflected in sub
12920 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
12930 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
12940 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 e()] or [sqlite3
12950 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a _errmsg()]..**.*
12960 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
12970 0a 2a 2a 20 7b 48 31 32 33 37 31 7d 20 49 66 20 .** {H12371} If
12980 61 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 a [sqlite3_get_t
12990 61 62 6c 65 28 29 5d 20 66 61 69 6c 73 20 61 20 able()] fails a
129a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
129b0 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 n, then.**
129c0 20 20 20 20 69 74 20 73 68 61 6c 6c 20 66 72 65 it shall fre
129d0 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 e the result tab
129e0 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73 74 72 75 le under constru
129f0 63 74 69 6f 6e 2c 20 61 62 6f 72 74 20 74 68 65 ction, abort the
12a00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 71 75 65 .** que
12a10 72 79 20 69 6e 20 70 72 6f 63 65 73 73 2c 20 73 ry in process, s
12a20 6b 69 70 20 61 6e 79 20 73 75 62 73 65 71 75 65 kip any subseque
12a30 6e 74 20 71 75 65 72 69 65 73 2c 20 73 65 74 20 nt queries, set
12a40 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
12a50 2a 70 61 7a 52 65 73 75 6c 74 20 6f 75 74 70 75 *pazResult outpu
12a60 74 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c t pointer to NUL
12a70 4c 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 L and return [SQ
12a80 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a LITE_NOMEM]..**.
12a90 2a 2a 20 7b 48 31 32 33 37 33 7d 20 49 66 20 74 ** {H12373} If t
12aa0 68 65 20 70 6e 43 6f 6c 75 6d 6e 20 70 61 72 61 he pnColumn para
12ab0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
12ac0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 3_get_table()] i
12ad0 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 s not NULL.**
12ae0 20 20 20 20 20 20 20 74 68 65 6e 20 61 20 73 75 then a su
12af0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 ccessful invocat
12b00 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
12b10 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 73 68 61 get_table()] sha
12b20 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 ll.** w
12b30 72 69 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20 rite the number
12b40 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
12b50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 e.** re
12b60 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 sult set of the
12b70 71 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e 43 6f query into *pnCo
12b80 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 lumn..**.** {H12
12b90 33 37 34 7d 20 49 66 20 74 68 65 20 70 6e 52 6f 374} If the pnRo
12ba0 77 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b w parameter to [
12bb0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
12bc0 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c e()] is not NULL
12bd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
12be0 6e 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 69 n a successful i
12bf0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 nvocation of [sq
12c00 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
12c10 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 )] shall.**
12c20 20 20 20 20 20 77 72 69 74 65 73 20 74 68 65 20 writes the
12c30 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 number of rows i
12c40 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 n the.**
12c50 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 result set of
12c60 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a the query into *
12c70 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 pnRow..**.** {H1
12c80 32 33 37 36 7d 20 41 20 73 75 63 63 65 73 73 66 2376} A successf
12c90 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 ul invocation of
12ca0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 [sqlite3_get_ta
12cb0 62 6c 65 28 29 5d 20 74 68 61 74 20 63 6f 6d 70 ble()] that comp
12cc0 75 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 utes.**
12cd0 20 4e 20 72 6f 77 73 20 6f 66 20 72 65 73 75 6c N rows of resul
12ce0 74 20 77 69 74 68 20 43 20 63 6f 6c 75 6d 6e 73 t with C columns
12cf0 20 70 65 72 20 72 6f 77 20 73 68 61 6c 6c 20 6d per row shall m
12d00 61 6b 65 20 2a 70 61 7a 52 65 73 75 6c 74 0a 2a ake *pazResult.*
12d10 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 * point
12d20 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 to an array of
12d30 70 6f 69 6e 74 65 72 73 20 74 6f 20 28 4e 2b 31 pointers to (N+1
12d40 29 2a 43 20 73 74 72 69 6e 67 73 20 77 68 65 72 )*C strings wher
12d50 65 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 20 e the first.**
12d60 20 20 20 20 20 20 20 20 43 20 73 74 72 69 6e 67 C string
12d70 73 20 61 72 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d s are column nam
12d80 65 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 es as obtained f
12d90 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 rom.**
12da0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
12db0 6e 61 6d 65 28 29 5d 20 61 6e 64 20 74 68 65 20 name()] and the
12dc0 72 65 73 74 20 61 72 65 20 63 6f 6c 75 6d 6e 20 rest are column
12dd0 72 65 73 75 6c 74 20 76 61 6c 75 65 73 0a 2a 2a result values.**
12de0 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e obtain
12df0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
12e00 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e _column_text()].
12e10 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 39 7d 20 .**.** {H12379}
12e20 54 68 65 20 76 61 6c 75 65 73 20 69 6e 20 74 68 The values in th
12e30 65 20 70 61 7a 52 65 73 75 6c 74 20 61 72 72 61 e pazResult arra
12e40 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 y returned by [s
12e50 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
12e60 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ()].**
12e70 73 68 61 6c 6c 20 72 65 6d 61 69 6e 20 76 61 6c shall remain val
12e80 69 64 20 75 6e 74 69 6c 20 63 6c 65 61 72 65 64 id until cleared
12e90 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 by [sqlite3_fre
12ea0 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a e_table()]..**.*
12eb0 2a 20 7b 48 31 32 33 38 32 7d 20 57 68 65 6e 20 * {H12382} When
12ec0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 an error occurs
12ed0 64 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69 6f during evaluatio
12ee0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 n of [sqlite3_ge
12ef0 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 t_table()].**
12f00 20 20 20 20 20 20 20 74 68 65 20 66 75 6e 63 74 the funct
12f10 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20 2a 70 ion shall set *p
12f20 61 7a 52 65 73 75 6c 74 20 74 6f 20 4e 55 4c 4c azResult to NULL
12f30 2c 20 77 72 69 74 65 20 61 6e 20 65 72 72 6f 72 , write an error
12f40 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 message.**
12f50 20 20 20 20 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 into memory
12f60 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
12f70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
12f80 5d 2c 20 6d 61 6b 65 0a 2a 2a 20 20 20 20 20 20 ], make.**
12f90 20 20 20 20 2a 2a 70 7a 45 72 72 6d 73 67 20 70 **pzErrmsg p
12fa0 6f 69 6e 74 20 74 6f 20 74 68 61 74 20 65 72 72 oint to that err
12fb0 6f 72 20 6d 65 73 73 61 67 65 2c 20 61 6e 64 20 or message, and
12fc0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 20 20 20 20 return a.**
12fd0 20 20 20 20 20 61 70 70 72 6f 70 72 69 61 74 65 appropriate
12fe0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a [error code]..*
12ff0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 /.int sqlite3_ge
13000 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 t_table(. sqlit
13010 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
13020 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 /* An open data
13030 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 base */. const
13040 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 char *zSql,
13050 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 /* SQL to be eva
13060 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 luated */. char
13070 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 ***pazResult,
13080 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 /* Results of
13090 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 the query */. i
130a0 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 nt *pnRow,
130b0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f /* Number o
130c0 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 f result rows wr
130d0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 itten here */.
130e0 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 int *pnColumn,
130f0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 /* Number
13100 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e of result column
13110 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a s written here *
13120 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 /. char **pzErr
13130 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 msg /* Err
13140 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 or msg written h
13150 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 ere */.);.void s
13160 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
13170 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 e(char **result)
13180 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
13190 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 F: Formatted Str
131a0 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e ing Printing Fun
131b0 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 30 7d 20 ctions {H17400}
131c0 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 30 30 3e <S70000><S20000>
131d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
131e0 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c tines are workal
131f0 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 ikes of the "pri
13200 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 ntf()" family of
13210 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 functions.** fr
13220 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 om the standard
13230 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a C library..**.**
13240 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 The sqlite3_mpr
13250 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 intf() and sqlit
13260 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f e3_vmprintf() ro
13270 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 utines write the
13280 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e ir.** results in
13290 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
132a0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
132b0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 _malloc()]..** T
132c0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 he strings retur
132d0 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f ned by these two
132e0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 routines should
132f0 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 be.** released
13300 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 by [sqlite3_free
13310 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74 69 ()]. Both routi
13320 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 nes return a.**
13330 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 NULL pointer if
13340 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
13350 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 )] is unable to
13360 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a allocate enough.
13370 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c ** memory to hol
13380 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 d the resulting
13390 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e string..**.** In
133a0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
133b0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 f() routine is s
133c0 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 imilar to "snpri
133d0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 ntf()" from.** t
133e0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 he standard C li
133f0 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 brary. The resu
13400 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e lt is written in
13410 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 to the.** buffer
13420 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 supplied as the
13430 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
13440 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 r whose size is
13450 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 given by.** the
13460 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e first parameter.
13470 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f Note that the o
13480 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 rder of the.** f
13490 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 irst two paramet
134a0 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 ers is reversed
134b0 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e from snprintf().
134c0 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 This is an.**
134d0 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 historical accid
134e0 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 ent that cannot
134f0 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 be fixed without
13500 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 breaking.** bac
13510 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
13520 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f lity. Note also
13530 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e that sqlite3_sn
13540 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 printf().** retu
13550 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
13560 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 its buffer inst
13570 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 ead of the numbe
13580 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 r of.** characte
13590 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 rs actually writ
135a0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 ten into the buf
135b0 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74 fer. We admit t
135c0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 hat.** the numbe
135d0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 r of characters
135e0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 written would be
135f0 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 a more useful r
13600 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 eturn.** value b
13610 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 ut we cannot cha
13620 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e nge the implemen
13630 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 tation of sqlite
13640 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 3_snprintf().**
13650 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 now without brea
13660 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 king compatibili
13670 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e ty..**.** As lon
13680 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 g as the buffer
13690 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 size is greater
136a0 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 than zero, sqlit
136b0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
136c0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
136d0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 the buffer is a
136e0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 lways zero-termi
136f0 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 72 73 nated. The firs
13700 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 t.** parameter "
13710 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 n" is the total
13720 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 size of the buff
13730 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 er, including sp
13740 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a ace for.** the z
13750 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ero terminator.
13760 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 So the longest
13770 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 string that can
13780 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a be completely.**
13790 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 written will be
137a0 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e n-1 characters.
137b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
137c0 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d tines all implem
137d0 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f ent some additio
137e0 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a nal formatting.*
137f0 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 * options that a
13800 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f re useful for co
13810 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 nstructing SQL s
13820 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c tatements..** Al
13830 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 l of the usual p
13840 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 rintf() formatti
13850 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 ng options apply
13860 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 . In addition,
13870 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 there.** is are
13880 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 "%q", "%Q", and
13890 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a "%z" options..**
138a0 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f .** The %q optio
138b0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 n works like %s
138c0 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 in that it subst
138d0 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 itutes a null-te
138e0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 rminated.** stri
138f0 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 ng from the argu
13900 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 ment list. But
13910 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 %q also doubles
13920 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 every '\'' chara
13930 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 cter..** %q is d
13940 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 esigned for use
13950 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 inside a string
13960 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 literal. By dou
13970 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a bling each '\''.
13980 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 ** character it
13990 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 escapes that cha
139a0 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 racter and allow
139b0 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 s it to be inser
139c0 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 ted into.** the
139d0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f string..**.** Fo
139e0 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d r example, assum
139f0 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 e the string var
13a00 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 iable zText cont
13a10 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c ains text as fol
13a20 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lows:.**.** <blo
13a30 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
13a40 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 char *zText =
13a50 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 "It's a happy da
13a60 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f y!";.** </pre></
13a70 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
13a80 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 * One can use th
13a90 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 is text in an SQ
13aa0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 L statement as f
13ab0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
13ac0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
13ad0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d ** char *zSQL =
13ae0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 sqlite3_mprintf
13af0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 ("INSERT INTO ta
13b00 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 ble VALUES('%q')
13b10 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 ", zText);.** s
13b20 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 qlite3_exec(db,
13b30 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a zSQL, 0, 0, 0);.
13b40 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 ** sqlite3_free
13b50 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 (zSQL);.** </pre
13b60 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
13b70 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 *.** Because the
13b80 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e %q format strin
13b90 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 g is used, the '
13ba0 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e \'' character in
13bb0 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 zText.** is esc
13bc0 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c aped and the SQL
13bd0 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 generated is as
13be0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
13bf0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
13c00 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 >.** INSERT INT
13c10 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 O table1 VALUES(
13c20 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 'It''s a happy d
13c30 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c ay!').** </pre><
13c40 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
13c50 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 ** This is corre
13c60 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 ct. Had we used
13c70 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 %s instead of %
13c80 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 q, the generated
13c90 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 SQL.** would ha
13ca0 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 ve looked like t
13cb0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 his:.**.** <bloc
13cc0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
13cd0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 INSERT INTO tab
13ce0 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 le1 VALUES('It's
13cf0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b a happy day!');
13d00 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
13d10 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
13d20 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c is second exampl
13d30 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 e is an SQL synt
13d40 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 ax error. As a
13d50 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 general rule you
13d60 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 should.** alway
13d70 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 s use %q instead
13d80 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 of %s when inse
13d90 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 rting text into
13da0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c a string literal
13db0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f ..**.** The %Q o
13dc0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
13dd0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c %q except it al
13de0 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 so adds single q
13df0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 uotes around.**
13e00 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 the outside of t
13e10 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e he total string.
13e20 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 Additionally,
13e30 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
13e40 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d in the.** argum
13e50 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 ent list is a NU
13e60 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 LL pointer, %Q s
13e70 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 ubstitutes the t
13e80 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 ext "NULL" (with
13e90 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 out.** single qu
13ea0 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f otes) in place o
13eb0 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e f the %Q option.
13ec0 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c So, for exampl
13ed0 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 e, one could say
13ee0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
13ef0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 ote><pre>.** ch
13f00 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 ar *zSQL = sqlit
13f10 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 e3_mprintf("INSE
13f20 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 RT INTO table VA
13f30 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 LUES(%Q)", zText
13f40 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 );.** sqlite3_e
13f50 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c xec(db, zSQL, 0,
13f60 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 0, 0);.** sqli
13f70 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a te3_free(zSQL);.
13f80 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
13f90 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
13fa0 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c code above will
13fb0 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 render a correc
13fc0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 t SQL statement
13fd0 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 in the zSQL.** v
13fe0 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 ariable even if
13ff0 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 the zText variab
14000 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 le is a NULL poi
14010 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nter..**.** The
14020 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 "%z" formatting
14030 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 option works exa
14040 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77 ctly like "%s" w
14050 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 ith the.** addit
14060 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 ion that after t
14070 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 he string has be
14080 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 en read and copi
14090 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 ed into.** the r
140a0 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f esult, [sqlite3_
140b0 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 free()] is calle
140c0 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 d on the input s
140d0 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a tring. {END}.**.
140e0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
140f0 2a 0a 2a 2a 20 7b 48 31 37 34 30 33 7d 20 20 54 *.** {H17403} T
14100 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 he [sqlite3_mpri
14110 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ntf()] and [sqli
14120 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d 20 te3_vmprintf()]
14130 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 20 20 interfaces.**
14140 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 65 return e
14150 69 74 68 65 72 20 70 6f 69 6e 74 65 72 73 20 74 ither pointers t
14160 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 o zero-terminate
14170 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20 d UTF-8 strings
14180 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 20 20 20 held in.**
14190 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f 62 74 61 memory obta
141a0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 ined from [sqlit
141b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 e3_malloc()] or
141c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 69 66 NULL pointers if
141d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 .** a
141e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
141f0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 69 6c 73 _malloc()] fails
14200 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 36 7d ..**.** {H17406}
14210 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 The [sqlite3_s
14220 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 nprintf()] inter
14230 66 61 63 65 20 77 72 69 74 65 73 20 61 20 7a 65 face writes a ze
14240 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
14250 20 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 UTF-8
14260 20 73 74 72 69 6e 67 20 69 6e 74 6f 20 74 68 65 string into the
14270 20 62 75 66 66 65 72 20 70 6f 69 6e 74 65 64 20 buffer pointed
14280 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 to by the second
14290 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 parameter.**
142a0 20 20 20 20 20 20 20 20 70 72 6f 76 69 64 65 64 provided
142b0 20 74 68 61 74 20 74 68 65 20 66 69 72 73 74 20 that the first
142c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 67 72 65 parameter is gre
142d0 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a ater than zero..
142e0 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 37 7d 20 20 **.** {H17407}
142f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 The [sqlite3_snp
14300 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 rintf()] interfa
14310 63 65 20 64 6f 65 73 20 6e 6f 74 20 77 72 69 74 ce does not writ
14320 65 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20 20 e slots of.**
14330 20 20 20 20 20 20 20 20 69 74 73 20 6f 75 74 70 its outp
14340 75 74 20 62 75 66 66 65 72 20 28 74 68 65 20 73 ut buffer (the s
14350 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 29 econd parameter)
14360 20 6f 75 74 73 69 64 65 20 74 68 65 20 72 61 6e outside the ran
14370 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 ge.**
14380 6f 66 20 30 20 74 68 72 6f 75 67 68 20 4e 2d 31 of 0 through N-1
14390 20 28 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 (where N is the
143a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
143b0 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 ).** r
143c0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 egardless of the
143d0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 length of the s
143e0 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 tring.**
143f0 20 20 20 72 65 71 75 65 73 74 65 64 20 62 79 20 requested by
14400 74 68 65 20 66 6f 72 6d 61 74 20 73 70 65 63 69 the format speci
14410 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 68 61 fication..*/.cha
14420 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e r *sqlite3_mprin
14430 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e tf(const char*,.
14440 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 ..);.char *sqlit
14450 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 e3_vmprintf(cons
14460 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 t char*, va_list
14470 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 );.char *sqlite3
14480 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 _snprintf(int,ch
14490 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
144a0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ...);../*.** CA
144b0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 PI3REF: Memory A
144c0 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 llocation Subsys
144d0 74 65 6d 20 7b 48 31 37 33 30 30 7d 20 3c 53 32 tem {H17300} <S2
144e0 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0000>.**.** The
144f0 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65 SQLite core use
14500 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f s these three ro
14510 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f utines for all o
14520 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 f its own.** int
14530 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c ernal memory all
14540 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 ocation needs. "
14550 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 Core" in the pre
14560 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a vious sentence.*
14570 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 * does not inclu
14580 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 de operating-sys
14590 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 tem specific VFS
145a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
145b0 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 The.** Windows
145c0 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 VFS uses native
145d0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 malloc() and fr
145e0 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 ee() for some op
145f0 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 erations..**.**
14600 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c The sqlite3_mall
14610 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 oc() routine ret
14620 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
14630 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 o a block.** of
14640 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 memory at least
14650 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 N bytes in lengt
14660 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 h, where N is th
14670 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 e parameter..**
14680 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f If sqlite3_mallo
14690 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f c() is unable to
146a0 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 obtain sufficie
146b0 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 nt free.** memor
146c0 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 y, it returns a
146d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 NULL pointer. I
146e0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
146f0 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f N to.** sqlite3_
14700 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f malloc() is zero
14710 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 or negative the
14720 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 n sqlite3_malloc
14730 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 () returns.** a
14740 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
14750 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 .** Calling sqli
14760 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 te3_free() with
14770 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f a pointer previo
14780 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a usly returned.**
14790 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c by sqlite3_mall
147a0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f oc() or sqlite3_
147b0 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 realloc() releas
147c0 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 es that memory s
147d0 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 o.** that it mig
147e0 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 54 ht be reused. T
147f0 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 he sqlite3_free(
14800 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 ) routine is.**
14810 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 a no-op if is ca
14820 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c lled with a NULL
14830 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 pointer. Passi
14840 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ng a NULL pointe
14850 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f r.** to sqlite3_
14860 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 free() is harmle
14870 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 ss. After being
14880 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a freed, memory.*
14890 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 * should neither
148a0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 be read nor wri
148b0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 tten. Even read
148c0 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 ing previously f
148d0 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d reed.** memory m
148e0 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 ight result in a
148f0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 segmentation fa
14900 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 ult or other sev
14910 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 ere error..** Me
14920 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c mory corruption,
14930 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 a segmentation
14940 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 fault, or other
14950 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 severe error.**
14960 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 might result if
14970 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 sqlite3_free() i
14980 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 s called with a
14990 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 non-NULL pointer
149a0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 that.** was not
149b0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 obtained from s
149c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
149d0 6f 72 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 or sqlite3_free(
149e0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )..**.** The sql
149f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 ite3_realloc() i
14a00 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 nterface attempt
14a10 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a s to resize a.**
14a20 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c prior memory al
14a30 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 location to be a
14a40 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c t least N bytes,
14a50 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a where N is the.
14a60 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 ** second parame
14a70 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 ter. The memory
14a80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 allocation to b
14a90 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 e resized is the
14aa0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 first.** parame
14ab0 74 65 72 2e 20 20 49 66 20 74 68 65 20 66 69 72 ter. If the fir
14ac0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
14ad0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
14ae0 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 ).** is a NULL p
14af0 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 ointer then its
14b00 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e behavior is iden
14b10 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 tical to calling
14b20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c .** sqlite3_mall
14b30 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 oc(N) where N is
14b40 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
14b50 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
14b60 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 _realloc()..** I
14b70 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 f the second par
14b80 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
14b90 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 3_realloc() is z
14ba0 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 ero or.** negati
14bb0 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 ve then the beha
14bc0 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 vior is exactly
14bd0 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c the same as call
14be0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 ing.** sqlite3_f
14bf0 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 ree(P) where P i
14c00 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 s the first para
14c10 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
14c20 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73 _realloc()..** s
14c30 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
14c40 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
14c50 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 er to a memory a
14c60 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 llocation.** of
14c70 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 at least N bytes
14c80 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c in size or NULL
14c90 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d if sufficient m
14ca0 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c emory is unavail
14cb0 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 able..** If M is
14cc0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
14cd0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
14ce0 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 n, then min(N,M)
14cf0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 bytes.** of the
14d00 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
14d10 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 n are copied int
14d20 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 o the beginning
14d30 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e of buffer return
14d40 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 ed.** by sqlite3
14d50 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 _realloc() and t
14d60 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
14d70 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a ion is freed..**
14d80 20 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c If sqlite3_real
14d90 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 loc() returns NU
14da0 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 LL, then the pri
14db0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a or allocation.**
14dc0 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a is not freed..*
14dd0 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 *.** The memory
14de0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
14df0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 te3_malloc() and
14e00 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
14e10 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 ().** is always
14e20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 aligned to at le
14e30 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f ast an 8 byte bo
14e40 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a undary. {END}.**
14e50 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 .** The default
14e60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
14e70 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c f the memory all
14e80 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 ocation subsyste
14e90 6d 20 75 73 65 73 0a 2a 2a 20 74 68 65 20 6d 61 m uses.** the ma
14ea0 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 lloc(), realloc(
14eb0 29 20 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f ) and free() pro
14ec0 76 69 64 65 64 20 62 79 20 74 68 65 20 73 74 61 vided by the sta
14ed0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e ndard C library.
14ee0 0a 2a 2a 20 7b 48 31 37 33 38 32 7d 20 48 6f 77 .** {H17382} How
14ef0 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 ever, if SQLite
14f00 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
14f10 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d the.** SQLITE_M
14f20 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e EMORY_SIZE=<i>NN
14f30 4e 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f 63 65 N</i> C preproce
14f40 73 73 6f 72 20 6d 61 63 72 6f 20 28 77 68 65 72 ssor macro (wher
14f50 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 e <i>NNN</i>.**
14f60 69 73 20 61 6e 20 69 6e 74 65 67 65 72 29 2c 20 is an integer),
14f70 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61 then SQLite crea
14f80 74 65 20 61 20 73 74 61 74 69 63 20 61 72 72 61 te a static arra
14f90 79 20 6f 66 20 61 74 20 6c 65 61 73 74 0a 2a 2a y of at least.**
14fa0 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 <i>NNN</i> byte
14fb0 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 s in size and us
14fc0 65 73 20 74 68 61 74 20 61 72 72 61 79 20 66 6f es that array fo
14fd0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e r all of its dyn
14fe0 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 amic.** memory a
14ff0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e llocation needs.
15000 20 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e {END} Addition
15010 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 al memory alloca
15020 74 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d tor options.** m
15030 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
15040 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a uture releases..
15050 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 **.** In SQLite
15060 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e version 3.5.0 an
15070 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 d 3.5.1, it was
15080 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 possible to defi
15090 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 ne.** the SQLITE
150a0 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c _OMIT_MEMORY_ALL
150b0 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f OCATION which wo
150c0 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 uld cause the bu
150d0 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d ilt-in.** implem
150e0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 entation of thes
150f0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 e routines to be
15100 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 omitted. That
15110 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 capability.** is
15120 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 no longer provi
15130 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 ded. Only built
15140 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 -in memory alloc
15150 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 ators can be use
15160 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e d..**.** The Win
15170 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 dows OS interfac
15180 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a e layer calls.**
15190 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c the system mall
151a0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
151b0 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f directly when co
151c0 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 nverting.** file
151d0 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 names between th
151e0 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 e UTF-8 encoding
151f0 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a used by SQLite.
15200 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 ** and whatever
15210 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e filename encodin
15220 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 g is used by the
15230 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 particular Wind
15240 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 ows.** installat
15250 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c ion. Memory all
15260 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 ocation errors a
15270 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 re detected, but
15280 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 .** they are rep
15290 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 orted back as [S
152a0 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 QLITE_CANTOPEN]
152b0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f or.** [SQLITE_IO
152c0 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e ERR] rather than
152d0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e [SQLITE_NOMEM].
152e0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
152f0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 33 S:.**.** {H17303
15300 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f } The [sqlite3_
15310 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 malloc(N)] inter
15320 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 face returns eit
15330 68 65 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f her a pointer to
15340 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 .** a
15350 6e 65 77 6c 79 20 63 68 65 63 6b 65 64 2d 6f 75 newly checked-ou
15360 74 20 62 6c 6f 63 6b 20 6f 66 20 61 74 20 6c 65 t block of at le
15370 61 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 6d ast N bytes of m
15380 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 emory.**
15390 20 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74 that is 8-byt
153a0 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 69 74 e aligned, or it
153b0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 returns NULL if
153c0 20 69 74 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a it is unable.**
153d0 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 66 75 to fu
153e0 6c 66 69 6c 6c 20 74 68 65 20 72 65 71 75 65 73 lfill the reques
153f0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 34 t..**.** {H17304
15400 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f } The [sqlite3_
15410 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 malloc(N)] inter
15420 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 4e face returns a N
15430 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 0a 2a ULL pointer if.*
15440 2a 20 20 20 20 20 20 20 20 20 20 20 4e 20 69 73 * N is
15450 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 less than or eq
15460 75 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a ual to zero..**.
15470 2a 2a 20 7b 48 31 37 33 30 35 7d 20 20 54 68 65 ** {H17305} The
15480 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 [sqlite3_free(P
15490 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 6c )] interface rel
154a0 65 61 73 65 73 20 6d 65 6d 6f 72 79 20 70 72 65 eases memory pre
154b0 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 viously.**
154c0 20 20 20 20 20 72 65 74 75 72 6e 65 64 20 66 72 returned fr
154d0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
154e0 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 oc()] or [sqlite
154f0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 3_realloc()],.**
15500 20 20 20 20 20 20 20 20 20 20 20 6d 61 6b 69 6e makin
15510 67 20 69 74 20 61 76 61 69 6c 61 62 6c 65 20 66 g it available f
15520 6f 72 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 or reuse..**.**
15530 7b 48 31 37 33 30 36 7d 20 20 41 20 63 61 6c 6c {H17306} A call
15540 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 to [sqlite3_fre
15550 65 28 4e 55 4c 4c 29 5d 20 69 73 20 61 20 68 61 e(NULL)] is a ha
15560 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a rmless no-op..**
15570 0a 2a 2a 20 7b 48 31 37 33 31 30 7d 20 20 41 20 .** {H17310} A
15580 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
15590 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69 _realloc(0,N)] i
155a0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 s equivalent to
155b0 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 a call.**
155c0 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f to [sqlite3_
155d0 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a malloc(N)]..**.*
155e0 2a 20 7b 48 31 37 33 31 32 7d 20 20 41 20 63 61 * {H17312} A ca
155f0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 ll to [sqlite3_r
15600 65 61 6c 6c 6f 63 28 50 2c 30 29 5d 20 69 73 20 ealloc(P,0)] is
15610 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 equivalent to a
15620 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 call.**
15630 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 to [sqlite3_fr
15640 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ee(P)]..**.** {H
15650 31 37 33 31 35 7d 20 20 54 68 65 20 53 51 4c 69 17315} The SQLi
15660 74 65 20 63 6f 72 65 20 75 73 65 73 20 5b 73 71 te core uses [sq
15670 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c lite3_malloc()],
15680 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
15690 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 c()],.**
156a0 20 20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f and [sqlite3_
156b0 66 72 65 65 28 29 5d 20 66 6f 72 20 61 6c 6c 20 free()] for all
156c0 6f 66 20 69 74 73 20 6d 65 6d 6f 72 79 20 61 6c of its memory al
156d0 6c 6f 63 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 location and.**
156e0 20 20 20 20 20 20 20 20 20 20 64 65 61 6c 6c 6f deallo
156f0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a cation needs..**
15700 0a 2a 2a 20 7b 48 31 37 33 31 38 7d 20 20 54 68 .** {H17318} Th
15710 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c e [sqlite3_reall
15720 6f 63 28 50 2c 4e 29 5d 20 69 6e 74 65 72 66 61 oc(P,N)] interfa
15730 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 ce returns eithe
15740 72 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 r a pointer.**
15750 20 20 20 20 20 20 20 20 20 74 6f 20 61 20 62 6c to a bl
15760 6f 63 6b 20 6f 66 20 63 68 65 63 6b 65 64 2d 6f ock of checked-o
15770 75 74 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 ut memory of at
15780 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e least N bytes in
15790 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 size.**
157a0 20 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74 that is 8-byt
157b0 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 61 20 e aligned, or a
157c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
157d0 0a 2a 2a 20 7b 48 31 37 33 32 31 7d 20 20 57 68 .** {H17321} Wh
157e0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c en [sqlite3_real
157f0 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e loc(P,N)] return
15800 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 s a non-NULL poi
15810 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a nter, it first.*
15820 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 * copi
15830 65 73 20 74 68 65 20 66 69 72 73 74 20 4b 20 62 es the first K b
15840 79 74 65 73 20 6f 66 20 63 6f 6e 74 65 6e 74 20 ytes of content
15850 66 72 6f 6d 20 50 20 69 6e 74 6f 20 74 68 65 20 from P into the
15860 6e 65 77 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 newly.**
15870 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 62 6c 6f allocated blo
15880 63 6b 2c 20 77 68 65 72 65 20 4b 20 69 73 20 74 ck, where K is t
15890 68 65 20 6c 65 73 73 65 72 20 6f 66 20 4e 20 61 he lesser of N a
158a0 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a nd the size of.*
158b0 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 * the
158c0 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 buffer P..**.**
158d0 7b 48 31 37 33 32 32 7d 20 20 57 68 65 6e 20 5b {H17322} When [
158e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
158f0 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 P,N)] returns a
15900 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 non-NULL pointer
15910 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 , it first.**
15920 20 20 20 20 20 20 20 20 72 65 6c 65 61 73 65 73 releases
15930 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a the buffer P..*
15940 2a 0a 2a 2a 20 7b 48 31 37 33 32 33 7d 20 20 57 *.** {H17323} W
15950 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 hen [sqlite3_rea
15960 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 lloc(P,N)] retur
15970 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 20 62 75 66 ns NULL, the buf
15980 66 65 72 20 50 20 69 73 0a 2a 2a 20 20 20 20 20 fer P is.**
15990 20 20 20 20 20 20 6e 6f 74 20 6d 6f 64 69 66 69 not modifi
159a0 65 64 20 6f 72 20 72 65 6c 65 61 73 65 64 2e 0a ed or released..
159b0 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e **.** ASSUMPTION
159c0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 30 S:.**.** {A17350
159d0 7d 20 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 } The pointer a
159e0 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c rguments to [sql
159f0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 ite3_free()] and
15a00 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
15a10 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 c()].**
15a20 20 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 must be either
15a30 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f NULL or else po
15a40 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 inters obtained
15a50 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 from a prior.**
15a60 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61 invoca
15a70 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
15a80 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 _malloc()] or [s
15a90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
15aa0 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 20 ] that have.**
15ab0 20 20 20 20 20 20 20 20 20 6e 6f 74 20 79 65 74 not yet
15ac0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a been released..
15ad0 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 31 7d 20 20 **.** {A17351}
15ae0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
15af0 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 must not read or
15b00 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 write any part
15b10 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 of.**
15b20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 a block of memor
15b30 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 y after it has b
15b40 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 een released usi
15b50 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 ng.**
15b60 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
15b70 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
15b80 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 lloc()]..*/.void
15b90 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 *sqlite3_malloc
15ba0 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c (int);.void *sql
15bb0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 ite3_realloc(voi
15bc0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 d*, int);.void s
15bd0 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 qlite3_free(void
15be0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
15bf0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f REF: Memory Allo
15c00 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 cator Statistics
15c10 20 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 31 {H17370} <S3021
15c20 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 0>.**.** SQLite
15c30 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 provides these t
15c40 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f wo interfaces fo
15c50 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 r reporting on t
15c60 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 he status.** of
15c70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c the [sqlite3_mal
15c80 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 loc()], [sqlite3
15c90 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 _free()], and [s
15ca0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
15cb0 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 ].** routines, w
15cc0 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 hich form the bu
15cd0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c ilt-in memory al
15ce0 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 location subsyst
15cf0 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 em..**.** INVARI
15d00 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 ANTS:.**.** {H17
15d10 33 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 371} The [sqlite
15d20 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 3_memory_used()]
15d30 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
15d40 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
15d50 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 ytes.**
15d60 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 of memory curre
15d70 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 ntly outstanding
15d80 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e (malloced but n
15d90 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a ot freed)..**.**
15da0 20 7b 48 31 37 33 37 33 7d 20 54 68 65 20 5b 73 {H17373} The [s
15db0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
15dc0 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 ghwater()] routi
15dd0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d ne returns the m
15de0 61 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20 aximum.**
15df0 20 20 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c value of [sql
15e00 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
15e10 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 ()] since the hi
15e20 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a gh-water mark.**
15e30 20 20 20 20 20 20 20 20 20 20 77 61 73 20 6c 61 was la
15e40 73 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 st reset..**.**
15e50 7b 48 31 37 33 37 34 7d 20 54 68 65 20 76 61 6c {H17374} The val
15e60 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ues returned by
15e70 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
15e80 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 used()] and.**
15e90 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
15ea0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
15eb0 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 r()] include any
15ec0 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20 20 20 overhead.**
15ed0 20 20 20 20 20 20 61 64 64 65 64 20 62 79 20 53 added by S
15ee0 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 QLite in its imp
15ef0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b lementation of [
15f00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
15f10 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 ],.** b
15f20 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 ut not overhead
15f30 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 added by the any
15f40 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 underlying syst
15f50 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20 em library.**
15f60 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65 73 20 routines
15f70 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 that [sqlite3_ma
15f80 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c lloc()] may call
15f90 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 35 7d ..**.** {H17375}
15fa0 20 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 The memory high
15fb0 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 -water mark is r
15fc0 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 eset to the curr
15fd0 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 ent value of.**
15fe0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
15ff0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 3_memory_used()]
16000 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 if and only if
16010 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f the parameter to
16020 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
16030 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
16040 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 hwater()] is tru
16050 65 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 e. The value re
16060 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 turned.**
16070 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d by [sqlite3_m
16080 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
16090 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 1)] is the high-
160a0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 water mark.**
160b0 20 20 20 20 20 20 20 70 72 69 6f 72 20 74 6f 20 prior to
160c0 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 the reset..*/.sq
160d0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
160e0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
160f0 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 void);.sqlite3_i
16100 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d nt64 sqlite3_mem
16110 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e ory_highwater(in
16120 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f t resetFlag);../
16130 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 *.** CAPI3REF: P
16140 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d seudo-Random Num
16150 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 48 ber Generator {H
16160 31 37 33 39 30 7d 20 3c 53 32 30 30 30 30 3e 0a 17390} <S20000>.
16170 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e **.** SQLite con
16180 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 tains a high-qua
16190 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 lity pseudo-rand
161a0 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 om number genera
161b0 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 tor (PRNG) used
161c0 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e to.** select ran
161d0 64 6f 6d 20 52 4f 57 49 44 73 20 77 68 65 6e 20 dom ROWIDs when
161e0 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 inserting new re
161f0 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 cords into a tab
16200 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 le that.** alrea
16210 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 dy uses the larg
16220 65 73 74 20 70 6f 73 73 69 62 6c 65 20 52 4f 57 est possible ROW
16230 49 44 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 ID. The PRNG is
16240 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a also used for.*
16250 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 * the build-in r
16260 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 andom() and rand
16270 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e omblob() SQL fun
16280 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e ctions. This in
16290 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a terface allows.*
162a0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 * applications t
162b0 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d o access the sam
162c0 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 e PRNG for other
162d0 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a purposes..**.**
162e0 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 A call to this
162f0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e routine stores N
16300 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d bytes of random
16310 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 ness into buffer
16320 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 P..**.** The fi
16330 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f rst time this ro
16340 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 utine is invoked
16350 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 (either interna
16360 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 lly or by.** the
16370 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 application) th
16380 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 e PRNG is seeded
16390 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 using randomnes
163a0 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 s obtained.** fr
163b0 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 om the xRandomne
163c0 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 ss method of the
163d0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 default [sqlite
163e0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 3_vfs] object..*
163f0 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 * On all subsequ
16400 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c ent invocations,
16410 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 the pseudo-rand
16420 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 omness is genera
16430 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c ted.** internall
16440 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 y and without re
16450 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 course to the [s
16460 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e qlite3_vfs] xRan
16470 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f domness.** metho
16480 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 d..**.** INVARIA
16490 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 NTS:.**.** {H173
164a0 39 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 92} The [sqlite3
164b0 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c 50 29 _randomness(N,P)
164c0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 ] interface writ
164d0 65 73 20 4e 20 62 79 74 65 73 20 6f 66 0a 2a 2a es N bytes of.**
164e0 20 20 20 20 20 20 20 20 20 20 68 69 67 68 2d 71 high-q
164f0 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 uality pseudo-ra
16500 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 ndomness into bu
16510 66 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20 ffer P..*/.void
16520 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 sqlite3_randomne
16530 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a ss(int N, void *
16540 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 P);../*.** CAPI3
16550 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d REF: Compile-Tim
16560 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 e Authorization
16570 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 35 30 Callbacks {H1250
16580 30 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a 0} <S70100>.**.*
16590 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 * This routine r
165a0 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f egisters a autho
165b0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 rizer callback w
165c0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 ith a particular
165d0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
165e0 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c nnection], suppl
165f0 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 ied in the first
16600 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 argument..** Th
16610 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
16620 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
16630 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e as SQL statemen
16640 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d ts are being com
16650 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c piled.** by [sql
16660 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
16670 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 or its variants
16680 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
16690 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 _v2()],.** [sqli
166a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
166b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 and [sqlite3_pr
166c0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 epare16_v2()].
166d0 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f At various.** po
166e0 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 ints during the
166f0 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 compilation proc
16700 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 ess, as logic is
16710 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a being created.*
16720 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 * to perform var
16730 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 ious actions, th
16740 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
16750 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
16760 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 to.** see if th
16770 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 ose actions are
16780 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75 allowed. The au
16790 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
167a0 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 k should.** retu
167b0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 rn [SQLITE_OK] t
167c0 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 o allow the acti
167d0 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f on, [SQLITE_IGNO
167e0 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 RE] to disallow
167f0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 the.** specific
16800 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 action but allow
16810 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
16820 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 nt to continue t
16830 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 o be.** compiled
16840 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e , or [SQLITE_DEN
16850 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 Y] to cause the
16860 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 entire SQL state
16870 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 ment to be.** re
16880 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 jected with an e
16890 72 72 6f 72 2e 20 20 49 66 20 74 68 65 20 61 75 rror. If the au
168a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
168b0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 k returns.** any
168c0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 value other tha
168d0 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 n [SQLITE_IGNORE
168e0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 ], [SQLITE_OK],
168f0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d or [SQLITE_DENY]
16900 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 .** then the [sq
16910 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
16920 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e ()] or equivalen
16930 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 t call that trig
16940 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 gered.** the aut
16950 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 horizer will fai
16960 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 l with an error
16970 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 message..**.** W
16980 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
16990 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
169a0 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 _OK], that means
169b0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a the operation.*
169c0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f * requested is o
169d0 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c k. When the cal
169e0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 lback returns [S
169f0 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 QLITE_DENY], the
16a00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
16a10 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 pare_v2()] or eq
16a20 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 uivalent call th
16a30 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 at triggered the
16a40 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 .** authorizer w
16a50 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e ill fail with an
16a60 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 error message e
16a70 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a xplaining that.*
16a80 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 * access is deni
16a90 65 64 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 ed. If the auth
16aa0 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b orizer code is [
16ab0 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 SQLITE_READ].**
16ac0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b and the callback
16ad0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
16ae0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 _IGNORE] then th
16af0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
16b00 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d tatement] statem
16b10 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 ent is construct
16b20 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 ed to substitute
16b30 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 .** a NULL value
16b40 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 in place of the
16b50 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 table column th
16b60 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a at would have.**
16b70 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 been read if [S
16b80 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 QLITE_OK] had be
16b90 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 en returned. Th
16ba0 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 e [SQLITE_IGNORE
16bb0 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 ].** return can
16bc0 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 be used to deny
16bd0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 an untrusted use
16be0 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 r access to indi
16bf0 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e vidual.** column
16c00 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a s of a table..**
16c10 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 .** The first pa
16c20 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 rameter to the a
16c30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
16c40 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 ck is a copy of
16c50 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 the third.** par
16c60 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
16c70 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
16c80 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 izer() interface
16c90 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 . The second par
16ca0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ameter.** to the
16cb0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
16cc0 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f integer [SQLITE_
16cd0 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f COPY | action co
16ce0 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 de] that specifi
16cf0 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 es.** the partic
16d00 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 ular action to b
16d10 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 e authorized. Th
16d20 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 e third through
16d30 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 sixth parameters
16d40 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 .** to the callb
16d50 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 ack are zero-ter
16d60 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 minated strings
16d70 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 that contain add
16d80 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 itional.** detai
16d90 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 ls about the act
16da0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 ion to be author
16db0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 ized..**.** An a
16dc0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 uthorizer is use
16dd0 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f d when [sqlite3_
16de0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 prepare | prepar
16df0 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 ing].** SQL stat
16e00 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 ements from an u
16e10 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c ntrusted source,
16e20 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 to ensure that
16e30 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
16e40 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 ts.** do not try
16e50 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 to access data
16e60 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c they are not all
16e70 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 owed to see, or
16e80 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 that they do not
16e90 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 .** try to execu
16ea0 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 te malicious sta
16eb0 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d tements that dam
16ec0 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 age the database
16ed0 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c . For.** exampl
16ee0 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f e, an applicatio
16ef0 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 n may allow a us
16f00 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 er to enter arbi
16f10 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 trary.** SQL que
16f20 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 ries for evaluat
16f30 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 ion by a databas
16f40 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c e. But the appl
16f50 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 ication does.**
16f60 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 not want the use
16f70 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 r to be able to
16f80 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 make arbitrary c
16f90 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a hanges to the.**
16fa0 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 database. An a
16fb0 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 uthorizer could
16fc0 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 then be put in p
16fd0 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a lace while the.*
16fe0 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 * user-entered S
16ff0 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c QL is being [sql
17000 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 ite3_prepare | p
17010 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a repared] that.**
17020 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 disallows every
17030 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 thing except [SE
17040 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 LECT] statements
17050 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 ..**.** Applicat
17060 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 ions that need t
17070 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 o process SQL fr
17080 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 om untrusted sou
17090 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c rces.** might al
170a0 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 so consider lowe
170b0 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 ring resource li
170c0 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 mits using [sqli
170d0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 te3_limit()].**
170e0 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 and limiting dat
170f0 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 abase size using
17100 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 the [max_page_c
17110 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a ount] [PRAGMA].*
17120 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f * in addition to
17130 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 using an author
17140 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 izer..**.** Only
17150 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 a single author
17160 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 izer can be in p
17170 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 lace on a databa
17180 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
17190 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 at a time. Eac
171a0 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 h call to sqlite
171b0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
171c0 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a overrides the.*
171d0 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e * previous call.
171e0 20 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 Disable the au
171f0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 thorizer by inst
17200 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 alling a NULL ca
17210 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 llback..** The a
17220 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 uthorizer is dis
17230 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
17240 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
17250 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 t the authorizer
17260 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
17270 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 oked only during
17280 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
17290 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 pare()] or its v
172a0 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 ariants. Author
172b0 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a ization is not.*
172c0 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 * performed duri
172d0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 ng statement eva
172e0 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 luation in [sqli
172f0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a te3_step()]..**.
17300 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
17310 2a 0a 2a 2a 20 7b 48 31 32 35 30 31 7d 20 54 68 *.** {H12501} Th
17320 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 e [sqlite3_set_a
17330 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29 uthorizer(D,...)
17340 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ] interface regi
17350 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20 20 20 sters a.**
17360 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 authorizer c
17370 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64 61 74 allback with dat
17380 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
17390 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 D..**.** {H1250
173a0 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 2} The authorize
173b0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
173c0 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 voked as SQL sta
173d0 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20 tements are.**
173e0 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 63 6f being co
173f0 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 mpiled..**.** {H
17400 31 32 35 30 33 7d 20 49 66 20 74 68 65 20 61 75 12503} If the au
17410 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
17420 6b 20 72 65 74 75 72 6e 73 20 61 6e 79 20 76 61 k returns any va
17430 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a lue other than.*
17440 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 * [SQLI
17450 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c TE_IGNORE], [SQL
17460 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c ITE_OK], or [SQL
17470 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 6e 0a ITE_DENY], then.
17480 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
17490 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
174a0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 _v2()] or equiva
174b0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 63 lent call that c
174c0 61 75 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 aused.**
174d0 20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 the authorizer
174e0 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e callback to run
174f0 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 shall fail with
17500 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 an.**
17510 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 [SQLITE_ERROR] e
17520 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e rror code and an
17530 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 appropriate err
17540 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a or message..**.*
17550 2a 20 7b 48 31 32 35 30 34 7d 20 57 68 65 6e 20 * {H12504} When
17560 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
17570 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
17580 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 [SQLITE_OK], the
17590 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 operation.**
175a0 20 20 20 20 20 20 20 64 65 73 63 72 69 62 65 64 described
175b0 20 69 73 20 70 72 6f 63 65 73 73 65 64 20 6e 6f is processed no
175c0 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 rmally..**.** {H
175d0 31 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65 20 12505} When the
175e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
175f0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ack returns [SQL
17600 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a ITE_DENY], the.*
17610 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
17620 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
17630 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 ] or equivalent
17640 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 call that caused
17650 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
17660 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
17670 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c back to run shal
17680 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 l fail.**
17690 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 with an [SQLI
176a0 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 TE_ERROR] error
176b0 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f code and an erro
176c0 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 r message.**
176d0 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67 explaining
176e0 20 74 68 61 74 20 61 63 63 65 73 73 20 69 73 20 that access is
176f0 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 denied..**.** {H
17700 31 32 35 30 36 7d 20 49 66 20 74 68 65 20 61 75 12506} If the au
17710 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74 thorizer code (t
17720 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
17730 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a to the authoriz
17740 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 er.** c
17750 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c allback) is [SQL
17760 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68 ITE_READ] and th
17770 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
17780 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a lback returns.**
17790 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 [SQLIT
177a0 45 5f 49 47 4e 4f 52 45 5d 2c 20 74 68 65 6e 20 E_IGNORE], then
177b0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 the prepared sta
177c0 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 tement is constr
177d0 75 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 ucted to.**
177e0 20 20 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55 insert a NU
177f0 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 LL value in plac
17800 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 e of the table c
17810 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 olumn that would
17820 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 have.**
17830 20 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b been read if [
17840 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 SQLITE_OK] had b
17850 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a een returned..**
17860 0a 2a 2a 20 7b 48 31 32 35 30 37 7d 20 49 66 20 .** {H12507} If
17870 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
17880 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 ode (the 2nd par
17890 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 ameter to the au
178a0 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 thorizer.**
178b0 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 callback) i
178c0 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 s anything other
178d0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45 than [SQLITE_RE
178e0 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 AD], then.**
178f0 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f a return o
17900 66 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 f [SQLITE_IGNORE
17910 5d 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 65 ] has the same e
17920 66 66 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45 ffect as [SQLITE
17930 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 _DENY]..**.** {H
17940 31 32 35 31 30 7d 20 54 68 65 20 66 69 72 73 74 12510} The first
17950 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
17960 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
17970 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 lback is a copy
17980 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 of.** t
17990 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
179a0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 er to the [sqlit
179b0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
179c0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a r()] interface..
179d0 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 31 7d 20 54 **.** {H12511} T
179e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
179f0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 ter to the callb
17a00 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ack is an intege
17a10 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 r.** [S
17a20 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 QLITE_COPY | act
17a30 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 ion code] that s
17a40 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72 pecifies the par
17a50 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a ticular action.*
17a60 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 62 65 * to be
17a70 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a authorized..**.
17a80 2a 2a 20 7b 48 31 32 35 31 32 7d 20 54 68 65 20 ** {H12512} The
17a90 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 third through si
17aa0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 xth parameters t
17ab0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 o the callback a
17ac0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a re.** z
17ad0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ero-terminated s
17ae0 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 trings that cont
17af0 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ain.**
17b00 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 additional detai
17b10 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 ls about the act
17b20 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 ion to be author
17b30 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ized..**.** {H12
17b40 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 520} Each call t
17b50 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 o [sqlite3_set_a
17b60 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65 uthorizer()] ove
17b70 72 72 69 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 rrides.**
17b80 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c any previousl
17b90 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75 74 68 y installed auth
17ba0 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 orizer..**.** {H
17bb0 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75 12521} A NULL au
17bc0 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74 thorizer means t
17bd0 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61 hat no authoriza
17be0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 tion.**
17bf0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
17c00 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 oked..**.** {H12
17c10 35 32 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74 522} The default
17c20 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e authorizer is N
17c30 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ULL..*/.int sqli
17c40 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
17c50 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a er(. sqlite3*,.
17c60 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 int (*xAuth)(v
17c70 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 oid*,int,const c
17c80 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
17c90 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e ,const char*,con
17ca0 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 st char*),. voi
17cb0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a d *pUserData.);.
17cc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
17cd0 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 Authorizer Retu
17ce0 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30 rn Codes {H12590
17cf0 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a } <H12500>.**.**
17d00 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
17d10 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 t_authorizer | a
17d20 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
17d30 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 ck function] mus
17d40 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 t.** return eith
17d50 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f er [SQLITE_OK] o
17d60 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 r one of these t
17d70 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 wo constants in
17d80 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e order.** to sign
17d90 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 al SQLite whethe
17da0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 r or not the act
17db0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 ion is permitted
17dc0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 . See the.** [s
17dd0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
17de0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
17df0 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e er documentation
17e00 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c ] for additional
17e10 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e .** information.
17e20 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
17e30 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a TE_DENY 1 /*
17e40 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 Abort the SQL s
17e50 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e tatement with an
17e60 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e error */.#defin
17e70 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 e SQLITE_IGNORE
17e80 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 2 /* Don't all
17e90 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 ow access, but d
17ea0 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e on't generate an
17eb0 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a error */../*.**
17ec0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f CAPI3REF: Autho
17ed0 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 rizer Action Cod
17ee0 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 es {H12550} <H12
17ef0 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 500>.**.** The [
17f00 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
17f10 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 orizer()] interf
17f20 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 ace registers a
17f30 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
17f40 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 n.** that is inv
17f50 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a oked to authoriz
17f60 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 e certain SQL st
17f70 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e atement actions.
17f80 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 The.** second
17f90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
17fa0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
17fb0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 integer code tha
17fc0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 t specifies.** w
17fd0 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 hat action is be
17fe0 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 ing authorized.
17ff0 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 These are the i
18000 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f nteger action co
18010 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 des that.** the
18020 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
18030 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 ack may be passe
18040 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 d..**.** These a
18050 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 ction code value
18060 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b s signify what k
18070 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e ind of operation
18080 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 is to be.** aut
18090 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 horized. The 3r
180a0 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 d and 4th parame
180b0 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 ters to the auth
180c0 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c orization.** cal
180d0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 lback function w
180e0 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 ill be parameter
180f0 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 s or NULL depend
18100 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 ing on which of
18110 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 these.** codes i
18120 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 s used as the se
18130 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 cond parameter.
18140 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 The 5th paramet
18150 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 er to the.** aut
18160 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
18170 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
18180 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d the database ("m
18190 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a ain", "temp",.**
181a0 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 etc.) if applic
181b0 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 able. The 6th p
181c0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
181d0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
181e0 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 ack.** is the na
181f0 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d me of the inner-
18200 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 most trigger or
18210 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 view that is res
18220 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 ponsible for.**
18230 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d the access attem
18240 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 pt or NULL if th
18250 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 is access attemp
18260 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 t is directly fr
18270 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 om.** top-level
18280 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 SQL code..**.**
18290 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
182a0 2a 20 7b 48 31 32 35 35 31 7d 20 54 68 65 20 73 * {H12551} The s
182b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
182c0 74 6f 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 to an.**
182d0 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 [sqlite3_set_a
182e0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 uthorizer | auth
182f0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d orizer callback]
18300 20 69 73 20 61 6c 77 61 79 73 20 61 6e 20 69 6e is always an in
18310 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 teger.**
18320 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c [SQLITE_COPY |
18330 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 authorizer code
18340 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 ] that specifies
18350 20 77 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 what action.**
18360 20 20 20 20 20 20 20 20 20 69 73 20 62 65 69 6e is bein
18370 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a g authorized..**
18380 0a 2a 2a 20 7b 48 31 32 35 35 32 7d 20 54 68 65 .** {H12552} The
18390 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 3rd and 4th par
183a0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 0a 2a ameters to the.*
183b0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
183c0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
183d0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 61 74 69 er | authorizati
183e0 6f 6e 20 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20 on callback].**
183f0 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 62 65 will be
18400 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e parameters or N
18410 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ULL depending on
18420 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 which.**
18430 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 [SQLITE_COPY
18440 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 | authorizer cod
18450 65 5d 20 69 73 20 75 73 65 64 20 61 73 20 74 68 e] is used as th
18460 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
18470 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 er..**.** {H1255
18480 33 7d 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 3} The 5th param
18490 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 eter to the.**
184a0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
184b0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
184c0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c | authorizer cal
184d0 6c 62 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 lback] is the na
184e0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f me.** o
184f0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 f the database (
18500 65 78 61 6d 70 6c 65 3a 20 22 6d 61 69 6e 22 2c example: "main",
18510 20 22 74 65 6d 70 22 2c 20 65 74 63 2e 29 20 69 "temp", etc.) i
18520 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a f applicable..**
18530 0a 2a 2a 20 7b 48 31 32 35 35 34 7d 20 54 68 65 .** {H12554} The
18540 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6th parameter t
18550 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 o the.**
18560 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 [sqlite3_set_a
18570 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 uthorizer | auth
18580 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d orizer callback]
18590 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 is the name.**
185a0 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 of the
185b0 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 inner-most trigg
185c0 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 er or view that
185d0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
185e0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 or.** t
185f0 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 he access attemp
18600 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 t or NULL if thi
18610 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 s access attempt
18620 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f is directly fro
18630 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f m.** to
18640 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 p-level SQL code
18650 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ..*/./**********
18660 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
18670 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
18680 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a * 3rd **********
18690 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a ** 4th *********
186a0 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 **/.#define SQLI
186b0 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 TE_CREATE_INDEX
186c0 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 1 /*
186d0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
186e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
186f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18700 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 E_CREATE_TABLE
18710 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 2 /* T
18720 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
18730 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
18740 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
18750 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 _CREATE_TEMP_IND
18760 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e EX 3 /* In
18770 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
18780 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
18790 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
187a0 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c CREATE_TEMP_TABL
187b0 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 E 4 /* Tab
187c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
187d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
187e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
187f0 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 REATE_TEMP_TRIGG
18800 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 ER 5 /* Trig
18810 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
18820 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
18830 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
18840 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 EATE_TEMP_VIEW
18850 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 6 /* View
18860 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
18870 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
18880 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
18890 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 ATE_TRIGGER
188a0 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 7 /* Trigge
188b0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
188c0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
188d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
188e0 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 TE_VIEW
188f0 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 8 /* View Na
18900 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
18910 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
18920 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 ine SQLITE_DELET
18930 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
18940 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 9 /* Table Na
18950 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
18960 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
18970 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 ne SQLITE_DROP_I
18980 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 NDEX 1
18990 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 0 /* Index Nam
189a0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
189b0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
189c0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 e SQLITE_DROP_TA
189d0 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 BLE 11
189e0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
189f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
18a00 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
18a10 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
18a20 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 P_INDEX 12
18a30 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
18a40 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
18a50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
18a60 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
18a70 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 _TABLE 13
18a80 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
18a90 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
18aa0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
18ab0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
18ac0 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 TRIGGER 14
18ad0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
18ae0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
18af0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
18b00 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 LITE_DROP_TEMP_V
18b10 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f IEW 15 /
18b20 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
18b30 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
18b40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
18b50 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 ITE_DROP_TRIGGER
18b60 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 16 /*
18b70 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
18b80 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
18b90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18ba0 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 TE_DROP_VIEW
18bb0 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 17 /*
18bc0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
18bd0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
18be0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18bf0 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 E_INSERT
18c00 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 18 /* T
18c10 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
18c20 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
18c30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
18c40 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 _PRAGMA
18c50 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 19 /* Pr
18c60 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 agma Name 1s
18c70 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f t arg or NULL */
18c80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18c90 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 READ
18ca0 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 20 /* Tab
18cb0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c le Name Col
18cc0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a umn Name */.
18cd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
18ce0 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 ELECT
18cf0 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 21 /* NULL
18d00 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c NULL
18d10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
18d20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 define SQLITE_TR
18d30 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 ANSACTION
18d40 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 22 /* NULL
18d50 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 NULL
18d60 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
18d70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 efine SQLITE_UPD
18d80 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ATE
18d90 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 23 /* Table
18da0 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e Name Column
18db0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
18dc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 fine SQLITE_ATTA
18dd0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CH
18de0 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 24 /* Filenam
18df0 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 e NULL
18e00 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
18e10 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 ine SQLITE_DETAC
18e20 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
18e30 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 25 /* Database
18e40 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 Name NULL
18e50 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
18e60 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f ne SQLITE_ALTER_
18e70 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 TABLE 2
18e80 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6 /* Database
18e90 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d Name Table Nam
18ea0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
18eb0 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 e SQLITE_REINDEX
18ec0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 27
18ed0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
18ee0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
18ef0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
18f00 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 SQLITE_ANALYZE
18f10 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 28
18f20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
18f30 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
18f40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
18f50 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 SQLITE_CREATE_VT
18f60 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 ABLE 29
18f70 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
18f80 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 Module Name
18f90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
18fa0 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c QLITE_DROP_VTABL
18fb0 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 E 30
18fc0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
18fd0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 Module Name
18fe0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
18ff0 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 LITE_FUNCTION
19000 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 31 /
19010 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 * Function Name
19020 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
19030 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
19040 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 ITE_COPY
19050 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 0 /*
19060 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 No longer used
19070 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
19080 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 EF: Tracing And
19090 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 Profiling Functi
190a0 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c 53 36 ons {H12280} <S6
190b0 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 0400>.**.** Thes
190c0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 e routines regis
190d0 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e ter callback fun
190e0 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 ctions that can
190f0 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 be used for.** t
19100 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 racing and profi
19110 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 ling the executi
19120 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d on of SQL statem
19130 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ents..**.** The
19140 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
19150 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 n registered by
19160 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 sqlite3_trace()
19170 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a is invoked at.**
19180 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 various times w
19190 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 hen an SQL state
191a0 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 ment is being ru
191b0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 n by [sqlite3_st
191c0 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 ep()]..** The ca
191d0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 llback returns a
191e0 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 UTF-8 rendering
191f0 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 of the SQL stat
19200 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73 ement text.** as
19210 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 the statement f
19220 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 irst begins exec
19230 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e uting. Addition
19240 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63 al callbacks occ
19250 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 ur.** as each tr
19260 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 iggered subprogr
19270 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 am is entered.
19280 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f The callbacks fo
19290 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f r triggers.** co
192a0 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 ntain a UTF-8 SQ
192b0 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 L comment that i
192c0 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 dentifies the tr
192d0 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 igger..**.** The
192e0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
192f0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 on registered by
19300 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 sqlite3_profile
19310 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a () is invoked.**
19320 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 as each SQL sta
19330 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e tement finishes.
19340 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 The profile ca
19350 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a llback contains.
19360 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 ** the original
19370 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 statement text a
19380 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f nd an estimate o
19390 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d f wall-clock tim
193a0 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 e.** of how long
193b0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 that statement
193c0 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a took to run..**.
193d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 ** The sqlite3_p
193e0 72 6f 66 69 6c 65 28 29 20 41 50 49 20 69 73 20 rofile() API is
193f0 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 currently consid
19400 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 ered experimenta
19410 6c 20 61 6e 64 0a 2a 2a 20 69 73 20 73 75 62 6a l and.** is subj
19420 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 ect to change or
19430 20 72 65 6d 6f 76 61 6c 20 69 6e 20 61 20 66 75 removal in a fu
19440 74 75 72 65 20 72 65 6c 65 61 73 65 2e 0a 2a 2a ture release..**
19450 0a 2a 2a 20 54 68 65 20 74 72 69 67 67 65 72 20 .** The trigger
19460 72 65 70 6f 72 74 69 6e 67 20 66 65 61 74 75 72 reporting featur
19470 65 20 6f 66 20 74 68 65 20 74 72 61 63 65 20 63 e of the trace c
19480 61 6c 6c 62 61 63 6b 20 69 73 20 63 6f 6e 73 69 allback is consi
19490 64 65 72 65 64 0a 2a 2a 20 65 78 70 65 72 69 6d dered.** experim
194a0 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 ental and is sub
194b0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f ject to change o
194c0 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 r removal in fut
194d0 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a ure releases..**
194e0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 Future versions
194f0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 of SQLite might
19500 20 61 6c 73 6f 20 61 64 64 20 6e 65 77 20 74 72 also add new tr
19510 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 ace callback.**
19520 69 6e 76 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a invocations..**.
19530 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
19540 2a 0a 2a 2a 20 7b 48 31 32 32 38 31 7d 20 54 68 *.** {H12281} Th
19550 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
19560 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 ion registered b
19570 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 y [sqlite3_trace
19580 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 ()] is.**
19590 20 20 20 77 68 65 6e 65 76 65 72 20 61 6e 20 53 whenever an S
195a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 QL statement fir
195b0 73 74 20 62 65 67 69 6e 73 20 74 6f 20 65 78 65 st begins to exe
195c0 63 75 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 cute and.**
195d0 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 61 20 whenever a
195e0 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 trigger subprogr
195f0 61 6d 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 am first begins
19600 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 to run..**.** {H
19610 31 32 32 38 32 7d 20 45 61 63 68 20 63 61 6c 6c 12282} Each call
19620 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 to [sqlite3_tra
19630 63 65 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 ce()] overrides
19640 74 68 65 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a the previously.*
19650 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 * regis
19660 74 65 72 65 64 20 74 72 61 63 65 20 63 61 6c 6c tered trace call
19670 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 back..**.** {H12
19680 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72 61 63 283} A NULL trac
19690 65 20 63 61 6c 6c 62 61 63 6b 20 64 69 73 61 62 e callback disab
196a0 6c 65 73 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a les tracing..**.
196b0 2a 2a 20 7b 48 31 32 32 38 34 7d 20 54 68 65 20 ** {H12284} The
196c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
196d0 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c o the trace call
196e0 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f back is a copy o
196f0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 f.** th
19700 65 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 e pointer which
19710 77 61 73 20 74 68 65 20 33 72 64 20 61 72 67 75 was the 3rd argu
19720 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
19730 5f 74 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a _trace()]..**.**
19740 20 7b 48 31 32 32 38 35 7d 20 54 68 65 20 73 65 {H12285} The se
19750 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
19760 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 the trace callb
19770 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 ack is a.**
19780 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e zero-termin
19790 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e ated UTF-8 strin
197a0 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 g containing the
197b0 20 6f 72 69 67 69 6e 61 6c 20 74 65 78 74 0a 2a original text.*
197c0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 * of th
197d0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
197e0 61 73 20 69 74 20 77 61 73 20 70 61 73 73 65 64 as it was passed
197f0 20 69 6e 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 into [sqlite3_p
19800 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 repare_v2()].**
19810 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 or the
19820 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20 61 equivalent, or a
19830 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e n SQL comment in
19840 64 69 63 61 74 69 6e 67 20 74 68 65 20 62 65 67 dicating the beg
19850 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 inning.**
19860 20 20 20 6f 66 20 61 20 74 72 69 67 67 65 72 20 of a trigger
19870 73 75 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a subprogram..**.*
19880 2a 20 7b 48 31 32 32 38 37 7d 20 54 68 65 20 63 * {H12287} The c
19890 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
198a0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b registered by [
198b0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 sqlite3_profile(
198c0 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a )] is invoked.**
198d0 20 20 20 20 20 20 20 20 20 20 61 73 20 65 61 63 as eac
198e0 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 h SQL statement
198f0 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 finishes..**.**
19900 7b 48 31 32 32 38 38 7d 20 54 68 65 20 66 69 72 {H12288} The fir
19910 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
19920 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c the profile call
19930 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f back is a copy o
19940 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 f.** th
19950 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
19960 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 to [sqlite3_prof
19970 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ile()]..**.** {H
19980 31 32 32 38 39 7d 20 54 68 65 20 73 65 63 6f 6e 12289} The secon
19990 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
199a0 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 he profile callb
199b0 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 ack is a.**
199c0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e zero-termin
199d0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e ated UTF-8 strin
199e0 67 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 g that contains
199f0 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 74 65 78 the complete tex
19a00 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 t of.**
19a10 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
19a20 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 72 6f nt as it was pro
19a30 63 65 73 73 65 64 20 62 79 20 5b 73 71 6c 69 74 cessed by [sqlit
19a40 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
19a50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
19a60 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a the equivalent..
19a70 2a 2a 0a 2a 2a 20 7b 48 31 32 32 39 30 7d 20 54 **.** {H12290} T
19a80 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
19a90 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c er to the profil
19aa0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e e callback is an
19ab0 20 65 73 74 69 6d 61 74 65 0a 2a 2a 20 20 20 20 estimate.**
19ac0 20 20 20 20 20 20 6f 66 20 74 68 65 20 6e 75 6d of the num
19ad0 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e ber of nanosecon
19ae0 64 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b ds of wall-clock
19af0 20 74 69 6d 65 20 72 65 71 75 69 72 65 64 20 74 time required t
19b00 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 75 o.** ru
19b10 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d n the SQL statem
19b20 65 6e 74 20 66 72 6f 6d 20 73 74 61 72 74 20 74 ent from start t
19b30 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a 76 6f 69 o finish..*/.voi
19b40 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 d *sqlite3_trace
19b50 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 (sqlite3*, void(
19b60 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 *xTrace)(void*,c
19b70 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 onst char*), voi
19b80 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 d*);.void *sqlit
19b90 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 e3_profile(sqlit
19ba0 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 e3*,. void(*xP
19bb0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f rofile)(void*,co
19bc0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 nst char*,sqlite
19bd0 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 3_uint64), void*
19be0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
19bf0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 EF: Query Progre
19c00 73 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 ss Callbacks {H1
19c10 32 39 31 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2910} <S60400>.*
19c20 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
19c30 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 e configures a c
19c40 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
19c50 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 - the.** progre
19c60 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 ss callback - th
19c70 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 at is invoked pe
19c80 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e riodically durin
19c90 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e g long.** runnin
19ca0 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 g calls to [sqli
19cb0 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 te3_exec()], [sq
19cc0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e lite3_step()] an
19cd0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 d.** [sqlite3_ge
19ce0 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 t_table()]. An
19cf0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 example use for
19d00 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 this.** interfac
19d10 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 e is to keep a G
19d20 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e UI updated durin
19d30 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e g a large query.
19d40 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 .**.** If the pr
19d50 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 ogress callback
19d60 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
19d70 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 , the operation
19d80 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 is.** interrupte
19d90 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 d. This feature
19da0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
19db0 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 implement a.** "
19dc0 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f Cancel" button o
19dd0 6e 20 61 20 47 55 49 20 64 69 61 6c 6f 67 20 62 n a GUI dialog b
19de0 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 ox..**.** INVARI
19df0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ANTS:.**.** {H12
19e00 39 31 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 911} The callbac
19e10 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 k function regis
19e20 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 tered by sqlite3
19e30 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 _progress_handle
19e40 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 r().**
19e50 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f is invoked perio
19e60 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c dically during l
19e70 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c ong running call
19e80 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 s to.**
19e90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
19ea0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 32 ]..**.** {H12912
19eb0 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 } The progress c
19ec0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
19ed0 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 ed once for ever
19ee0 79 20 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20 20 y N virtual.**
19ef0 20 20 20 20 20 20 20 20 6d 61 63 68 69 6e 65 20 machine
19f00 6f 70 63 6f 64 65 73 2c 20 77 68 65 72 65 20 4e opcodes, where N
19f10 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 is the second a
19f20 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 rgument to.**
19f30 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 the [sqli
19f40 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e te3_progress_han
19f50 64 6c 65 72 28 29 5d 20 63 61 6c 6c 20 74 68 61 dler()] call tha
19f60 74 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 t registered.**
19f70 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61 6c the cal
19f80 6c 62 61 63 6b 2e 20 20 49 66 20 4e 20 69 73 20 lback. If N is
19f90 6c 65 73 73 20 74 68 61 6e 20 31 2c 20 73 71 6c less than 1, sql
19fa0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 ite3_progress_ha
19fb0 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20 ndler().**
19fc0 20 20 20 20 61 63 74 73 20 61 73 20 69 66 20 61 acts as if a
19fd0 20 4e 55 4c 4c 20 70 72 6f 67 72 65 73 73 20 68 NULL progress h
19fe0 61 6e 64 6c 65 72 20 68 61 64 20 62 65 65 6e 20 andler had been
19ff0 73 70 65 63 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a specified..**.**
1a000 20 7b 48 31 32 39 31 33 7d 20 54 68 65 20 70 72 {H12913} The pr
1a010 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 ogress callback
1a020 69 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69 itself is identi
1a030 66 69 65 64 20 62 79 20 74 68 65 20 74 68 69 72 fied by the thir
1a040 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 d.** ar
1a050 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
1a060 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 3_progress_handl
1a070 65 72 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 er()..**.** {H12
1a080 39 31 34 7d 20 54 68 65 20 66 6f 75 72 74 68 20 914} The fourth
1a090 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
1a0a0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e te3_progress_han
1a0b0 64 6c 65 72 28 29 20 69 73 20 61 0a 2a 2a 20 20 dler() is a.**
1a0c0 20 20 20 20 20 20 20 20 76 6f 69 64 20 70 6f 69 void poi
1a0d0 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 nter passed to t
1a0e0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c he progress call
1a0f0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 back.**
1a100 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 function each t
1a110 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 ime it is invoke
1a120 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 35 d..**.** {H12915
1a130 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b } If a call to [
1a140 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1a150 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77 65 72 results in fewer
1a160 20 74 68 61 6e 20 4e 20 6f 70 63 6f 64 65 73 0a than N opcodes.
1a170 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 69 6e ** bein
1a180 67 20 65 78 65 63 75 74 65 64 2c 20 74 68 65 6e g executed, then
1a190 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 the progress ca
1a1a0 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20 llback is never
1a1b0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b invoked..**.** {
1a1c0 48 31 32 39 31 36 7d 20 45 76 65 72 79 20 63 61 H12916} Every ca
1a1d0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 ll to [sqlite3_p
1a1e0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 rogress_handler(
1a1f0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f )].** o
1a200 76 65 72 77 72 69 74 65 73 20 61 6e 79 20 70 72 verwrites any pr
1a210 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 eviously registe
1a220 72 65 64 20 70 72 6f 67 72 65 73 73 20 68 61 6e red progress han
1a230 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 dler..**.** {H12
1a240 39 31 37 7d 20 49 66 20 74 68 65 20 70 72 6f 67 917} If the prog
1a250 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c ress handler cal
1a260 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 20 74 68 lback is NULL th
1a270 65 6e 20 6e 6f 20 70 72 6f 67 72 65 73 73 0a 2a en no progress.*
1a280 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e 64 6c * handl
1a290 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a er is invoked..*
1a2a0 2a 0a 2a 2a 20 7b 48 31 32 39 31 38 7d 20 49 66 *.** {H12918} If
1a2b0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 the progress ca
1a2c0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 llback returns a
1a2d0 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74 68 result other th
1a2e0 61 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 an 0, then.**
1a2f0 20 20 20 20 20 20 20 74 68 65 20 62 65 68 61 76 the behav
1a300 69 6f 72 20 69 73 20 61 20 69 66 20 5b 73 71 6c ior is a if [sql
1a310 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
1a320 5d 20 68 61 64 20 62 65 65 6e 20 63 61 6c 6c 65 ] had been calle
1a330 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c d..** <
1a340 53 33 30 35 30 30 3e 0a 2a 2f 0a 76 6f 69 64 20 S30500>.*/.void
1a350 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 sqlite3_progress
1a360 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 _handler(sqlite3
1a370 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 *, int, int(*)(v
1a380 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a oid*), void*);..
1a390 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1a3a0 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 Opening A New Da
1a3b0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
1a3c0 6e 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32 n {H12700} <S402
1a3d0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 00>.**.** These
1a3e0 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e routines open an
1a3f0 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 SQLite database
1a400 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 file whose name
1a410 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 is given by the
1a420 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 .** filename arg
1a430 75 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e ument. The filen
1a440 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ame argument is
1a450 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 interpreted as U
1a460 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 TF-8 for.** sqli
1a470 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 te3_open() and s
1a480 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
1a490 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 and as UTF-16 i
1a4a0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 n the native byt
1a4b0 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 e.** order for s
1a4c0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e qlite3_open16().
1a4d0 20 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e A [database con
1a4e0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 nection] handle
1a4f0 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 is usually.** re
1a500 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c turned in *ppDb,
1a510 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f even if an erro
1a520 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f r occurs. The o
1a530 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 nly exception is
1a540 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 that.** if SQLi
1a550 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 te is unable to
1a560 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 allocate memory
1a570 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c to hold the [sql
1a580 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a ite3] object,.**
1a590 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 a NULL will be
1a5a0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 written into *pp
1a5b0 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 Db instead of a
1a5c0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b pointer to the [
1a5d0 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 sqlite3].** obje
1a5e0 63 74 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 ct. If the datab
1a5f0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 ase is opened (a
1a600 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 nd/or created) s
1a610 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 uccessfully, the
1a620 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d n.** [SQLITE_OK]
1a630 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f is returned. O
1a640 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 therwise an [err
1a650 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
1a660 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 rned. The.** [s
1a670 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
1a680 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 or [sqlite3_err
1a690 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 msg16()] routine
1a6a0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f s can be used to
1a6b0 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e obtain.** an En
1a6c0 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 glish language d
1a6d0 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 escription of th
1a6e0 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 e error..**.** T
1a6f0 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 he default encod
1a700 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 ing for the data
1a710 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 base will be UTF
1a720 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 -8 if.** sqlite3
1a730 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 _open() or sqlit
1a740 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
1a750 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 called and.** UT
1a760 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 F-16 in the nati
1a770 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 ve byte order if
1a780 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
1a790 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a ) is used..**.**
1a7a0 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 Whether or not
1a7b0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 an error occurs
1a7c0 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 when it is opene
1a7d0 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 d, resources.**
1a7e0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
1a7f0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
1a800 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 nnection] handle
1a810 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 should be relea
1a820 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e sed by.** passin
1a830 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 g it to [sqlite3
1a840 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 _close()] when i
1a850 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 t is no longer r
1a860 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 equired..**.** T
1a870 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f he sqlite3_open_
1a880 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 v2() interface w
1a890 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 orks like sqlite
1a8a0 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 3_open().** exce
1a8b0 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 pt that it accep
1a8c0 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 ts two additiona
1a8d0 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 l parameters for
1a8e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 additional cont
1a8f0 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 rol.** over the
1a900 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e new database con
1a910 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c nection. The fl
1a920 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 ags parameter ca
1a930 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a n take one of.**
1a940 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 the following t
1a950 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 hree values, opt
1a960 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 ionally combined
1a970 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 with the .** [S
1a980 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
1a990 45 58 5d 20 66 6c 61 67 3a 0a 2a 2a 0a 2a 2a 20 EX] flag:.**.**
1a9a0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c <dl>.** <dt>[SQL
1a9b0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
1a9c0 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 Y]</dt>.** <dd>T
1a9d0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
1a9e0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e pened in read-on
1a9f0 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 ly mode. If the
1aa00 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e database does n
1aa10 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 ot.** already ex
1aa20 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 ist, an error is
1aa30 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a returned.</dd>.
1aa40 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 **.** <dt>[SQLIT
1aa50 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
1aa60 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 ]</dt>.** <dd>Th
1aa70 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
1aa80 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 ened for reading
1aa90 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 and writing if
1aaa0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 possible, or rea
1aab0 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 ding.** only if
1aac0 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 the file is writ
1aad0 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 e protected by t
1aae0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
1aaf0 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a tem. In either.
1ab00 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 ** case the data
1ab10 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 base must alread
1ab20 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 y exist, otherwi
1ab30 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 se an error is r
1ab40 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a eturned.</dd>.**
1ab50 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f .** <dt>[SQLITE_
1ab60 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 OPEN_READWRITE]
1ab70 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 | [SQLITE_OPEN_C
1ab80 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c REATE]</dt>.** <
1ab90 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 dd>The database
1aba0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
1abb0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e ading and writin
1abc0 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 g, and is create
1abd0 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f s it if.** it do
1abe0 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 es not already e
1abf0 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 xist. This is th
1ac00 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 e behavior that
1ac10 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 is always used f
1ac20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 or.** sqlite3_op
1ac30 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 en() and sqlite3
1ac40 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a _open16().</dd>.
1ac50 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 ** </dl>.**.** I
1ac60 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 f the 3rd parame
1ac70 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f ter to sqlite3_o
1ac80 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 pen_v2() is not
1ac90 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f one of the.** co
1aca0 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e mbinations shown
1acb0 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 above or one of
1acc0 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e the combination
1acd0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f s shown above co
1ace0 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 mbined.** with t
1acf0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
1ad00 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 2c 20 74 NOMUTEX] flag, t
1ad10 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
1ad20 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
1ad30 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 4c *.** If the [SQL
1ad40 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
1ad50 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 ] flag is set, t
1ad60 68 65 6e 20 6d 75 74 65 78 65 73 20 6f 6e 20 74 hen mutexes on t
1ad70 68 65 0a 2a 2a 20 6f 70 65 6e 65 64 20 5b 64 61 he.** opened [da
1ad80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1ad90 6e 5d 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 n] are disabled
1ada0 61 6e 64 20 74 68 65 20 61 70 70 6c 69 61 74 69 and the appliati
1adb0 6f 6e 20 6d 75 73 74 0a 2a 2a 20 69 6e 73 75 72 on must.** insur
1adc0 65 20 74 68 61 74 20 61 63 63 65 73 73 20 74 6f e that access to
1add0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
1ade0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 69 onnection] and i
1adf0 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a ts associated.**
1ae00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1ae10 6d 65 6e 74 73 5d 20 69 73 20 73 65 72 69 61 6c ments] is serial
1ae20 69 7a 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 ized. The [SQLI
1ae30 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d TE_OPEN_NOMUTEX]
1ae40 20 66 6c 61 67 0a 2a 2a 20 69 73 20 74 68 65 20 flag.** is the
1ae50 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 default behavior
1ae60 20 69 73 20 53 51 4c 69 74 65 20 69 73 20 63 6f is SQLite is co
1ae70 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67 20 74 nfigured using t
1ae80 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f he.** [SQLITE_CO
1ae90 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 NFIG_MULTITHREAD
1aea0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e ] or [SQLITE_CON
1aeb0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
1aec0 5d 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 ] options.** to
1aed0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
1aee0 29 5d 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 )]. The [SQLITE
1aef0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 _OPEN_NOMUTEX] f
1af00 6c 61 67 20 6f 6e 6c 79 20 6d 61 6b 65 73 20 61 lag only makes a
1af10 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63 65 20 77 .** difference w
1af20 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e hen SQLite is in
1af30 20 69 74 73 20 64 65 66 61 75 6c 74 20 5b 53 51 its default [SQ
1af40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
1af50 41 4c 49 5a 45 44 5d 20 6d 6f 64 65 2e 0a 2a 2a ALIZED] mode..**
1af60 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e .** If the filen
1af70 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a ame is ":memory:
1af80 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 ", then a privat
1af90 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d e, temporary in-
1afa0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a memory database.
1afb0 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f ** is created fo
1afc0 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e r the connection
1afd0 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 . This in-memor
1afe0 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 y database will
1aff0 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 vanish when.** t
1b000 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1b010 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 ection is closed
1b020 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f . Future versio
1b030 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 ns of SQLite mig
1b040 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f ht.** make use o
1b050 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 f additional spe
1b060 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 cial filenames t
1b070 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 hat begin with t
1b080 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 he ":" character
1b090 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d ..** It is recom
1b0a0 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e mended that when
1b0b0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
1b0c0 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f name actually do
1b0d0 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a es begin with.**
1b0e0 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 a ":" character
1b0f0 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 you should pref
1b100 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 ix the filename
1b110 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 with a pathname
1b120 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 such as.** "./"
1b130 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 to avoid ambigui
1b140 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ty..**.** If the
1b150 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 filename is an
1b160 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 empty string, th
1b170 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 en a private, te
1b180 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 mporary.** on-di
1b190 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c sk database will
1b1a0 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 54 68 be created. Th
1b1b0 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 is private datab
1b1c0 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 ase will be.** a
1b1d0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c utomatically del
1b1e0 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 eted as soon as
1b1f0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
1b200 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 nection is close
1b210 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 d..**.** The fou
1b220 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
1b230 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
1b240 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f () is the name o
1b250 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
1b260 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 3_vfs] object th
1b270 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f at defines the o
1b280 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 perating system
1b290 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a interface that.*
1b2a0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 * the new databa
1b2b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 se connection sh
1b2c0 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20 74 68 ould use. If th
1b2d0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
1b2e0 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 er is.** a NULL
1b2f0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 pointer then the
1b300 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 default [sqlite
1b310 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 3_vfs] object is
1b320 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e used..**.** <b>
1b330 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 Note to Windows
1b340 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 users:</b> The
1b350 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f encoding used fo
1b360 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 r the filename a
1b370 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 rgument.** of sq
1b380 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 lite3_open() and
1b390 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
1b3a0 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 () must be UTF-8
1b3b0 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a , not whatever.*
1b3c0 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 * codepage is cu
1b3d0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e rrently defined.
1b3e0 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 Filenames cont
1b3f0 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 aining internati
1b400 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 onal.** characte
1b410 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 rs must be conve
1b420 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 rted to UTF-8 pr
1b430 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 ior to passing t
1b440 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 hem into.** sqli
1b450 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 te3_open() or sq
1b460 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
1b470 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
1b480 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 31 S:.**.** {H12701
1b490 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f } The [sqlite3_o
1b4a0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
1b4b0 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a _open16()], and.
1b4c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
1b4d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 ite3_open_v2()]
1b4e0 69 6e 74 65 72 66 61 63 65 73 20 63 72 65 61 74 interfaces creat
1b4f0 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 e a new.**
1b500 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f [database co
1b510 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 nnection] associ
1b520 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20 20 20 ated with.**
1b530 20 20 20 20 20 20 74 68 65 20 64 61 74 61 62 61 the databa
1b540 73 65 20 66 69 6c 65 20 67 69 76 65 6e 20 69 6e se file given in
1b550 20 74 68 65 69 72 20 66 69 72 73 74 20 70 61 72 their first par
1b560 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ameter..**.** {H
1b570 31 32 37 30 32 7d 20 54 68 65 20 66 69 6c 65 6e 12702} The filen
1b580 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ame argument is
1b590 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 interpreted as U
1b5a0 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 TF-8.**
1b5b0 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 for [sqlite3_op
1b5c0 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 en()] and [sqlit
1b5d0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e e3_open_v2()] an
1b5e0 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 20 d as UTF-16.**
1b5f0 20 20 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e in the n
1b600 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
1b610 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 for [sqlite3_op
1b620 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b en16()]..**.** {
1b630 48 31 32 37 30 33 7d 20 41 20 73 75 63 63 65 73 H12703} A succes
1b640 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 sful invocation
1b650 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e of [sqlite3_open
1b660 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
1b670 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 en16()],.**
1b680 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 or [sqlite3
1b690 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72 69 74 _open_v2()] writ
1b6a0 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 es a pointer to
1b6b0 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 a new.**
1b6c0 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e [database conn
1b6d0 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70 ection] into *pp
1b6e0 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 Db..**.** {H1270
1b6f0 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 4} The [sqlite3_
1b700 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
1b710 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 3_open16()], and
1b720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
1b730 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
1b740 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 interfaces retu
1b750 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 75 rn [SQLITE_OK] u
1b760 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a 2a 20 pon success,.**
1b770 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e 20 61 or an a
1b780 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f ppropriate [erro
1b790 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 r code] on failu
1b7a0 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 re..**.** {H1270
1b7b0 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 74 6} The default t
1b7c0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 ext encoding for
1b7d0 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 a new database
1b7e0 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a created using.**
1b7f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
1b800 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 e3_open()] or [s
1b810 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
1b820 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 2e ] will be UTF-8.
1b830 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 37 7d 20 .**.** {H12707}
1b840 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 74 The default text
1b850 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 encoding for a
1b860 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 72 65 new database cre
1b870 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 ated using.**
1b880 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
1b890 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c 20 62 open16()] will b
1b8a0 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 e UTF-16..**.**
1b8b0 7b 48 31 32 37 30 39 7d 20 54 68 65 20 5b 73 71 {H12709} The [sq
1b8c0 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44 29 5d lite3_open(F,D)]
1b8d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 71 interface is eq
1b8e0 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20 uivalent to.**
1b8f0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
1b900 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 30 _open_v2(F,D,G,0
1b910 29 5d 20 77 68 65 72 65 20 74 68 65 20 47 20 70 )] where the G p
1b920 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 arameter is.**
1b930 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
1b940 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 7c OPEN_READWRITE]|
1b950 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 [SQLITE_OPEN_CRE
1b960 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ATE]..**.** {H12
1b970 37 31 31 7d 20 49 66 20 74 68 65 20 47 20 70 61 711} If the G pa
1b980 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
1b990 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c te3_open_v2(F,D,
1b9a0 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 G,V)] contains t
1b9b0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 he.** b
1b9c0 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 it value [SQLITE
1b9d0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 _OPEN_READONLY]
1b9e0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
1b9f0 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 e is opened.**
1ba00 20 20 20 20 20 20 20 20 66 6f 72 20 72 65 61 64 for read
1ba10 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ing only..**.**
1ba20 7b 48 31 32 37 31 32 7d 20 49 66 20 74 68 65 20 {H12712} If the
1ba30 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b G parameter to [
1ba40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1ba50 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 F,D,G,V)] contai
1ba60 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ns the.**
1ba70 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 bit value [SQ
1ba80 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
1ba90 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20 64 61 ITE] then the da
1baa0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
1bab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 61 .** rea
1bac0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 ding and writing
1bad0 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 if possible, or
1bae0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c for reading onl
1baf0 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 y if the.**
1bb00 20 20 20 20 20 66 69 6c 65 20 69 73 20 77 72 69 file is wri
1bb10 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 te protected by
1bb20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
1bb30 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 stem..**.** {H12
1bb40 37 31 33 7d 20 49 66 20 74 68 65 20 47 20 70 61 713} If the G pa
1bb50 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
1bb60 74 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c te3_open(v2(F,D,
1bb70 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68 65 0a G,V)] omits the.
1bb80 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 ** bit
1bb90 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 value [SQLITE_OP
1bba0 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74 EN_CREATE] and t
1bbb0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 he database does
1bbc0 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 not.**
1bbd0 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 previously exis
1bbe0 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 t, an error is r
1bbf0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b eturned..**.** {
1bc00 48 31 32 37 31 34 7d 20 49 66 20 74 68 65 20 47 H12714} If the G
1bc10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
1bc20 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 28 46 qlite3_open(v2(F
1bc30 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e ,D,G,V)] contain
1bc40 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
1bc50 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c bit value [SQL
1bc60 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d ITE_OPEN_CREATE]
1bc70 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 and the databas
1bc80 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 e does not.**
1bc90 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c previousl
1bca0 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20 61 6e y exist, then an
1bcb0 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 attempt is made
1bcc0 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64 0a 2a to create and.*
1bcd0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69 74 69 * initi
1bce0 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61 62 61 alize the databa
1bcf0 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 se..**.** {H1271
1bd00 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 7} If the filena
1bd10 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b me argument to [
1bd20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
1bd30 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
1bd40 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ()],.**
1bd50 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 or [sqlite3_ope
1bd60 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d 65 6d n_v2()] is ":mem
1bd70 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 ory:", then an p
1bd80 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 rivate,.**
1bd90 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c 20 69 ephemeral, i
1bda0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 n-memory databas
1bdb0 65 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 e is created for
1bdc0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e the connection.
1bdd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f .** <to
1bde0 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 do>Is SQLITE_OPE
1bdf0 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f N_CREATE|SQLITE_
1be00 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72 OPEN_READWRITE r
1be10 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 equired.**
1be20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f in sqlite3_o
1be30 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e pen_v2()?</todo>
1be40 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 39 7d 20 .**.** {H12719}
1be50 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 If the filename
1be60 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d is NULL or an em
1be70 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e pty string, then
1be80 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 a private,.**
1be90 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 72 61 ephemera
1bea0 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 l on-disk databa
1beb0 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 se will be creat
1bec0 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ed..**
1bed0 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f <todo>Is SQLITE_
1bee0 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 OPEN_CREATE|SQLI
1bef0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
1bf00 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 E required.**
1bf10 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 in sqlite
1bf20 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 3_open_v2()?</to
1bf30 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 do>.**.** {H1272
1bf40 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 1} The [database
1bf50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 72 65 connection] cre
1bf60 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ated by [sqlite3
1bf70 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 _open_v2(F,D,G,V
1bf80 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 )].** w
1bf90 69 6c 6c 20 75 73 65 20 74 68 65 20 5b 73 71 6c ill use the [sql
1bfa0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
1bfb0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 identified by t
1bfc0 68 65 20 56 20 70 61 72 61 6d 65 74 65 72 2c 0a he V parameter,.
1bfd0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 ** or t
1bfe0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 he default [sqli
1bff0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 te3_vfs] object
1c000 69 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 if V is a NULL p
1c010 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ointer..**.** {H
1c020 31 32 37 32 33 7d 20 54 77 6f 20 5b 64 61 74 61 12723} Two [data
1c030 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
1c040 5d 20 77 69 6c 6c 20 73 68 61 72 65 20 61 20 63 ] will share a c
1c050 6f 6d 6d 6f 6e 20 63 61 63 68 65 20 69 66 20 62 ommon cache if b
1c060 6f 74 68 20 77 65 72 65 0a 2a 2a 20 20 20 20 20 oth were.**
1c070 20 20 20 20 20 6f 70 65 6e 65 64 20 77 69 74 68 opened with
1c080 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 77 68 the same VFS wh
1c090 69 6c 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 ile [shared cach
1c0a0 65 20 6d 6f 64 65 5d 20 77 61 73 20 65 6e 61 62 e mode] was enab
1c0b0 6c 65 64 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 led and.**
1c0c0 20 20 20 20 69 66 20 62 6f 74 68 20 66 69 6c 65 if both file
1c0d0 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65 20 65 71 names compare eq
1c0e0 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d 63 6d 70 ual using memcmp
1c0f0 28 29 20 61 66 74 65 72 20 68 61 76 69 6e 67 20 () after having
1c100 62 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 been.**
1c110 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 74 68 processed by th
1c120 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c e [sqlite3_vfs |
1c130 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 5d 20 xFullPathname]
1c140 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 56 46 method of the VF
1c150 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 S..*/.int sqlite
1c160 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 3_open(. const
1c170 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 char *filename,
1c180 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 /* Database fi
1c190 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a lename (UTF-8) *
1c1a0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 /. sqlite3 **pp
1c1b0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f Db /* O
1c1c0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 UT: SQLite db ha
1c1d0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 ndle */.);.int s
1c1e0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 qlite3_open16(.
1c1f0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c const void *fil
1c200 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 ename, /* Data
1c210 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 base filename (U
1c220 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 TF-16) */. sqli
1c230 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 te3 **ppDb
1c240 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
1c250 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
1c260 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f );.int sqlite3_o
1c270 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 pen_v2(. const
1c280 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 char *filename,
1c290 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 /* Database fi
1c2a0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a lename (UTF-8) *
1c2b0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 /. sqlite3 **pp
1c2c0 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f Db, /* O
1c2d0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 UT: SQLite db ha
1c2e0 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c ndle */. int fl
1c2f0 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 ags,
1c300 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 /* Flags */.
1c310 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 const char *zVfs
1c320 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 /* Name
1c330 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f of VFS module to
1c340 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a use */.);../*.*
1c350 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f * CAPI3REF: Erro
1c360 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 r Codes And Mess
1c370 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20 3c 53 ages {H12800} <S
1c380 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 60200>.**.** The
1c390 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 sqlite3_errcode
1c3a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
1c3b0 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 urns the numeric
1c3c0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f [result code] o
1c3d0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 r.** [extended r
1c3e0 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 esult code] for
1c3f0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
1c400 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a failed sqlite3_*
1c410 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 API call.** ass
1c420 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b ociated with a [
1c430 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1c440 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 ion]. If a prior
1c450 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 API call failed
1c460 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 .** but the most
1c470 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c recent API call
1c480 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 succeeded, the
1c490 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f return value fro
1c4a0 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 m.** sqlite3_err
1c4b0 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 code() is undefi
1c4c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ned..**.** The s
1c4d0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 qlite3_errmsg()
1c4e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d and sqlite3_errm
1c4f0 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e sg16() return En
1c500 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a glish-language.*
1c510 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 * text that desc
1c520 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c ribes the error,
1c530 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 as either UTF-8
1c540 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 or UTF-16 respe
1c550 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f ctively..** Memo
1c560 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 ry to hold the e
1c570 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 rror message str
1c580 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 ing is managed i
1c590 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 nternally..** Th
1c5a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f e application do
1c5b0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 es not need to w
1c5c0 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 orry about freei
1c5d0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a ng the result..*
1c5e0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 * However, the e
1c5f0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 rror string migh
1c600 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e t be overwritten
1c610 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 or deallocated
1c620 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 by.** subsequent
1c630 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 calls to other
1c640 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
1c650 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a functions..**.*
1c660 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 * If an interfac
1c670 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c e fails with SQL
1c680 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 ITE_MISUSE, that
1c690 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 means the inter
1c6a0 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f face.** was invo
1c6b0 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 ked incorrectly
1c6c0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 by the applicati
1c6d0 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 on. In that cas
1c6e0 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 e, the.** error
1c6f0 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 code and message
1c700 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 may or may not
1c710 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e be set..**.** IN
1c720 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
1c730 7b 48 31 32 38 30 31 7d 20 54 68 65 20 5b 73 71 {H12801} The [sq
1c740 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 lite3_errcode(D)
1c750 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
1c760 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a rns the numeric.
1c770 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 72 65 73 ** [res
1c780 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 ult code] or [ex
1c790 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
1c7a0 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 de] for the most
1c7b0 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 recently.**
1c7c0 20 20 20 20 20 20 66 61 69 6c 65 64 20 69 6e 74 failed int
1c7d0 65 72 66 61 63 65 20 63 61 6c 6c 20 61 73 73 6f erface call asso
1c7e0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
1c7f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1c800 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b tion] D..**.** {
1c810 48 31 32 38 30 33 7d 20 54 68 65 20 5b 73 71 6c H12803} The [sql
1c820 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 20 ite3_errmsg(D)]
1c830 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 and [sqlite3_err
1c840 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20 20 msg16(D)].**
1c850 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 interfaces
1c860 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d return English-
1c870 6c 61 6e 67 75 61 67 65 20 74 65 78 74 20 74 68 language text th
1c880 61 74 20 64 65 73 63 72 69 62 65 73 0a 2a 2a 20 at describes.**
1c890 20 20 20 20 20 20 20 20 20 74 68 65 20 65 72 72 the err
1c8a0 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c 79 or in the mostly
1c8b0 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65 64 recently failed
1c8c0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2c interface call,
1c8d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63 .** enc
1c8e0 6f 64 65 64 20 61 73 20 65 69 74 68 65 72 20 55 oded as either U
1c8f0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 TF-8 or UTF-16 r
1c900 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a espectively..**.
1c910 2a 2a 20 7b 48 31 32 38 30 37 7d 20 54 68 65 20 ** {H12807} The
1c920 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 strings returned
1c930 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 by [sqlite3_err
1c940 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 msg()] and [sqli
1c950 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a te3_errmsg16()].
1c960 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 ** are
1c970 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 valid until the
1c980 6e 65 78 74 20 53 51 4c 69 74 65 20 69 6e 74 65 next SQLite inte
1c990 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a rface call..**.*
1c9a0 2a 20 7b 48 31 32 38 30 38 7d 20 43 61 6c 6c 73 * {H12808} Calls
1c9b0 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73 to API routines
1c9c0 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 that do not ret
1c9d0 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 urn an error cod
1c9e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 28 65 e.** (e
1c9f0 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 xample: [sqlite3
1ca00 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 _data_count()])
1ca10 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 do not.**
1ca20 20 20 20 63 68 61 6e 67 65 20 74 68 65 20 65 72 change the er
1ca30 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 ror code or mess
1ca40 61 67 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a age returned by.
1ca50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
1ca60 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c ite3_errcode()],
1ca70 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
1ca80 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 ()], or [sqlite3
1ca90 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a _errmsg16()]..**
1caa0 0a 2a 2a 20 7b 48 31 32 38 30 39 7d 20 49 6e 74 .** {H12809} Int
1cab0 65 72 66 61 63 65 73 20 74 68 61 74 20 61 72 65 erfaces that are
1cac0 20 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20 not associated
1cad0 77 69 74 68 20 61 20 73 70 65 63 69 66 69 63 0a with a specific.
1cae0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 ** [dat
1caf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1cb00 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 ] (examples:.**
1cb10 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
1cb20 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 3_mprintf()] or
1cb30 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f [sqlite3_enable_
1cb40 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 0a shared_cache()].
1cb50 2a 2a 20 20 20 20 20 20 20 20 20 20 64 6f 20 6e ** do n
1cb60 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 ot change the va
1cb70 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 lues returned by
1cb80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
1cb90 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
1cba0 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 , [sqlite3_errms
1cbb0 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 g()], or [sqlite
1cbc0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 3_errmsg16()]..*
1cbd0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 /.int sqlite3_er
1cbe0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 rcode(sqlite3 *d
1cbf0 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a b);.const char *
1cc00 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 sqlite3_errmsg(s
1cc10 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 qlite3*);.const
1cc20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 void *sqlite3_er
1cc30 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 rmsg16(sqlite3*)
1cc40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1cc50 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 F: SQL Statement
1cc60 20 4f 62 6a 65 63 74 20 7b 48 31 33 30 30 30 7d Object {H13000}
1cc70 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 4b 45 59 <H13010>.** KEY
1cc80 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 WORDS: {prepared
1cc90 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 statement} {pre
1cca0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
1ccb0 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 }.**.** An insta
1ccc0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
1ccd0 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 ct represents a
1cce0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 single SQL state
1ccf0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 ment..** This ob
1cd00 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c ject is variousl
1cd10 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 y known as a "pr
1cd20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1cd30 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 " or a.** "compi
1cd40 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e led SQL statemen
1cd50 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 t" or simply as
1cd60 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a a "statement"..*
1cd70 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 *.** The life of
1cd80 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a a statement obj
1cd90 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 ect goes somethi
1cda0 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a ng like this:.**
1cdb0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ol>.** <li>
1cdc0 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 Create the obje
1cdd0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ct using [sqlite
1cde0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
1cdf0 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 or a related.**
1ce00 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a function..*
1ce10 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 * <li> Bind valu
1ce20 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 es to [host para
1ce30 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 meters] using th
1ce40 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
1ce50 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 ().** inter
1ce60 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 faces..** <li> R
1ce70 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 un the SQL by ca
1ce80 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 lling [sqlite3_s
1ce90 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f tep()] one or mo
1cea0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 re times..** <li
1ceb0 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74 > Reset the stat
1cec0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c ement using [sql
1ced0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 ite3_reset()] th
1cee0 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 en go back.**
1cef0 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 to step 2. D
1cf00 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d o this zero or m
1cf10 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c ore times..** <l
1cf20 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f i> Destroy the o
1cf30 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c bject using [sql
1cf40 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
1cf50 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a ..** </ol>.**.**
1cf60 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 Refer to docume
1cf70 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 ntation on indiv
1cf80 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 idual methods ab
1cf90 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ove for addition
1cfa0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f al.** informatio
1cfb0 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 n..*/.typedef st
1cfc0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d ruct sqlite3_stm
1cfd0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a t sqlite3_stmt;.
1cfe0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1cff0 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 Run-time Limits
1d000 20 7b 48 31 32 37 36 30 7d 20 3c 53 32 30 36 30 {H12760} <S2060
1d010 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 0>.**.** This in
1d020 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 terface allows t
1d030 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f he size of vario
1d040 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f us constructs to
1d050 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f be limited.** o
1d060 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 n a connection b
1d070 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 y connection bas
1d080 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 is. The first p
1d090 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a arameter is the.
1d0a0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
1d0b0 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c nection] whose l
1d0c0 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 imit is to be se
1d0d0 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 t or queried. T
1d0e0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 he.** second par
1d0f0 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 ameter is one of
1d100 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 the [limit cate
1d110 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 gories] that def
1d120 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f ine a.** class o
1d130 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 f constructs to
1d140 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e be size limited.
1d150 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 The third para
1d160 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 meter is the.**
1d170 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 new limit for th
1d180 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 at construct. T
1d190 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 he function retu
1d1a0 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 rns the old limi
1d1b0 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 t..**.** If the
1d1c0 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e new limit is a n
1d1d0 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 egative number,
1d1e0 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 the limit is unc
1d1f0 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 hanged..** For t
1d200 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 he limit categor
1d210 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 y of SQLITE_LIMI
1d220 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20 61 T_XYZ there is a
1d230 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 62 hard upper.** b
1d240 6f 75 6e 64 20 73 65 74 20 62 79 20 61 20 63 6f ound set by a co
1d250 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 mpile-time C pre
1d260 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 processor macro
1d270 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 4d 41 58 named SQLITE_MAX
1d280 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68 65 20 22 5f _XYZ..** (The "_
1d290 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e LIMIT_" in the n
1d2a0 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 ame is changed t
1d2b0 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 o "_MAX_".).** A
1d2c0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 ttempts to incre
1d2d0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 ase a limit abov
1d2e0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 e its hard upper
1d2f0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 bound are.** si
1d300 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 lently truncated
1d310 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 to the hard upp
1d320 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 er limit..**.**
1d330 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73 20 Run time limits
1d340 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 are intended for
1d350 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 use in applicat
1d360 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 ions that manage
1d370 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f .** both their o
1d380 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 wn internal data
1d390 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 base and also da
1d3a0 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 tabases that are
1d3b0 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 controlled.** b
1d3c0 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 y untrusted exte
1d3d0 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 rnal sources. A
1d3e0 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 n example applic
1d3f0 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 ation might be a
1d400 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65 72 20 74 .** webbrowser t
1d410 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 hat has its own
1d420 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 databases for st
1d430 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e oring history an
1d440 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 d.** separate da
1d450 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c tabases controll
1d460 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 ed by JavaScript
1d470 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f applications do
1d480 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 wnloaded.** off
1d490 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 the Internet. T
1d4a0 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 he internal data
1d4b0 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 bases can be giv
1d4c0 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c en the.** large,
1d4d0 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e default limits.
1d4e0 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 Databases mana
1d4f0 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 ged by external
1d500 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 sources can.** b
1d510 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 e given much sma
1d520 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 ller limits desi
1d530 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 gned to prevent
1d540 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 a denial of serv
1d550 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 ice.** attack.
1d560 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 Developers might
1d570 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 also want to us
1d580 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 e the [sqlite3_s
1d590 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d et_authorizer()]
1d5a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f .** interface to
1d5b0 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c further control
1d5c0 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 untrusted SQL.
1d5d0 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 The size of the
1d5e0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 database.** cre
1d5f0 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 ated by an untru
1d600 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 sted script can
1d610 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 be contained usi
1d620 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 ng the.** [max_p
1d630 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 age_count] [PRAG
1d640 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 MA]..**.** New r
1d650 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 un-time limit ca
1d660 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 tegories may be
1d670 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
1d680 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 releases..**.**
1d690 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
1d6a0 2a 20 7b 48 31 32 37 36 32 7d 20 41 20 73 75 63 * {H12762} A suc
1d6b0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 cessful call to
1d6c0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 [sqlite3_limit(D
1d6d0 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69 ,C,V)] where V i
1d6e0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f s.** po
1d6f0 73 69 74 69 76 65 20 63 68 61 6e 67 65 73 20 74 sitive changes t
1d700 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 he limit on the
1d710 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 size of construc
1d720 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 t C in the.**
1d730 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 [database
1d740 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 connection] D t
1d750 6f 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66 20 o the lesser of
1d760 56 20 61 6e 64 20 74 68 65 20 68 61 72 64 20 75 V and the hard u
1d770 70 70 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 pper.**
1d780 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73 69 bound on the si
1d790 7a 65 20 6f 66 20 43 20 74 68 61 74 20 69 73 20 ze of C that is
1d7a0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 set at compile-t
1d7b0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 ime..**.** {H127
1d7c0 36 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 66} A successful
1d7d0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
1d7e0 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 3_limit(D,C,V)]
1d7f0 77 68 65 72 65 20 56 20 69 73 20 6e 65 67 61 74 where V is negat
1d800 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ive.**
1d810 6c 65 61 76 65 73 20 74 68 65 20 73 74 61 74 65 leaves the state
1d820 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 of the [databas
1d830 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 e connection] D
1d840 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a unchanged..**.**
1d850 20 7b 48 31 32 37 36 39 7d 20 41 20 73 75 63 63 {H12769} A succ
1d860 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
1d870 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c sqlite3_limit(D,
1d880 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20 74 68 C,V)] returns th
1d890 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 e.** va
1d8a0 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 lue of the limit
1d8b0 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 on the size of
1d8c0 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20 74 construct C in t
1d8d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
1d8e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1d8f0 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77 61 73 ion] D as it was
1d900 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61 prior to the ca
1d910 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ll..*/.int sqlit
1d920 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 e3_limit(sqlite3
1d930 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e *, int id, int n
1d940 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ewVal);../*.** C
1d950 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d API3REF: Run-Tim
1d960 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 e Limit Categori
1d970 65 73 20 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 es {H12790} <H12
1d980 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 760>.** KEYWORDS
1d990 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 : {limit categor
1d9a0 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f y} {limit catego
1d9b0 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ries}.**.** Thes
1d9c0 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 e constants defi
1d9d0 6e 65 20 76 61 72 69 6f 75 73 20 61 73 70 65 63 ne various aspec
1d9e0 74 73 20 6f 66 20 61 20 5b 64 61 74 61 62 61 73 ts of a [databas
1d9f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a e connection].**
1da00 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 69 6d that can be lim
1da10 69 74 65 64 20 69 6e 20 73 69 7a 65 20 62 79 20 ited in size by
1da20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
1da30 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 3_limit()]..** T
1da40 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 he meanings of t
1da50 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 he various limit
1da60 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 s are as follows
1da70 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 :.**.** <dl>.**
1da80 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
1da90 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 _LENGTH</dt>.**
1daa0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
1dab0 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 size of any stri
1dac0 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 ng or BLOB or ta
1dad0 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a ble row.<dd>.**.
1dae0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ** <dt>SQLITE_LI
1daf0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f MIT_SQL_LENGTH</
1db00 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
1db10 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
1db20 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
1db30 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 t.</dd>.**.** <d
1db40 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 t>SQLITE_LIMIT_C
1db50 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 OLUMN</dt>.** <d
1db60 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
1db70 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
1db80 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e in a table defin
1db90 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a ition or in the.
1dba0 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 ** result set of
1dbb0 20 61 20 53 45 4c 45 43 54 20 6f 72 20 74 68 65 a SELECT or the
1dbc0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
1dbd0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e of columns in an
1dbe0 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 index.** or in
1dbf0 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 an ORDER BY or G
1dc00 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c ROUP BY clause.<
1dc10 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
1dc20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 QLITE_LIMIT_EXPR
1dc30 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c _DEPTH</dt>.** <
1dc40 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 dd>The maximum d
1dc50 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 epth of the pars
1dc60 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 e tree on any ex
1dc70 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a pression.</dd>.*
1dc80 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
1dc90 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 LIMIT_COMPOUND_S
1dca0 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ELECT</dt>.** <d
1dcb0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
1dcc0 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e mber of terms in
1dcd0 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 a compound SELE
1dce0 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 CT statement.</d
1dcf0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
1dd00 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f ITE_LIMIT_VDBE_O
1dd10 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 P</dt>.** <dd>Th
1dd20 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
1dd30 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 of instructions
1dd40 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 in a virtual ma
1dd50 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a chine program.**
1dd60 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 used to impleme
1dd70 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d nt an SQL statem
1dd80 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ent.</dd>.**.**
1dd90 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
1dda0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 _FUNCTION_ARG</d
1ddb0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
1ddc0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
1ddd0 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 arguments on a f
1dde0 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a unction.</dd>.**
1ddf0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c .** <dt>SQLITE_L
1de00 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 IMIT_ATTACHED</d
1de10 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
1de20 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
1de30 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
1de40 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c es.</dd>.**.** <
1de50 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
1de60 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e LIKE_PATTERN_LEN
1de70 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e GTH</dt>.** <dd>
1de80 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 The maximum leng
1de90 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 th of the patter
1dea0 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 n argument to th
1deb0 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f e LIKE or.** GLO
1dec0 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 B operators.</dd
1ded0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
1dee0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c TE_LIMIT_VARIABL
1def0 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a E_NUMBER</dt>.**
1df00 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
1df10 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61 number of varia
1df20 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 bles in an SQL s
1df30 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61 tatement that ca
1df40 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f n.** be bound.</
1df50 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a dd>.** </dl>.*/.
1df60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
1df70 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 IMIT_LENGTH
1df80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
1df90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1dfa0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 LIMIT_SQL_LENGTH
1dfb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1dfc0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
1dfd0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 _LIMIT_COLUMN
1dfe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1dff0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
1e000 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 E_LIMIT_EXPR_DEP
1e010 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
1e020 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
1e030 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e TE_LIMIT_COMPOUN
1e040 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 D_SELECT
1e050 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
1e060 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f ITE_LIMIT_VDBE_O
1e070 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 P
1e080 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 5.#define SQ
1e090 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
1e0a0 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 ION_ARG
1e0b0 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 6.#define S
1e0c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 QLITE_LIMIT_ATTA
1e0d0 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 CHED
1e0e0 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 7.#define
1e0f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b SQLITE_LIMIT_LIK
1e100 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 E_PATTERN_LENGTH
1e110 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 8.#define
1e120 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 SQLITE_LIMIT_VA
1e130 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 RIABLE_NUMBER
1e140 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 9../*.**
1e150 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 CAPI3REF: Compi
1e160 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 ling An SQL Stat
1e170 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c ement {H13010} <
1e180 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S10000>.** KEYWO
1e190 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d RDS: {SQL statem
1e1a0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a ent compiler}.**
1e1b0 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 .** To execute a
1e1c0 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 n SQL query, it
1e1d0 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f must first be co
1e1e0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 mpiled into a by
1e1f0 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 te-code.** progr
1e200 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 am using one of
1e210 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
1e220 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
1e230 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 argument, "db",
1e240 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 is a [database c
1e250 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 onnection] obtai
1e260 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 ned from a.** pr
1e270 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ior call to [sql
1e280 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
1e290 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
1e2a0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ] or [sqlite3_op
1e2b0 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 en16()]..**.** T
1e2c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
1e2d0 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 nt, "zSql", is t
1e2e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 he statement to
1e2f0 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 be compiled, enc
1e300 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 oded.** as eithe
1e310 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 r UTF-8 or UTF-1
1e320 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6. The sqlite3_
1e330 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 prepare() and sq
1e340 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1e350 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 ().** interfaces
1e360 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 use UTF-8, and
1e370 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
1e380 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6() and sqlite3_
1e390 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a prepare16_v2().*
1e3a0 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a * use UTF-16..**
1e3b0 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65 .** If the nByte
1e3c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 argument is les
1e3d0 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 s than zero, the
1e3e0 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 n zSql is read u
1e3f0 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 p to the.** firs
1e400 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f t zero terminato
1e410 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73 20 6e r. If nByte is n
1e420 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 on-negative, the
1e430 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 n it is the maxi
1e440 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 mum.** number of
1e450 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f bytes read fro
1e460 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42 m zSql. When nB
1e470 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 yte is non-negat
1e480 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c ive, the.** zSql
1e490 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 string ends at
1e4a0 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 either the first
1e4b0 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 '\000' or '\u00
1e4c0 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 00' character or
1e4d0 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 .** the nByte-th
1e4e0 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 byte, whichever
1e4f0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 comes first. If
1e500 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 the caller know
1e510 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 s.** that the su
1e520 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 pplied string is
1e530 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c nul-terminated,
1e540 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 then there is a
1e550 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 small.** perfor
1e560 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 mance advantage
1e570 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 to be gained by
1e580 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 passing an nByte
1e590 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a parameter that.
1e5a0 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 ** is equal to t
1e5b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
1e5c0 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 es in the input
1e5d0 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 string <i>includ
1e5e0 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e ing</i>.** the n
1e5f0 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 ul-terminator by
1e600 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 tes..**.** *pzTa
1e610 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f il is made to po
1e620 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 int to the first
1e630 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65 byte past the e
1e640 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 nd of the.** fir
1e650 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 st SQL statement
1e660 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 in zSql. These
1e670 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63 routines only c
1e680 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 ompile the first
1e690 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e .** statement in
1e6a0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 zSql, so *pzTai
1e6b0 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 l is left pointi
1e6c0 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69 ng to what remai
1e6d0 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 ns.** uncompiled
1e6e0 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 ..**.** *ppStmt
1e6f0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 is left pointing
1e700 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b to a compiled [
1e710 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1e720 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a nt] that can be.
1e730 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e ** executed usin
1e740 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 g [sqlite3_step(
1e750 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 )]. If there is
1e760 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 an error, *ppSt
1e770 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 mt is set.** to
1e780 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e NULL. If the in
1e790 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e put text contain
1e7a0 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 s no SQL (if the
1e7b0 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 input is an emp
1e7c0 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 ty.** string or
1e7d0 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 a comment) then
1e7e0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 *ppStmt is set t
1e7f0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41 31 33 30 o NULL..** {A130
1e800 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 18} The calling
1e810 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 procedure is res
1e820 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c ponsible for del
1e830 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c eting the compil
1e840 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d ed.** SQL statem
1e850 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ent using [sqlit
1e860 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 e3_finalize()] a
1e870 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 fter it has fini
1e880 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a shed with it..**
1e890 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 .** On success,
1e8a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 [SQLITE_OK] is r
1e8b0 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77 69 eturned, otherwi
1e8c0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 se an [error cod
1e8d0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a e] is returned..
1e8e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
1e8f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 3_prepare_v2() a
1e900 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
1e910 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 re16_v2() interf
1e920 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f aces are.** reco
1e930 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 mmended for all
1e940 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 new programs. Th
1e950 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 e two older inte
1e960 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 rfaces are retai
1e970 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 ned.** for backw
1e980 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
1e990 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 ty, but their us
1e9a0 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 e is discouraged
1e9b0 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 ..** In the "v2"
1e9c0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 interfaces, the
1e9d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
1e9e0 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 ent.** that is r
1e9f0 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 eturned (the [sq
1ea00 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 lite3_stmt] obje
1ea10 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 ct) contains a c
1ea20 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 opy of the.** or
1ea30 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e iginal SQL text.
1ea40 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 This causes the
1ea50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
1ea60 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a ] interface to.*
1ea70 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65 * behave a diffe
1ea80 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 rently in two wa
1ea90 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a ys:.**.** <ol>.*
1eaa0 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 * <li>.** If the
1eab0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 database schema
1eac0 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 changes, instea
1ead0 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b d of returning [
1eae0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 SQLITE_SCHEMA] a
1eaf0 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 s it.** always u
1eb00 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 sed to do, [sqli
1eb10 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c te3_step()] will
1eb20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 automatically r
1eb30 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c ecompile the SQL
1eb40 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e .** statement an
1eb50 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 d try to run it
1eb60 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73 again. If the s
1eb70 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 chema has change
1eb80 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 d in.** a way th
1eb90 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 at makes the sta
1eba0 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 tement no longer
1ebb0 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 valid, [sqlite3
1ebc0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 _step()] will st
1ebd0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 ill.** return [S
1ebe0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 QLITE_SCHEMA].
1ebf0 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c But unlike the l
1ec00 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 egacy behavior,
1ec10 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 [SQLITE_SCHEMA]
1ec20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 is.** now a fata
1ec30 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e l error. Callin
1ec40 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
1ec50 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 re_v2()] again w
1ec60 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 ill not make the
1ec70 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 .** error go awa
1ec80 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 y. Note: use [s
1ec90 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
1eca0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 to find the tex
1ecb0 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73 t.** of the pars
1ecc0 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72 ing error that r
1ecd0 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 esults in an [SQ
1ece0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 LITE_SCHEMA] ret
1ecf0 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a urn..** </li>.**
1ed00 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e .** <li>.** When
1ed10 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
1ed20 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
1ed30 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f )] will return o
1ed40 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c ne of the detail
1ed50 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 ed.** [error cod
1ed60 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 es] or [extended
1ed70 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 error codes].
1ed80 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 The legacy behav
1ed90 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 ior was that.**
1eda0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1edb0 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 would only retu
1edc0 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 rn a generic [SQ
1edd0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 LITE_ERROR] resu
1ede0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 lt code.** and y
1edf0 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f ou would have to
1ee00 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 make a second c
1ee10 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
1ee20 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 reset()] in orde
1ee30 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 r.** to find the
1ee40 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 underlying caus
1ee50 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d e of the problem
1ee60 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 . With the "v2"
1ee70 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 prepare.** inter
1ee80 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 faces, the under
1ee90 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 lying reason for
1eea0 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 the error is re
1eeb0 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 turned immediate
1eec0 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 ly..** </li>.**
1eed0 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 </ol>.**.** INVA
1eee0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
1eef0 31 33 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 13011} The [sqli
1ef00 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a te3_prepare(db,z
1ef10 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a Sql,...)] and.**
1ef20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
1ef30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 e3_prepare_v2(db
1ef40 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 ,zSql,...)] inte
1ef50 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 74 rfaces interpret
1ef60 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
1ef70 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a text in their z
1ef80 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73 Sql parameter as
1ef90 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 UTF-8..**.** {H
1efa0 31 33 30 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 13012} The [sqli
1efb0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 64 62 te3_prepare16(db
1efc0 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a ,zSql,...)] and.
1efd0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
1efe0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
1eff0 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 2(db,zSql,...)]
1f000 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 interfaces inter
1f010 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 pret the.**
1f020 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 text in the
1f030 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 ir zSql paramete
1f040 72 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 r as UTF-16 in t
1f050 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f he native byte o
1f060 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 rder..**.** {H13
1f070 30 31 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74 013} If the nByt
1f080 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 e argument to [s
1f090 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1f0a0 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2(db,zSql,nByte,
1f0b0 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 ...)].**
1f0c0 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e and its varian
1f0d0 74 73 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 ts is less than
1f0e0 7a 65 72 6f 2c 20 74 68 65 20 53 51 4c 20 74 65 zero, the SQL te
1f0f0 78 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 xt is.**
1f100 20 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c read from zSql
1f110 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 is read up to t
1f120 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 he first zero te
1f130 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 rminator..**.**
1f140 7b 48 31 33 30 31 34 7d 20 49 66 20 74 68 65 20 {H13014} If the
1f150 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 nByte argument t
1f160 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 o [sqlite3_prepa
1f170 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 re_v2(db,zSql,nB
1f180 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 yte,...)].**
1f190 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 and its va
1f1a0 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 riants is non-ne
1f1b0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 74 20 gative, then at
1f1c0 6d 6f 73 74 20 6e 42 79 74 65 73 20 62 79 74 65 most nBytes byte
1f1d0 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 s of.**
1f1e0 20 53 51 4c 20 74 65 78 74 20 69 73 20 72 65 61 SQL text is rea
1f1f0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a d from zSql..**.
1f200 2a 2a 20 7b 48 31 33 30 31 35 7d 20 49 6e 20 5b ** {H13015} In [
1f210 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1f220 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 v2(db,zSql,N,P,p
1f230 7a 54 61 69 6c 29 5d 20 61 6e 64 20 69 74 73 20 zTail)] and its
1f240 76 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20 variants.**
1f250 20 20 20 20 20 69 66 20 74 68 65 20 7a 53 71 6c if the zSql
1f260 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 input text cont
1f270 61 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f ains more than o
1f280 6e 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ne SQL statement
1f290 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 .** and
1f2a0 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e pzTail is not N
1f2b0 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69 ULL, then *pzTai
1f2c0 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 l is made to poi
1f2d0 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 nt to the.**
1f2e0 20 20 20 20 20 20 66 69 72 73 74 20 62 79 74 65 first byte
1f2f0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 past the end of
1f300 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 the first SQL s
1f310 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c tatement in zSql
1f320 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 ..** <t
1f330 6f 64 6f 3e 57 68 61 74 20 64 6f 65 73 20 2a 70 odo>What does *p
1f340 7a 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69 zTail point to i
1f350 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65 20 73 f there is one s
1f360 74 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e tatement?</todo>
1f370 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 36 7d 20 .**.** {H13016}
1f380 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c A successful cal
1f390 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 l to [sqlite3_pr
1f3a0 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c epare_v2(db,zSql
1f3b0 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a ,N,ppStmt,...)].
1f3c0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 6f ** or o
1f3d0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e ne of its varian
1f3e0 74 73 20 77 72 69 74 65 73 20 69 6e 74 6f 20 2a ts writes into *
1f3f0 70 70 53 74 6d 74 20 61 20 70 6f 69 6e 74 65 72 ppStmt a pointer
1f400 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 to a new.**
1f410 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 [prepared
1f420 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20 statement] or a
1f430 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 pointer to NULL
1f440 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73 if zSql contains
1f450 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74 .** not
1f460 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 hing other than
1f470 77 68 69 74 65 73 70 61 63 65 20 6f 72 20 63 6f whitespace or co
1f480 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 mments..**.** {H
1f490 31 33 30 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 13019} The [sqli
1f4a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1f4b0 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 ] interface and
1f4c0 69 74 73 20 76 61 72 69 61 6e 74 73 20 72 65 74 its variants ret
1f4d0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 urn.**
1f4e0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 [SQLITE_OK] or a
1f4f0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 n appropriate [e
1f500 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 rror code] upon
1f510 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b failure..**.** {
1f520 48 31 33 30 32 31 7d 20 42 65 66 6f 72 65 20 5b H13021} Before [
1f530 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
1f540 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 db,zSql,nByte,pp
1f550 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 Stmt,pzTail)] or
1f560 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 its.**
1f570 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e variants return
1f580 73 20 61 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 s an error (any
1f590 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e value other than
1f5a0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 2c 0a 2a [SQLITE_OK]),.*
1f5b0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 79 20 * they
1f5c0 66 69 72 73 74 20 73 65 74 20 2a 70 70 53 74 6d first set *ppStm
1f5d0 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e t to NULL..*/.in
1f5e0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
1f5f0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 e(. sqlite3 *db
1f600 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
1f610 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
1f620 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
1f630 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
1f640 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
1f650 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a TF-8 encoded */.
1f660 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
1f670 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
1f680 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
1f690 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
1f6a0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
1f6b0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
1f6c0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
1f6d0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
1f6e0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 har **pzTail
1f6f0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
1f700 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
1f710 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
1f720 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 .int sqlite3_pre
1f730 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 pare_v2(. sqlit
1f740 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
1f750 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
1f760 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
1f770 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 char *zSql,
1f780 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
1f790 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 ent, UTF-8 encod
1f7a0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
1f7b0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
1f7c0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 /* Maximum lengt
1f7d0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
1f7e0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 es. */. sqlite3
1f7f0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
1f800 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
1f810 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
1f820 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 onst char **pzTa
1f830 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
1f840 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
1f850 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
1f860 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
1f870 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 e3_prepare16(.
1f880 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
1f890 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
1f8a0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
1f8b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c const void *zSql
1f8c0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 , /* SQL s
1f8d0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 tatement, UTF-16
1f8e0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
1f8f0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
1f900 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
1f910 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
1f920 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
1f930 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
1f940 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
1f950 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
1f960 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
1f970 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
1f980 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
1f990 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
1f9a0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 f zSql */.);.int
1f9b0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
1f9c0 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 16_v2(. sqlite3
1f9d0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
1f9e0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
1f9f0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
1fa00 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 oid *zSql,
1fa10 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
1fa20 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 t, UTF-16 encode
1fa30 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
1fa40 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
1fa50 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
1fa60 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
1fa70 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
1fa80 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
1fa90 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
1faa0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
1fab0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 nst void **pzTai
1fac0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
1fad0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
1fae0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
1faf0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
1fb00 49 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 IREF: Retrieving
1fb10 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b Statement SQL {
1fb20 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30 3e H13100} <H13000>
1fb30 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
1fb40 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
1fb50 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 d to retrieve a
1fb60 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 saved copy of th
1fb70 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 e original.** SQ
1fb80 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 L text used to c
1fb90 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 reate a [prepare
1fba0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 d statement] if
1fbb0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 that statement w
1fbc0 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 as.** compiled u
1fbd0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c sing either [sql
1fbe0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1fbf0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
1fc00 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a repare16_v2()]..
1fc10 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
1fc20 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 31 7d :.**.** {H13101}
1fc30 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 If the [prepare
1fc40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 d statement] pas
1fc50 73 65 64 20 61 73 20 74 68 65 20 61 72 67 75 6d sed as the argum
1fc60 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 ent to.**
1fc70 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 [sqlite3_sql(
1fc80 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 )] was compiled
1fc90 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 using either [sq
1fca0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1fcb0 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 ()] or.**
1fcc0 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 [sqlite3_prep
1fcd0 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 74 68 65 are16_v2()], the
1fce0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 n [sqlite3_sql()
1fcf0 5d 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 ] returns.**
1fd00 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20 a pointer
1fd10 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
1fd20 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 ated string cont
1fd30 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72 aining a UTF-8 r
1fd40 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20 endering.**
1fd50 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67 of the orig
1fd60 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 inal SQL stateme
1fd70 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 nt..**.** {H1310
1fd80 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 2} If the [prepa
1fd90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 red statement] p
1fda0 61 73 73 65 64 20 61 73 20 74 68 65 20 61 72 67 assed as the arg
1fdb0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 ument to.**
1fdc0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71 [sqlite3_sq
1fdd0 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 l()] was compile
1fde0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b d using either [
1fdf0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
1fe00 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 )] or.**
1fe10 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 [sqlite3_prepa
1fe20 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 5b 73 re16()], then [s
1fe30 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 72 65 qlite3_sql()] re
1fe40 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
1fe50 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 nter..**.** {H13
1fe60 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e 67 20 103} The string
1fe70 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
1fe80 69 74 65 33 5f 73 71 6c 28 53 29 5d 20 69 73 20 ite3_sql(S)] is
1fe90 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 0a valid until the.
1fea0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 ** [pre
1feb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1fec0 20 53 20 69 73 20 64 65 6c 65 74 65 64 20 75 73 S is deleted us
1fed0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
1fee0 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f alize(S)]..*/.co
1fef0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
1ff00 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 3_sql(sqlite3_st
1ff10 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
1ff20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e ** CAPI3REF: Dyn
1ff30 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 amically Typed V
1ff40 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b 48 31 35 alue Object {H15
1ff50 30 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 000} <S20200>.**
1ff60 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 KEYWORDS: {prot
1ff70 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
1ff80 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 lue} {unprotecte
1ff90 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d d sqlite3_value}
1ffa0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 .**.** SQLite us
1ffb0 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 es the sqlite3_v
1ffc0 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 alue object to r
1ffd0 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c epresent all val
1ffe0 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 ues.** that can
1fff0 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 be stored in a d
20000 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 atabase table. S
20010 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d QLite uses dynam
20020 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 ic typing.** for
20030 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 the values it s
20040 74 6f 72 65 73 2e 20 56 61 6c 75 65 73 20 73 74 tores. Values st
20050 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f ored in sqlite3_
20060 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a value objects.**
20070 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 can be integers
20080 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 , floating point
20090 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 values, strings
200a0 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c , BLOBs, or NULL
200b0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 ..**.** An sqlit
200c0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
200d0 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 may be either "p
200e0 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e rotected" or "un
200f0 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 protected"..** S
20100 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 ome interfaces r
20110 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 equire a protect
20120 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
20130 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 . Other interfa
20140 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 ces.** will acce
20150 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 pt either a prot
20160 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 ected or an unpr
20170 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
20180 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 value..** Every
20190 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 interface that a
201a0 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 ccepts sqlite3_v
201b0 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 alue arguments s
201c0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 pecifies.** whet
201d0 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 her or not it re
201e0 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 quires a protect
201f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
20200 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d ..**.** The term
20210 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e s "protected" an
20220 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 d "unprotected"
20230 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 refer to whether
20240 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 or not.** a mut
20250 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 ex is held. A i
20260 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 nternal mutex is
20270 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 held for a prot
20280 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
20290 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 _value object bu
202a0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 t no mutex is he
202b0 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 ld for an unprot
202c0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
202d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 _value object.
202e0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
202f0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 piled to be sing
20300 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 le-threaded.** (
20310 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 with [SQLITE_THR
20320 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 EADSAFE=0] and w
20330 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 ith [sqlite3_thr
20340 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 eadsafe()] retur
20350 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 ning 0).** or if
20360 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 SQLite is run i
20370 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 n one of reduced
20380 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a mutex modes .**
20390 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
203a0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 SINGLETHREAD] or
203b0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
203c0 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 MULTITHREAD].**
203d0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f then there is no
203e0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 distinction bet
203f0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 ween protected a
20400 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a nd unprotected.*
20410 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
20420 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 objects and they
20430 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 can be used int
20440 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 erchangeably. H
20450 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d owever,.** for m
20460 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 aximum code port
20470 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 ability it is re
20480 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 commended that a
20490 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
204a0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 till make the di
204b0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 stinction betwee
204c0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 n between protec
204d0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 ted and unprotec
204e0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 ted.** sqlite3_v
204f0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 alue objects eve
20500 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 n when not stric
20510 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a tly required..**
20520 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
20530 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 value objects th
20540 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 at are passed as
20550 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f parameters into
20560 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e the.** implemen
20570 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 tation of [appli
20580 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
20590 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 QL functions] ar
205a0 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 e protected..**
205b0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
205c0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 e object returne
205d0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 d by.** [sqlite3
205e0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d _column_value()]
205f0 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e is unprotected.
20600 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 .** Unprotected
20610 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
20620 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 jects may only b
20630 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b e used with.** [
20640 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
20650 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c alue()] and [sql
20660 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
20670 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 )]..** The [sqli
20680 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c te3_value_blob |
20690 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
206a0 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 ype()] family of
206b0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 .** interfaces r
206c0 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 equire protected
206d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
206e0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 bjects..*/.typed
206f0 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 ef struct Mem sq
20700 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a lite3_value;../*
20710 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 .** CAPI3REF: SQ
20720 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 L Function Conte
20730 78 74 20 4f 62 6a 65 63 74 20 7b 48 31 36 30 30 xt Object {H1600
20740 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 1} <S20200>.**.*
20750 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e * The context in
20760 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 which an SQL fu
20770 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 nction executes
20780 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a is stored in an.
20790 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ** sqlite3_conte
207a0 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f xt object. A po
207b0 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 inter to an sqli
207c0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 te3_context obje
207d0 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 ct.** is always
207e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
207f0 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d to [application-
20800 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
20810 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 tions]..** The a
20820 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
20830 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ed SQL function
20840 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
20850 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a ill pass this.**
20860 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 pointer through
20870 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b into calls to [
20880 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 sqlite3_result_i
20890 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 nt | sqlite3_res
208a0 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ult()],.** [sqli
208b0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
208c0 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 ntext()], [sqlit
208d0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c e3_user_data()],
208e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
208f0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 text_db_handle()
20900 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f ], [sqlite3_get_
20910 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 auxdata()],.** a
20920 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 nd/or [sqlite3_s
20930 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a et_auxdata()]..*
20940 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
20950 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
20960 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
20970 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
20980 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 F: Binding Value
20990 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 s To Prepared St
209a0 61 74 65 6d 65 6e 74 73 20 7b 48 31 33 35 30 30 atements {H13500
209b0 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 20 4b 45 } <S70300>.** KE
209c0 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 YWORDS: {host pa
209d0 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 rameter} {host p
209e0 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 arameters} {host
209f0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d parameter name}
20a00 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 .** KEYWORDS: {S
20a10 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 QL parameter} {S
20a20 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b QL parameters} {
20a30 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e parameter bindin
20a40 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 g}.**.** In the
20a50 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75 SQL strings inpu
20a60 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 t to [sqlite3_pr
20a70 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
20a80 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a its variants,.**
20a90 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 literals may be
20aa0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 70 replaced by a p
20ab0 61 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20 arameter in one
20ac0 6f 66 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a of these forms:.
20ad0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
20ae0 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f i> ?.** <li> ?
20af0 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 NNN.** <li> :VV
20b00 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a V.** <li> @VVV.
20b10 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a ** <li> $VVV.**
20b20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 </ul>.**.** In
20b30 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f the parameter fo
20b40 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 rms shown above
20b50 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 NNN is an intege
20b60 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e r literal,.** an
20b70 64 20 56 56 56 20 69 73 20 61 6e 20 61 6c 70 68 d VVV is an alph
20b80 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65 a-numeric parame
20b90 74 65 72 20 6e 61 6d 65 2e 20 54 68 65 20 76 61 ter name. The va
20ba0 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a lues of these.**
20bb0 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 parameters (als
20bc0 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 o called "host p
20bd0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 arameter names"
20be0 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 or "SQL paramete
20bf0 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 rs").** can be s
20c00 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c et using the sql
20c10 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f ite3_bind_*() ro
20c20 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 utines defined h
20c30 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ere..**.** The f
20c40 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
20c50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
20c60 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 d_*() routines i
20c70 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f s always.** a po
20c80 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 inter to the [sq
20c90 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 lite3_stmt] obje
20ca0 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d ct returned from
20cb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
20cc0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 pare_v2()] or it
20cd0 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a s variants..**.*
20ce0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 * The second arg
20cf0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 ument is the ind
20d00 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 ex of the SQL pa
20d10 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 rameter to be se
20d20 74 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f t..** The leftmo
20d30 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 st SQL parameter
20d40 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 has an index of
20d50 20 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73 61 1. When the sa
20d60 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 me named.** SQL
20d70 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 parameter is use
20d80 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 d more than once
20d90 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 , second and sub
20da0 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 sequent.** occur
20db0 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 rences have the
20dc0 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 same index as th
20dd0 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e e first occurren
20de0 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 ce..** The index
20df0 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d for named param
20e00 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f eters can be loo
20e10 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 ked up using the
20e20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
20e30 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
20e40 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 x()] API if desi
20e50 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a red. The index.
20e60 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 ** for "?NNN" pa
20e70 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 rameters is the
20e80 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a value of NNN..**
20e90 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d The NNN value m
20ea0 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 ust be between 1
20eb0 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 and the [sqlite
20ec0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 3_limit()].** pa
20ed0 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f rameter [SQLITE_
20ee0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
20ef0 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 UMBER] (default
20f00 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a value: 999)..**.
20f10 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67 ** The third arg
20f20 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c ument is the val
20f30 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 ue to bind to th
20f40 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a e parameter..**.
20f50 2a 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 ** In those rout
20f60 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 ines that have a
20f70 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
20f80 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 , its value is t
20f90 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
20fa0 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 bytes in the par
20fb0 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 ameter. To be c
20fc0 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 lear: the value
20fd0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 is the.** number
20fe0 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e of <u>bytes</u>
20ff0 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e in the value, n
21000 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ot the number of
21010 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 characters..**
21020 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
21030 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 rameter is negat
21040 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 ive, the length
21050 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 of the string is
21060 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
21070 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 f bytes up to th
21080 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 e first zero ter
21090 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 minator..**.** T
210a0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e he fifth argumen
210b0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e t to sqlite3_bin
210c0 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 d_blob(), sqlite
210d0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 3_bind_text(), a
210e0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 nd.** sqlite3_bi
210f0 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 nd_text16() is a
21100 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 destructor used
21110 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 to dispose of t
21120 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 he BLOB or.** st
21130 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 ring after SQLit
21140 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 e has finished w
21150 69 74 68 20 69 74 2e 20 49 66 20 74 68 65 20 66 ith it. If the f
21160 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 ifth argument is
21170 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 .** the special
21180 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 value [SQLITE_ST
21190 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 ATIC], then SQLi
211a0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 te assumes that
211b0 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 the.** informati
211c0 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c on is in static,
211d0 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 unmanaged space
211e0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 and does not ne
211f0 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a ed to be freed..
21200 2a 2a 20 49 66 20 74 68 65 20 66 69 66 74 68 20 ** If the fifth
21210 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 argument has the
21220 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 value [SQLITE_T
21230 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a RANSIENT], then.
21240 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ** SQLite makes
21250 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
21260 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 copy of the data
21270 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 immediately, be
21280 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 fore.** the sqli
21290 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
212a0 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a tine returns..**
212b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
212c0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 bind_zeroblob()
212d0 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 routine binds a
212e0 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e BLOB of length N
212f0 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c that.** is fill
21300 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 ed with zeroes.
21310 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 A zeroblob uses
21320 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 a fixed amount
21330 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 of memory.** (ju
21340 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f st an integer to
21350 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 hold its size)
21360 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e while it is bein
21370 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 g processed..**
21380 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e Zeroblobs are in
21390 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 tended to serve
213a0 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 as placeholders
213b0 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a for BLOBs whose.
213c0 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 ** content is la
213d0 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e ter written usin
213e0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c g.** [sqlite3_bl
213f0 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d ob_open | increm
21400 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 ental BLOB I/O]
21410 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e routines..** A n
21420 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f egative value fo
21430 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 r the zeroblob r
21440 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f esults in a zero
21450 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a -length BLOB..**
21460 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
21470 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
21480 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 s must be called
21490 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 after.** [sqlit
214a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
214b0 20 28 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e (and its varian
214c0 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ts) or [sqlite3_
214d0 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 reset()] and.**
214e0 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f before [sqlite3_
214f0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 step()]..** Bind
21500 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 ings are not cle
21510 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c ared by the [sql
21520 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f ite3_reset()] ro
21530 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e utine..** Unboun
21540 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 d parameters are
21550 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
21560 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 NULL..**.** Thes
21570 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 e routines retur
21580 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e n [SQLITE_OK] on
21590 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65 success or an e
215a0 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 rror code if.**
215b0 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 anything goes wr
215c0 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 ong. [SQLITE_RA
215d0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 NGE] is returned
215e0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
215f0 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 r.** index is ou
21600 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 t of range. [SQ
21610 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 LITE_NOMEM] is r
21620 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f eturned if mallo
21630 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 c() fails..** [S
21640 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 QLITE_MISUSE] mi
21650 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 ght be returned
21660 69 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 if these routine
21670 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 s are called on
21680 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 a.** virtual mac
21690 68 69 6e 65 20 74 68 61 74 20 69 73 20 74 68 65 hine that is the
216a0 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 wrong state or
216b0 77 68 69 63 68 20 68 61 73 20 61 6c 72 65 61 64 which has alread
216c0 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 y been finalized
216d0 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f ..** Detection o
216e0 66 20 6d 69 73 75 73 65 20 69 73 20 75 6e 72 65 f misuse is unre
216f0 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 liable. Applica
21700 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 tions should not
21710 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 depend.** on SQ
21720 4c 49 54 45 5f 4d 49 53 55 53 45 20 72 65 74 75 LITE_MISUSE retu
21730 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 rns. SQLITE_MIS
21740 55 53 45 20 69 73 20 69 6e 74 65 6e 64 65 64 20 USE is intended
21750 74 6f 20 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a to indicate a.**
21760 20 61 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 a logic error i
21770 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f n the applicatio
21780 6e 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 n. Future versi
21790 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 ons of SQLite mi
217a0 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 ght.** panic rat
217b0 68 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e 20 her than return
217c0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a SQLITE_MISUSE..*
217d0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
217e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
217f0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
21800 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
21810 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
21820 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
21830 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
21840 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a _index()]..**.**
21850 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
21860 2a 2a 20 7b 48 31 33 35 30 36 7d 20 54 68 65 20 ** {H13506} The
21870 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 [SQL statement c
21880 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69 ompiler] recogni
21890 7a 65 73 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 zes tokens of th
218a0 65 20 66 6f 72 6d 73 0a 2a 2a 20 20 20 20 20 20 e forms.**
218b0 20 20 20 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c "?", "?NNN",
218c0 20 22 24 56 56 56 22 2c 20 22 3a 56 56 56 22 2c "$VVV", ":VVV",
218d0 20 61 6e 64 20 22 40 56 56 56 22 20 61 73 20 53 and "@VVV" as S
218e0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2c 0a 2a QL parameters,.*
218f0 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65 * where
21900 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65 71 75 NNN is any sequ
21910 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d ence of one or m
21920 6f 72 65 20 64 69 67 69 74 73 0a 2a 2a 20 20 20 ore digits.**
21930 20 20 20 20 20 20 20 61 6e 64 20 77 68 65 72 65 and where
21940 20 56 56 56 20 69 73 20 61 6e 79 20 73 65 71 75 VVV is any sequ
21950 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d ence of one or m
21960 6f 72 65 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 ore alphanumeric
21970 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68 61 .** cha
21980 72 61 63 74 65 72 73 20 6f 72 20 22 3a 3a 22 20 racters or "::"
21990 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f optionally follo
219a0 77 65 64 20 62 79 20 61 20 73 74 72 69 6e 67 20 wed by a string
219b0 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 containing.**
219c0 20 20 20 20 20 20 20 6e 6f 20 73 70 61 63 65 73 no spaces
219d0 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20 77 and contained w
219e0 69 74 68 69 6e 20 70 61 72 65 6e 74 68 65 73 65 ithin parenthese
219f0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 39 s..**.** {H13509
21a00 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 20 76 61 } The initial va
21a10 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 lue of an SQL pa
21a20 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 2e rameter is NULL.
21a30 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 32 7d 20 .**.** {H13512}
21a40 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 The index of an
21a50 22 3f 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 "?" SQL paramete
21a60 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 65 72 20 r is one larger
21a70 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 than the.**
21a80 20 20 20 20 20 6c 61 72 67 65 73 74 20 69 6e 64 largest ind
21a90 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 ex of SQL parame
21aa0 74 65 72 20 74 6f 20 74 68 65 20 6c 65 66 74 2c ter to the left,
21ab0 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20 20 20 or 1 if.**
21ac0 20 20 20 20 20 74 68 65 20 22 3f 22 20 69 73 20 the "?" is
21ad0 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c the leftmost SQL
21ae0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
21af0 2a 20 7b 48 31 33 35 31 35 7d 20 54 68 65 20 69 * {H13515} The i
21b00 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e ndex of an "?NNN
21b10 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 " SQL parameter
21b20 69 73 20 74 68 65 20 69 6e 74 65 67 65 72 20 4e is the integer N
21b30 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 NN..**.** {H1351
21b40 38 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 8} The index of
21b50 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 56 56 56 an ":VVV", "$VVV
21b60 22 2c 20 6f 72 20 22 40 56 56 56 22 20 53 51 4c ", or "@VVV" SQL
21b70 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a parameter is.**
21b80 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 the sa
21b90 6d 65 20 61 73 20 74 68 65 20 69 6e 64 65 78 20 me as the index
21ba0 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63 75 of leftmost occu
21bb0 72 72 65 6e 63 65 73 20 6f 66 20 74 68 65 20 73 rrences of the s
21bc0 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ame.**
21bd0 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e parameter, or on
21be0 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 65 20 e more than the
21bf0 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 76 largest index ov
21c00 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 er all.**
21c10 20 20 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f parameters to
21c20 20 74 68 65 20 6c 65 66 74 20 69 66 20 74 68 69 the left if thi
21c30 73 20 69 73 20 74 68 65 20 66 69 72 73 74 20 6f s is the first o
21c40 63 63 75 72 72 65 6e 63 65 0a 2a 2a 20 20 20 20 ccurrence.**
21c50 20 20 20 20 20 20 6f 66 20 74 68 69 73 20 70 61 of this pa
21c60 72 61 6d 65 74 65 72 2c 20 6f 72 20 31 20 69 66 rameter, or 1 if
21c70 20 74 68 69 73 20 69 73 20 74 68 65 20 6c 65 66 this is the lef
21c80 74 6d 6f 73 74 20 70 61 72 61 6d 65 74 65 72 2e tmost parameter.
21c90 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 31 7d 20 .**.** {H13521}
21ca0 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 The [SQL stateme
21cb0 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61 69 nt compiler] fai
21cc0 6c 73 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 ls with an [SQLI
21cd0 54 45 5f 52 41 4e 47 45 5d 0a 2a 2a 20 20 20 20 TE_RANGE].**
21ce0 20 20 20 20 20 20 65 72 72 6f 72 20 69 66 20 74 error if t
21cf0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 he index of an S
21d00 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 QL parameter is
21d10 6c 65 73 73 20 74 68 61 6e 20 31 0a 2a 2a 20 20 less than 1.**
21d20 20 20 20 20 20 20 20 20 6f 72 20 67 72 65 61 74 or great
21d30 65 72 20 74 68 61 6e 20 74 68 65 20 63 6f 6d 70 er than the comp
21d40 69 6c 65 2d 74 69 6d 65 20 53 51 4c 49 54 45 5f ile-time SQLITE_
21d50 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MAX_VARIABLE_NUM
21d60 42 45 52 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 BER.**
21d70 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
21d80 20 7b 48 31 33 35 32 34 7d 20 43 61 6c 6c 73 20 {H13524} Calls
21d90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 to [sqlite3_bind
21da0 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f _text | sqlite3_
21db0 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d bind(S,N,V,...)]
21dc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 .** ass
21dd0 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c 75 65 ociate the value
21de0 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51 4c 20 V with all SQL
21df0 70 61 72 61 6d 65 74 65 72 73 20 68 61 76 69 6e parameters havin
21e00 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 g an.**
21e10 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e 20 74 index of N in t
21e20 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
21e30 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a tement] S..**.**
21e40 20 7b 48 31 33 35 32 37 7d 20 43 61 6c 6c 73 20 {H13527} Calls
21e50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 to [sqlite3_bind
21e60 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f _text | sqlite3_
21e70 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a bind(S,N,...)].*
21e80 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72 72 * overr
21e90 69 64 65 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 ide prior calls
21ea0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76 61 with the same va
21eb0 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 20 4e 2e lues of S and N.
21ec0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 30 7d 20 .**.** {H13530}
21ed0 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62 6c 69 Bindings establi
21ee0 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 shed by [sqlite3
21ef0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c _bind_text | sql
21f00 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e 29 ite3_bind(S,...)
21f10 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 65 ].** pe
21f20 72 73 69 73 74 20 61 63 72 6f 73 73 20 63 61 6c rsist across cal
21f30 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 ls to [sqlite3_r
21f40 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 eset(S)]..**.**
21f50 7b 48 31 33 35 33 33 7d 20 49 6e 20 63 61 6c 6c {H13533} In call
21f60 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 s to [sqlite3_bi
21f70 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c nd_blob(S,N,V,L,
21f80 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 D)],.**
21f90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 [sqlite3_bind_t
21fa0 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c ext(S,N,V,L,D)],
21fb0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
21fc0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 [sqlite3_bind_te
21fd0 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d xt16(S,N,V,L,D)]
21fe0 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 74 68 SQLite binds th
21ff0 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20 20 20 e first L.**
22000 20 20 20 20 20 20 62 79 74 65 73 20 6f 66 20 74 bytes of t
22010 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e he BLOB or strin
22020 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 g pointed to by
22030 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20 20 20 V, when L.**
22040 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e 65 67 is non-neg
22050 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ative..**.** {H1
22060 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73 20 74 3536} In calls t
22070 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f o [sqlite3_bind_
22080 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d text(S,N,V,L,D)]
22090 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
220a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 [sqlite3_bind_te
220b0 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d xt16(S,N,V,L,D)]
220c0 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 63 68 SQLite binds ch
220d0 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 20 20 20 aracters.**
220e0 20 20 20 20 20 66 72 6f 6d 20 56 20 74 68 72 6f from V thro
220f0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 ugh the first ze
22100 72 6f 20 63 68 61 72 61 63 74 65 72 20 77 68 65 ro character whe
22110 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e n L is negative.
22120 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 39 7d 20 .**.** {H13539}
22130 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c In calls to [sql
22140 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 ite3_bind_blob(S
22150 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 ,N,V,L,D)],.**
22160 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
22170 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 _bind_text(S,N,V
22180 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 ,L,D)], or.**
22190 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
221a0 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c bind_text16(S,N,
221b0 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 V,L,D)] when D i
221c0 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a s the special.**
221d0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61 consta
221e0 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 nt [SQLITE_STATI
221f0 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d C], SQLite assum
22200 65 73 20 74 68 61 74 20 74 68 65 20 76 61 6c 75 es that the valu
22210 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 e V.**
22220 69 73 20 68 65 6c 64 20 69 6e 20 73 74 61 74 69 is held in stati
22230 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 c unmanaged spac
22240 65 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f 74 20 e that will not
22250 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 change.**
22260 20 20 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 during the li
22270 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 62 69 fetime of the bi
22280 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 nding..**.** {H1
22290 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73 20 74 3542} In calls t
222a0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f o [sqlite3_bind_
222b0 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d blob(S,N,V,L,D)]
222c0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 ,.** [s
222d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
222e0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 (S,N,V,L,D)], or
222f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
22300 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
22310 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 6(S,N,V,L,D)] wh
22320 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63 en D is the spec
22330 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ial.**
22340 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 constant [SQLITE
22350 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 _TRANSIENT], the
22360 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73 20 61 routine makes a
22370 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 .** pri
22380 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 vate copy of the
22390 20 76 61 6c 75 65 20 56 20 62 65 66 6f 72 65 20 value V before
223a0 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a it returns..**.*
223b0 2a 20 7b 48 31 33 35 34 35 7d 20 49 6e 20 63 61 * {H13545} In ca
223c0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
223d0 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c bind_blob(S,N,V,
223e0 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 L,D)],.**
223f0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 [sqlite3_bind
22400 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 _text(S,N,V,L,D)
22410 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 ], or.**
22420 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f [sqlite3_bind_
22430 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 text16(S,N,V,L,D
22440 29 5d 20 77 68 65 6e 20 44 20 69 73 20 61 20 70 )] when D is a p
22450 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 ointer to.**
22460 20 20 20 20 20 20 61 20 66 75 6e 63 74 69 6f 6e a function
22470 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 , SQLite invokes
22480 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 74 that function t
22490 6f 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a o destroy the.**
224a0 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 value
224b0 56 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 V after it has f
224c0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 inished using th
224d0 65 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a e value V..**.**
224e0 20 7b 48 31 33 35 34 38 7d 20 49 6e 20 63 61 6c {H13548} In cal
224f0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 ls to [sqlite3_b
22500 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e ind_zeroblob(S,N
22510 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75 65 ,V,L)] the value
22520 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20 20 bound.**
22530 20 20 20 69 73 20 61 20 42 4c 4f 42 20 6f 66 20 is a BLOB of
22540 4c 20 62 79 74 65 73 2c 20 6f 72 20 61 20 7a 65 L bytes, or a ze
22550 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 ro-length BLOB i
22560 66 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e f L is negative.
22570 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 35 31 7d 20 .**.** {H13551}
22580 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c In calls to [sql
22590 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
225a0 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20 61 72 S,N,V)] the V ar
225b0 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20 20 gument may.**
225c0 20 20 20 20 20 20 20 62 65 20 65 69 74 68 65 72 be either
225d0 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 a [protected sq
225e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
225f0 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 ect or an.**
22600 20 20 20 20 20 20 5b 75 6e 70 72 6f 74 65 63 74 [unprotect
22610 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
22620 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 ] object..*/.int
22630 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
22640 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ob(sqlite3_stmt*
22650 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 , int, const voi
22660 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 d*, int n, void(
22670 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 *)(void*));.int
22680 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 sqlite3_bind_dou
22690 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ble(sqlite3_stmt
226a0 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b *, int, double);
226b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
226c0 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 d_int(sqlite3_st
226d0 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a mt*, int, int);.
226e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
226f0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 _int64(sqlite3_s
22700 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 tmt*, int, sqlit
22710 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 e3_int64);.int s
22720 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c qlite3_bind_null
22730 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
22740 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 int);.int sqlite
22750 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 3_bind_text(sqli
22760 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
22770 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 const char*, int
22780 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 n, void(*)(void
22790 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 *));.int sqlite3
227a0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c _bind_text16(sql
227b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
227c0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
227d0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
227e0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f ));.int sqlite3_
227f0 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 bind_value(sqlit
22800 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
22810 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c onst sqlite3_val
22820 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ue*);.int sqlite
22830 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 3_bind_zeroblob(
22840 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
22850 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a nt, int n);../*.
22860 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d ** CAPI3REF: Num
22870 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d ber Of SQL Param
22880 65 74 65 72 73 20 7b 48 31 33 36 30 30 7d 20 3c eters {H13600} <
22890 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S70300>.**.** Th
228a0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 is routine can b
228b0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 e used to find t
228c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 he number of [SQ
228d0 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a L parameters].**
228e0 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 in a [prepared
228f0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c statement]. SQL
22900 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 parameters are
22910 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a tokens of the.**
22920 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e form "?", "?NNN
22930 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 ", ":AAA", "$AAA
22940 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 ", or "@AAA" tha
22950 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c t serve as.** pl
22960 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 aceholders for v
22970 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b alues that are [
22980 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
22990 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f b | bound].** to
229a0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 the parameters
229b0 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e at a later time.
229c0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
229d0 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 ine actually ret
229e0 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f urns the index o
229f0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 f the largest (r
22a00 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 ightmost).** par
22a10 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 ameter. For all
22a20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e forms except ?NN
22a30 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 N, this will cor
22a40 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a respond to the.*
22a50 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 * number of uniq
22a60 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ue parameters.
22a70 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 If parameters of
22a80 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 the ?NNN are us
22a90 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 ed,.** there may
22aa0 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 be gaps in the
22ab0 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 list..**.** See
22ac0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 also: [sqlite3_b
22ad0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
22ae0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _bind()],.** [sq
22af0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
22b00 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e eter_name()], an
22b10 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
22b20 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
22b30 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 ex()]..**.** INV
22b40 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
22b50 48 31 33 36 30 31 7d 20 54 68 65 20 5b 73 71 6c H13601} The [sql
22b60 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
22b70 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e ter_count(S)] in
22b80 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a terface returns.
22b90 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
22ba0 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66 largest index of
22bb0 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 all SQL paramet
22bc0 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 ers in the.**
22bd0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 [prepared
22be0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f statement] S, o
22bf0 72 20 30 20 69 66 20 53 20 63 6f 6e 74 61 69 6e r 0 if S contain
22c00 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 s no SQL paramet
22c10 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ers..*/.int sqli
22c20 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
22c30 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 er_count(sqlite3
22c40 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
22c50 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f CAPI3REF: Name O
22c60 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 f A Host Paramet
22c70 65 72 20 7b 48 31 33 36 32 30 7d 20 3c 53 37 30 er {H13620} <S70
22c80 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 300>.**.** This
22c90 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
22ca0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
22cb0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 name of the n-t
22cc0 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65 h.** [SQL parame
22cd0 74 65 72 5d 20 69 6e 20 61 20 5b 70 72 65 70 61 ter] in a [prepa
22ce0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
22cf0 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 ** SQL parameter
22d00 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f s of the form "?
22d10 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f NNN" or ":AAA" o
22d20 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 r "@AAA" or "$AA
22d30 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d A".** have a nam
22d40 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 e which is the s
22d50 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 tring "?NNN" or
22d60 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 ":AAA" or "@AAA"
22d70 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 or "$AAA".** re
22d80 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 spectively..** I
22d90 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 n other words, t
22da0 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f he initial ":" o
22db0 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 r "$" or "@" or
22dc0 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 "?".** is includ
22dd0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 ed as part of th
22de0 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d e name..** Param
22df0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 eters of the for
22e00 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 m "?" without a
22e10 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 following intege
22e20 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a r have no name.*
22e30 2a 20 61 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 * and are also r
22e40 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 61 eferred to as "a
22e50 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 nonymous paramet
22e60 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ers"..**.** The
22e70 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d first host param
22e80 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 eter has an inde
22e90 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a x of 1, not 0..*
22ea0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75 *.** If the valu
22eb0 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 e n is out of ra
22ec0 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d nge or if the n-
22ed0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a th parameter is.
22ee0 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 ** nameless, the
22ef0 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e n NULL is return
22f00 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 ed. The returne
22f10 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 d string is.** a
22f20 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 lways in UTF-8 e
22f30 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 ncoding even if
22f40 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 the named parame
22f50 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 ter was.** origi
22f60 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 nally specified
22f70 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 as UTF-16 in [sq
22f80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
22f90 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
22fa0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
22fb0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 ]..**.** See als
22fc0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
22fd0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 _blob|sqlite3_bi
22fe0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nd()],.** [sqlit
22ff0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
23000 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a r_count()], and.
23010 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
23020 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
23030 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ()]..**.** INVAR
23040 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
23050 33 36 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 3621} The [sqlit
23060 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
23070 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 r_name(S,N)] int
23080 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a erface returns.*
23090 2a 20 20 20 20 20 20 20 20 20 20 61 20 55 54 46 * a UTF
230a0 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 -8 rendering of
230b0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
230c0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e SQL parameter in
230d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
230e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
230f0 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e 67 20 69 ment] S having i
23100 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20 20 ndex N, or.**
23110 20 20 20 20 20 20 20 4e 55 4c 4c 20 69 66 20 74 NULL if t
23120 68 65 72 65 20 69 73 20 6e 6f 20 53 51 4c 20 70 here is no SQL p
23130 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e arameter with in
23140 64 65 78 20 4e 20 6f 72 20 69 66 20 74 68 65 0a dex N or if the.
23150 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 ** para
23160 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64 65 78 meter with index
23170 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e 79 6d 6f N is an anonymo
23180 75 73 20 70 61 72 61 6d 65 74 65 72 20 22 3f 22 us parameter "?"
23190 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 ..*/.const char
231a0 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 *sqlite3_bind_pa
231b0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c rameter_name(sql
231c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 ite3_stmt*, int)
231d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
231e0 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 F: Index Of A Pa
231f0 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 rameter With A G
23200 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33 36 34 iven Name {H1364
23210 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 0} <S70300>.**.*
23220 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 * Return the ind
23230 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 ex of an SQL par
23240 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 ameter given its
23250 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 name. The.** i
23260 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 ndex value retur
23270 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 ned is suitable
23280 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 for use as the s
23290 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 econd.** paramet
232a0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 er to [sqlite3_b
232b0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
232c0 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 _bind()]. A zer
232d0 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 o.** is returned
232e0 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 if no matching
232f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 parameter is fou
23300 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74 nd. The paramet
23310 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 er.** name must
23320 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d be given in UTF-
23330 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 8 even if the or
23340 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 iginal statement
23350 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 .** was prepared
23360 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 from UTF-16 tex
23370 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
23380 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
23390 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
233a0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
233b0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
233c0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
233d0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
233e0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a _count()], and.*
233f0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
23400 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
23410 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 )]..**.** INVARI
23420 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 ANTS:.**.** {H13
23430 36 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 641} The [sqlite
23440 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
23450 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e 74 _index(S,N)] int
23460 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a erface returns.*
23470 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 69 * the i
23480 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 ndex of SQL para
23490 6d 65 74 65 72 20 69 6e 20 74 68 65 20 5b 70 72 meter in the [pr
234a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
234b0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 20 ].** S
234c0 77 68 6f 73 65 20 6e 61 6d 65 20 6d 61 74 63 68 whose name match
234d0 65 73 20 74 68 65 20 55 54 46 2d 38 20 73 74 72 es the UTF-8 str
234e0 69 6e 67 20 4e 2c 20 6f 72 20 30 20 69 66 20 74 ing N, or 0 if t
234f0 68 65 72 65 20 69 73 0a 2a 2a 20 20 20 20 20 20 here is.**
23500 20 20 20 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2f no match..*/
23510 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
23520 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
23530 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c x(sqlite3_stmt*,
23540 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
23550 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 me);../*.** CAPI
23560 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 3REF: Reset All
23570 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 Bindings On A Pr
23580 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
23590 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 30 33 30 {H13660} <S7030
235a0 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 0>.**.** Contrar
235b0 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 y to the intuiti
235c0 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c on of many, [sql
235d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f ite3_reset()] do
235e0 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 es not reset.**
235f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
23600 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 d_blob | binding
23610 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 s] on a [prepare
23620 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
23630 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e Use this routin
23640 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 e to reset all h
23650 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 ost parameters t
23660 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e o NULL..**.** IN
23670 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
23680 7b 48 31 33 36 36 31 7d 20 54 68 65 20 5b 73 71 {H13661} The [sq
23690 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 lite3_clear_bind
236a0 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72 66 61 ings(S)] interfa
236b0 63 65 20 72 65 73 65 74 73 20 61 6c 6c 20 53 51 ce resets all SQ
236c0 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 L.** pa
236d0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 73 rameter bindings
236e0 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 in the [prepare
236f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 62 d statement] S b
23700 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a ack to NULL..*/.
23710 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 int sqlite3_clea
23720 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 r_bindings(sqlit
23730 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
23740 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
23750 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e er Of Columns In
23760 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 A Result Set {H
23770 31 33 37 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 13710} <S10700>.
23780 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 **.** Return the
23790 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
237a0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ns in the result
237b0 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 set returned by
237c0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
237d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 d statement]. Th
237e0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
237f0 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 ns 0 if pStmt is
23800 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 an SQL.** state
23810 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e ment that does n
23820 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 ot return data (
23830 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b for example an [
23840 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 UPDATE])..**.**
23850 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
23860 2a 20 7b 48 31 33 37 31 31 7d 20 54 68 65 20 5b * {H13711} The [
23870 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
23880 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61 ount(S)] interfa
23890 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ce returns the n
238a0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 umber of.**
238b0 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 columns in
238c0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 67 the result set g
238d0 65 6e 65 72 61 74 65 64 20 62 79 20 74 68 65 20 enerated by the
238e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
238f0 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20 ent] S,.**
23900 20 20 20 20 6f 72 20 30 20 69 66 20 53 20 64 6f or 0 if S do
23910 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74 65 20 es not generate
23920 61 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f a result set..*/
23930 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
23940 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 umn_count(sqlite
23950 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
23960 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
23970 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e Column Names In
23980 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 A Result Set {H
23990 31 33 37 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 13720} <S10700>.
239a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
239b0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 ines return the
239c0 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f name assigned to
239d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f a particular co
239e0 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 lumn.** in the r
239f0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b esult set of a [
23a00 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
23a10 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f t. The sqlite3_
23a20 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a column_name().**
23a30 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
23a40 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
23a50 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
23a60 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a d UTF-8 string.*
23a70 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f * and sqlite3_co
23a80 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 lumn_name16() re
23a90 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
23aa0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
23ab0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 ated.** UTF-16 s
23ac0 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72 73 tring. The firs
23ad0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 t parameter is t
23ae0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
23af0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 tement].** that
23b00 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b implements the [
23b10 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
23b20 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 t. The second pa
23b30 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
23b40 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e * column number.
23b50 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 The leftmost c
23b60 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 olumn is number
23b70 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 0..**.** The ret
23b80 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 urned string poi
23b90 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e nter is valid un
23ba0 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b til either the [
23bb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
23bc0 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f nt].** is destro
23bd0 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f yed by [sqlite3_
23be0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 finalize()] or u
23bf0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 ntil the next ca
23c00 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ll to.** sqlite3
23c10 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f _column_name() o
23c20 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
23c30 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 _name16() on the
23c40 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a same column..**
23c50 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d .** If sqlite3_m
23c60 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 alloc() fails du
23c70 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 ring the process
23c80 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f ing of either ro
23c90 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 utine.** (for ex
23ca0 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 ample during a c
23cb0 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 onversion from U
23cc0 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 TF-8 to UTF-16)
23cd0 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 then a.** NULL p
23ce0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e ointer is return
23cf0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 ed..**.** The na
23d00 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 me of a result c
23d10 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c olumn is the val
23d20 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 ue of the "AS" c
23d30 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 lause for.** tha
23d40 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 t column, if the
23d50 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 re is an AS clau
23d60 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 se. If there is
23d70 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a no AS clause.**
23d80 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f then the name o
23d90 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 f the column is
23da0 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 unspecified and
23db0 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a may change from.
23dc0 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f ** one release o
23dd0 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 f SQLite to the
23de0 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 next..**.** INVA
23df0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
23e00 31 33 37 32 31 7d 20 41 20 73 75 63 63 65 73 73 13721} A success
23e10 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f ful invocation o
23e20 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 f the [sqlite3_c
23e30 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d olumn_name(S,N)]
23e40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 .** int
23e50 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
23e60 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e he name of the N
23e70 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 th column (where
23e80 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 0 is.**
23e90 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 the leftmost c
23ea0 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 72 olumn) for the r
23eb0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 esult set of the
23ec0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
23ed0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
23ee0 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 ] S as a zero-te
23ef0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
23f00 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 tring..**.** {H1
23f10 33 37 32 33 7d 20 41 20 73 75 63 63 65 73 73 66 3723} A successf
23f20 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 ul invocation of
23f30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
23f40 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 lumn_name16(S,N)
23f50 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e ].** in
23f60 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
23f70 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
23f80 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 Nth column (wher
23f90 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 e 0 is.**
23fa0 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 the leftmost
23fb0 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 column) for the
23fc0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 result set of th
23fd0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 e.** [p
23fe0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
23ff0 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d 74 t] S as a zero-t
24000 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 erminated UTF-16
24010 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 string.**
24020 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76 in the nativ
24030 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a e byte order..**
24040 0a 2a 2a 20 7b 48 31 33 37 32 34 7d 20 54 68 65 .** {H13724} The
24050 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
24060 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73 71 _name()] and [sq
24070 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
24080 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 e16()].**
24090 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 interfaces re
240a0 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e turn a NULL poin
240b0 74 65 72 20 69 66 20 74 68 65 79 20 61 72 65 20 ter if they are
240c0 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20 20 unable to.**
240d0 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 20 6d allocate m
240e0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
240f0 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 74 75 72 eir normal retur
24100 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a n strings..**.**
24110 20 7b 48 31 33 37 32 35 7d 20 49 66 20 74 68 65 {H13725} If the
24120 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 N parameter to
24130 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
24140 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a name(S,N)] or.**
24150 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
24160 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
24170 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f 66 (S,N)] is out of
24180 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74 68 65 range, then the
24190 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 .** int
241a0 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61 erfaces return a
241b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
241c0 2a 0a 2a 2a 20 7b 48 31 33 37 32 36 7d 20 54 68 *.** {H13726} Th
241d0 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e e strings return
241e0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 ed by [sqlite3_c
241f0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d olumn_name(S,N)]
24200 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
24210 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
24220 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 61 72 _name16(S,N)] ar
24230 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 e valid until th
24240 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 e next.**
24250 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 call to eithe
24260 72 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 74 r routine with t
24270 68 65 20 73 61 6d 65 20 53 20 61 6e 64 20 4e 20 he same S and N
24280 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 parameters.**
24290 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 or until
242a0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
242b0 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e e(S)] is called.
242c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 37 7d 20 .**.** {H13727}
242d0 57 68 65 6e 20 61 20 72 65 73 75 6c 74 20 63 6f When a result co
242e0 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c 45 43 lumn of a [SELEC
242f0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6e T] statement con
24300 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 tains.**
24310 20 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2c 20 an AS clause,
24320 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 61 74 the name of that
24330 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 69 column is the i
24340 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20 20 20 20 dentifier.**
24350 20 20 20 20 20 20 74 6f 20 74 68 65 20 72 69 67 to the rig
24360 68 74 20 6f 66 20 74 68 65 20 41 53 20 6b 65 79 ht of the AS key
24370 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 word..*/.const c
24380 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
24390 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 umn_name(sqlite3
243a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a _stmt*, int N);.
243b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
243c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 te3_column_name1
243d0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
243e0 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 int N);../*.**
243f0 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 CAPI3REF: Source
24400 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 Of Data In A Qu
24410 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37 ery Result {H137
24420 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 40} <S10700>.**.
24430 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
24440 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e s provide a mean
24450 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 s to determine w
24460 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 hat column of wh
24470 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 at.** table in w
24480 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61 20 hich database a
24490 72 65 73 75 6c 74 20 6f 66 20 61 20 5b 53 45 4c result of a [SEL
244a0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 ECT] statement c
244b0 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 omes from..** Th
244c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 e name of the da
244d0 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 tabase or table
244e0 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 or column can be
244f0 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 returned as.**
24500 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f either a UTF-8 o
24510 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e r UTF-16 string.
24520 20 20 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f The _database_
24530 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
24540 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
24550 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c name, the _tabl
24560 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 e_ routines retu
24570 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d rn the table nam
24580 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 e, and.** the or
24590 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 igin_ routines r
245a0 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e eturn the column
245b0 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 name..** The re
245c0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 turned string is
245d0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 valid until the
245e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
245f0 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 ment] is destroy
24600 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c ed.** using [sql
24610 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
24620 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 or until the sa
24630 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 me information i
24640 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 s requested.** a
24650 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 gain in a differ
24660 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a ent encoding..**
24670 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72 65 .** The names re
24680 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f turned are the o
24690 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 riginal un-alias
246a0 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a ed names of the.
246b0 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 ** database, tab
246c0 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a le, and column..
246d0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
246e0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
246f0 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 following calls
24700 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 is a [prepared s
24710 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 tatement]..** Th
24720 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 ese functions re
24730 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e turn information
24740 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 63 about the Nth c
24750 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 olumn returned b
24760 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 y.** the stateme
24770 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 nt, where N is t
24780 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 he second functi
24790 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a on argument..**.
247a0 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f ** If the Nth co
247b0 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 lumn returned by
247c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
247d0 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 s an expression
247e0 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 or.** subquery a
247f0 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 nd is not a colu
24800 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 mn value, then a
24810 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 ll of these func
24820 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 tions return.**
24830 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72 6f 75 NULL. These rou
24840 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 tine might also
24850 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 return NULL if a
24860 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
24870 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 on error.** occu
24880 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 rs. Otherwise,
24890 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 they return the
248a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 name of the atta
248b0 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 ched database, t
248c0 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75 able.** and colu
248d0 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 mn that query re
248e0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 sult column was
248f0 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a extracted from..
24900 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c **.** As with al
24910 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 l other SQLite A
24920 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 PIs, those postf
24930 69 78 65 64 20 77 69 74 68 20 22 31 36 22 20 72 ixed with "16" r
24940 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 eturn.** UTF-16
24950 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c encoded strings,
24960 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 the other funct
24970 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d ions return UTF-
24980 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 8. {END}.**.** T
24990 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e hese APIs are on
249a0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 ly available if
249b0 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 the library was
249c0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
249d0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 e.** [SQLITE_ENA
249e0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 BLE_COLUMN_METAD
249f0 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 ATA] C-preproces
24a00 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e sor symbol defin
24a10 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 ed..**.** {A1375
24a20 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 1}.** If two or
24a30 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c more threads cal
24a40 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 l one or more of
24a50 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
24a60 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 against the same
24a70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 .** prepared sta
24a80 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d tement and colum
24a90 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 n at the same ti
24aa0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 me then the resu
24ab0 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 lts are.** undef
24ac0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 ined..**.** INVA
24ad0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
24ae0 31 33 37 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 13741} The [sqli
24af0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
24b00 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 ase_name(S,N)] i
24b10 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
24b20 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 either.**
24b30 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 the UTF-8 ze
24b40 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 ro-terminated na
24b50 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 me of the databa
24b60 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 se from which th
24b70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 e.** Nt
24b80 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 h result column
24b90 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 of the [prepared
24ba0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 statement] S is
24bb0 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 extracted,.**
24bc0 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 or NULL
24bd0 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d if the Nth colum
24be0 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 n of S is a gene
24bf0 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a ral expression.*
24c00 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 * or if
24c10 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
24c20 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 ate memory to st
24c30 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a ore the name..**
24c40 0a 2a 2a 20 7b 48 31 33 37 34 32 7d 20 54 68 65 .** {H13742} The
24c50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
24c60 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 _database_name16
24c70 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 (S,N)] interface
24c80 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a returns either.
24c90 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
24ca0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 UTF-16 native by
24cb0 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 te order zero-te
24cc0 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 rminated name of
24cd0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
24ce0 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 77 from w
24cf0 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65 73 hich the Nth res
24d00 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 ult column of th
24d10 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
24d20 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20 20 ement] S is.**
24d30 20 20 20 20 20 20 20 20 65 78 74 72 61 63 74 65 extracte
24d40 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 d, or NULL if th
24d50 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 e Nth column of
24d60 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 S is a general e
24d70 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 xpression.**
24d80 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 or if unab
24d90 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d le to allocate m
24da0 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 emory to store t
24db0 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b he name..**.** {
24dc0 48 31 33 37 34 33 7d 20 54 68 65 20 5b 73 71 6c H13743} The [sql
24dd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c ite3_column_tabl
24de0 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 e_name(S,N)] int
24df0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 erface returns e
24e00 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 ither.**
24e10 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f the UTF-8 zero
24e20 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 -terminated name
24e30 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66 72 of the table fr
24e40 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 om which the.**
24e50 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 Nth res
24e60 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 ult column of th
24e70 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
24e80 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 ement] S is extr
24e90 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 acted,.**
24ea0 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 or NULL if th
24eb0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 e Nth column of
24ec0 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 S is a general e
24ed0 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 xpression.**
24ee0 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 or if unab
24ef0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d le to allocate m
24f00 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 emory to store t
24f10 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b he name..**.** {
24f20 48 31 33 37 34 34 7d 20 54 68 65 20 5b 73 71 6c H13744} The [sql
24f30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c ite3_column_tabl
24f40 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 e_name16(S,N)] i
24f50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
24f60 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 either.**
24f70 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e the UTF-16 n
24f80 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
24f90 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
24fa0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 name of the tab
24fb0 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 le.** f
24fc0 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74 rom which the Nt
24fd0 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 h result column
24fe0 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 of the [prepared
24ff0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 statement] S is
25000 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 74 .** ext
25010 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 racted, or NULL
25020 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d if the Nth colum
25030 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 n of S is a gene
25040 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a ral expression.*
25050 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 * or if
25060 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
25070 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 ate memory to st
25080 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a ore the name..**
25090 0a 2a 2a 20 7b 48 31 33 37 34 35 7d 20 54 68 65 .** {H13745} The
250a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
250b0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 53 2c 4e _origin_name(S,N
250c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
250d0 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 urns either.**
250e0 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d the UTF-
250f0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 8 zero-terminate
25100 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 d name of the ta
25110 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 ble column from
25120 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 which the.**
25130 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 Nth result
25140 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b column of the [
25150 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
25160 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 nt] S is extract
25170 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ed,.**
25180 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e or NULL if the N
25190 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 th column of S i
251a0 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 s a general expr
251b0 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 ession.**
251c0 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 or if unable
251d0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f to allocate memo
251e0 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 ry to store the
251f0 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 name..**.** {H13
25200 37 34 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 746} The [sqlite
25210 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 3_column_origin_
25220 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 name16(S,N)] int
25230 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 erface returns e
25240 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 ither.**
25250 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 the UTF-16 nat
25260 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a ive byte order z
25270 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e ero-terminated n
25280 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 ame of the table
25290 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c .** col
252a0 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74 umn from which t
252b0 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f he Nth result co
252c0 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 lumn of the.**
252d0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 [prepare
252e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 d statement] S i
252f0 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 s extracted, or
25300 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 NULL if the Nth
25310 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 column.**
25320 20 20 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e of S is a gen
25330 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 eral expression
25340 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 or if unable to
25350 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a allocate memory.
25360 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 ** to s
25370 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a tore the name..*
25380 2a 0a 2a 2a 20 7b 48 31 33 37 34 38 7d 20 54 68 *.** {H13748} Th
25390 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 20 e return values
253a0 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 from.**
253b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
253c0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c _database_name |
253d0 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 column metadata
253e0 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 interfaces].**
253f0 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61 6c are val
25400 69 64 20 66 6f 72 20 74 68 65 20 6c 69 66 65 74 id for the lifet
25410 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72 65 70 ime of the [prep
25420 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a ared statement].
25430 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 ** or u
25440 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e ntil the encodin
25450 67 20 69 73 20 63 68 61 6e 67 65 64 20 62 79 20 g is changed by
25460 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61 74 61 another metadata
25470 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 .** int
25480 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f 72 20 erface call for
25490 74 68 65 20 73 61 6d 65 20 70 72 65 70 61 72 65 the same prepare
254a0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 d statement and
254b0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 41 53 column..**.** AS
254c0 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a SUMPTIONS:.**.**
254d0 20 7b 41 31 33 37 35 31 7d 20 49 66 20 74 77 6f {A13751} If two
254e0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 or more threads
254f0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 call one or mor
25500 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 e.** [s
25510 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
25520 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f tabase_name | co
25530 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e lumn metadata in
25540 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 terfaces].**
25550 20 20 20 20 20 20 66 6f 72 20 74 68 65 20 73 61 for the sa
25560 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 me [prepared sta
25570 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 tement] and resu
25580 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 lt column.**
25590 20 20 20 20 20 20 61 74 20 74 68 65 20 73 61 6d at the sam
255a0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 e time then the
255b0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
255c0 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 fined..*/.const
255d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
255e0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
255f0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
25600 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
25610 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
25620 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 n_database_name1
25630 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
25640 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 int);.const char
25650 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
25660 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 _table_name(sqli
25670 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
25680 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
25690 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 te3_column_table
256a0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
256b0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
256c0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
256d0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
256e0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
256f0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
25700 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
25710 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 n_origin_name16(
25720 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
25730 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
25740 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 REF: Declared Da
25750 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 tatype Of A Quer
25760 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37 36 30 y Result {H13760
25770 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a } <S10700>.**.**
25780 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
25790 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 eter is a [prepa
257a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
257b0 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 ** If this state
257c0 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 ment is a [SELEC
257d0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 T] statement and
257e0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
257f0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e of the.** return
25800 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 ed result set of
25810 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 that [SELECT] i
25820 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e s a table column
25830 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 (not an.** expr
25840 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 ession or subque
25850 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 ry) then the dec
25860 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 lared type of th
25870 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d e table.** colum
25880 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 n is returned.
25890 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d If the Nth colum
258a0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 n of the result
258b0 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 set is an.** exp
258c0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 ression or subqu
258d0 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c ery, then a NULL
258e0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 pointer is retu
258f0 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 rned..** The ret
25900 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 urned string is
25910 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 always UTF-8 enc
25920 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a oded. {END}.**.*
25930 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 * For example, g
25940 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 iven the databas
25950 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 e schema:.**.**
25960 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 CREATE TABLE t1(
25970 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a c1 VARIANT);.**.
25980 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f ** and the follo
25990 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 wing statement t
259a0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a o be compiled:.*
259b0 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b *.** SELECT c1 +
259c0 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 1, c1 FROM t1;.
259d0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 **.** this routi
259e0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 ne would return
259f0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 the string "VARI
25a00 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 ANT" for the sec
25a10 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f ond result.** co
25a20 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 lumn (i==1), and
25a30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
25a40 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 for the first re
25a50 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d sult column (i==
25a60 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 0)..**.** SQLite
25a70 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 uses dynamic ru
25a80 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 n-time typing.
25a90 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 So just because
25aa0 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 a column.** is d
25ab0 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 eclared to conta
25ac0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 in a particular
25ad0 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 type does not me
25ae0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 an that the.** d
25af0 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 ata stored in th
25b00 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 at column is of
25b10 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 the declared typ
25b20 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a e. SQLite is.**
25b30 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c strongly typed,
25b40 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 but the typing
25b50 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 is dynamic not s
25b60 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 tatic. Type.**
25b70 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 is associated wi
25b80 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 th individual va
25b90 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 lues, not with t
25ba0 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a he containers.**
25bb0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 used to hold th
25bc0 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a ose values..**.*
25bd0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
25be0 0a 2a 2a 20 7b 48 31 33 37 36 31 7d 20 20 41 20 .** {H13761} A
25bf0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 successful call
25c00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to [sqlite3_colu
25c10 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 mn_decltype(S,N)
25c20 5d 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 ] returns a.**
25c30 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 zero-te
25c40 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
25c50 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 tring containing
25c60 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 the declared da
25c70 74 61 74 79 70 65 0a 2a 2a 20 20 20 20 20 20 20 tatype.**
25c80 20 20 20 20 6f 66 20 74 68 65 20 74 61 62 6c 65 of the table
25c90 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 column that app
25ca0 65 61 72 73 20 61 73 20 74 68 65 20 4e 74 68 20 ears as the Nth
25cb0 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 column (numbered
25cc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 72 .** fr
25cd0 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 om 0) of the res
25ce0 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 20 5b ult set to the [
25cf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
25d00 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 nt] S..**.** {H1
25d10 33 37 36 32 7d 20 20 41 20 73 75 63 63 65 73 73 3762} A success
25d20 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
25d30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c ite3_column_decl
25d40 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 type16(S,N)].**
25d50 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e return
25d60 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 s a zero-termina
25d70 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 ted UTF-16 nativ
25d80 65 20 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 e byte order str
25d90 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ing.**
25da0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
25db0 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79 70 declared datatyp
25dc0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 e of the table c
25dd0 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 olumn that appea
25de0 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 rs.**
25df0 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d as the Nth colum
25e00 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d n (numbered from
25e10 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 0) of the resul
25e20 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 t set to the.**
25e30 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 [prepa
25e40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
25e50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 33 7d ..**.** {H13763}
25e60 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 If N is less t
25e70 68 61 6e 20 30 20 6f 72 20 4e 20 69 73 20 67 72 han 0 or N is gr
25e80 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 eater than or eq
25e90 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 ual to.**
25ea0 20 20 20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f the number o
25eb0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 f columns in the
25ec0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
25ed0 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 ment] S,.**
25ee0 20 20 20 20 20 20 6f 72 20 69 66 20 74 68 65 20 or if the
25ef0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 Nth column of S
25f00 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e is an expression
25f10 20 6f 72 20 73 75 62 71 75 65 72 79 20 72 61 74 or subquery rat
25f20 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 her.**
25f30 20 74 68 61 6e 20 61 20 74 61 62 6c 65 20 63 6f than a table co
25f40 6c 75 6d 6e 2c 20 6f 72 20 69 66 20 61 20 6d 65 lumn, or if a me
25f50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
25f60 66 61 69 6c 75 72 65 0a 2a 2a 20 20 20 20 20 20 failure.**
25f70 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72 69 occurs duri
25f80 6e 67 20 65 6e 63 6f 64 69 6e 67 20 63 6f 6e 76 ng encoding conv
25f90 65 72 73 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a ersions, then.**
25fa0 20 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 73 calls
25fb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c to [sqlite3_col
25fc0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e umn_decltype(S,N
25fd0 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 )] or.**
25fe0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 [sqlite3_colu
25ff0 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c mn_decltype16(S,
26000 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e N)] return NULL.
26010 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
26020 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
26030 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f ecltype(sqlite3_
26040 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
26050 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
26060 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 column_decltype1
26070 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
26080 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
26090 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 I3REF: Evaluate
260a0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
260b0 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30 30 30 {H13200} <S1000
260c0 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 0>.**.** After a
260d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
260e0 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 ment] has been p
260f0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 repared using ei
26100 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ther.** [sqlite3
26110 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
26120 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
26130 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e re16_v2()] or on
26140 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a e of the legacy.
26150 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 ** interfaces [s
26160 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
26170 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ] or [sqlite3_pr
26180 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 epare16()], this
26190 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 function.** mus
261a0 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 t be called one
261b0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f or more times to
261c0 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 evaluate the st
261d0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 atement..**.** T
261e0 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 he details of th
261f0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 e behavior of th
26200 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 e sqlite3_step()
26210 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e interface depen
26220 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 d.** on whether
26230 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 the statement wa
26240 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 s prepared using
26250 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 the newer "v2"
26260 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 interface.** [sq
26270 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
26280 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
26290 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
262a0 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 or the older le
262b0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 gacy.** interfac
262c0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 e [sqlite3_prepa
262d0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 re()] and [sqlit
262e0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e e3_prepare16()].
262f0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 The use of the
26300 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 .** new "v2" int
26310 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d erface is recomm
26320 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 ended for new ap
26330 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 plications but t
26340 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 he legacy.** int
26350 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 erface will cont
26360 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f inue to be suppo
26370 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 rted..**.** In t
26380 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
26390 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 ace, the return
263a0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 value will be ei
263b0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 ther [SQLITE_BUS
263c0 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 Y],.** [SQLITE_D
263d0 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f ONE], [SQLITE_RO
263e0 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f W], [SQLITE_ERRO
263f0 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d R], or [SQLITE_M
26400 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 ISUSE]..** With
26410 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
26420 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f ce, any of the o
26430 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 ther [result cod
26440 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e es] or.** [exten
26450 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
26460 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 ] might be retur
26470 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a ned as well..**.
26480 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ** [SQLITE_BUSY]
26490 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
264a0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 database engine
264b0 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 was unable to ac
264c0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 quire the.** dat
264d0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e abase locks it n
264e0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a eeds to do its j
264f0 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 ob. If the stat
26500 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d ement is a [COMM
26510 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 IT].** or occurs
26520 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 outside of an e
26530 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
26540 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 ion, then you ca
26550 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 n retry the.** s
26560 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 tatement. If th
26570 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e e statement is n
26580 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e ot a [COMMIT] an
26590 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 d occurs within
265a0 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 a.** explicit tr
265b0 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 ansaction then y
265c0 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 ou should rollba
265d0 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 ck the transacti
265e0 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e on before.** con
265f0 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b tinuing..**.** [
26600 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 SQLITE_DONE] mea
26610 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 ns that the stat
26620 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 ement has finish
26630 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 ed executing.**
26640 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 successfully. s
26650 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 qlite3_step() sh
26660 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c ould not be call
26670 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 ed again on this
26680 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 virtual.** mach
26690 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 ine without firs
266a0 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 t calling [sqlit
266b0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 e3_reset()] to r
266c0 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c eset the virtual
266d0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b .** machine back
266e0 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 to its initial
266f0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 state..**.** If
26700 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
26710 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 t being executed
26720 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 returns any dat
26730 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f a, then [SQLITE_
26740 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 ROW].** is retur
26750 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 ned each time a
26760 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 new row of data
26770 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f is ready for pro
26780 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a cessing by the.*
26790 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 * caller. The va
267a0 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 lues may be acce
267b0 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b ssed using the [
267c0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
267d0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c nctions]..** sql
267e0 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 ite3_step() is c
267f0 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 alled again to r
26800 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 etrieve the next
26810 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a row of data..**
26820 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f .** [SQLITE_ERRO
26830 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 R] means that a
26840 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 run-time error (
26850 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 such as a constr
26860 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f aint.** violatio
26870 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e n) has occurred.
26880 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 sqlite3_step()
26890 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 should not be c
268a0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a alled again on.*
268b0 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 * the VM. More i
268c0 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 nformation may b
268d0 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 e found by calli
268e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d ng [sqlite3_errm
268f0 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 sg()]..** With t
26900 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
26910 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 ace, a more spec
26920 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 ific error code
26930 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a (for example,.**
26940 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 [SQLITE_INTERRU
26950 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 PT], [SQLITE_SCH
26960 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f EMA], [SQLITE_CO
26970 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 RRUPT], and so f
26980 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 orth).** can be
26990 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c obtained by call
269a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
269b0 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 et()] on the.**
269c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
269d0 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 ent]. In the "v
269e0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 2" interface,.**
269f0 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 the more specif
26a00 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 ic error code is
26a10 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 returned direct
26a20 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 ly by sqlite3_st
26a30 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c ep()..**.** [SQL
26a40 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e ITE_MISUSE] mean
26a50 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 s that the this
26a60 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c routine was call
26a70 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 ed inappropriate
26a80 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 ly..** Perhaps i
26a90 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 t was called on
26aa0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
26ab0 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a ement] that has.
26ac0 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 ** already been
26ad0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
26ae0 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f e | finalized] o
26af0 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 r on one that ha
26b00 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 d.** previously
26b10 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 returned [SQLITE
26b20 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 _ERROR] or [SQLI
26b30 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 TE_DONE]. Or it
26b40 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 could.** be the
26b50 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 case that the s
26b60 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
26b70 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 nection is being
26b80 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a used by two or.
26b90 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 ** more threads
26ba0 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 at the same mome
26bb0 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a nt in time..**.*
26bc0 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 * <b>Goofy Inter
26bd0 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 face Alert:</b>
26be0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e In the legacy in
26bf0 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c terface, the sql
26c00 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 ite3_step().** A
26c10 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e PI always return
26c20 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f s a generic erro
26c30 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f r code, [SQLITE_
26c40 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e ERROR], followin
26c50 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f g any.** error o
26c60 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
26c70 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c E_BUSY] and [SQL
26c80 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f ITE_MISUSE]. Yo
26c90 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b u must call.** [
26ca0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
26cb0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e or [sqlite3_fin
26cc0 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 alize()] in orde
26cd0 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 r to find one of
26ce0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 the.** specific
26cf0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 [error codes] t
26d00 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 hat better descr
26d10 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a ibes the error..
26d20 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 ** We admit that
26d30 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 this is a goofy
26d40 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 design. The pr
26d50 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 oblem has been f
26d60 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 ixed.** with the
26d70 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e "v2" interface.
26d80 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 If you prepare
26d90 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c all of your SQL
26da0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 statements.** u
26db0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c sing either [sql
26dc0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
26dd0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
26de0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 repare16_v2()] i
26df0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 nstead.** of the
26e00 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 legacy [sqlite3
26e10 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 _prepare()] and
26e20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
26e30 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 16()] interfaces
26e40 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f ,.** then the mo
26e50 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 re specific [err
26e60 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 or codes] are re
26e70 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a turned directly.
26e80 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 ** by sqlite3_st
26e90 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f ep(). The use o
26ea0 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 f the "v2" inter
26eb0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e face is recommen
26ec0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ded..**.** INVAR
26ed0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
26ee0 33 32 30 32 7d 20 20 49 66 20 74 68 65 20 5b 70 3202} If the [p
26ef0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
26f00 74 5d 20 53 20 69 73 20 72 65 61 64 79 20 74 6f t] S is ready to
26f10 20 62 65 20 72 75 6e 2c 20 74 68 65 6e 0a 2a 2a be run, then.**
26f20 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 [sqli
26f30 74 65 33 5f 73 74 65 70 28 53 29 5d 20 61 64 76 te3_step(S)] adv
26f40 61 6e 63 65 73 20 74 68 61 74 20 70 72 65 70 61 ances that prepa
26f50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 6e red statement un
26f60 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 til.**
26f70 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20 75 completion or u
26f80 6e 74 69 6c 20 69 74 20 69 73 20 72 65 61 64 79 ntil it is ready
26f90 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 to return anoth
26fa0 65 72 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a 2a er row of the.**
26fb0 20 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c resul
26fc0 74 20 73 65 74 2c 20 6f 72 20 75 6e 74 69 6c 20 t set, or until
26fd0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 an [sqlite3_inte
26fe0 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 rrupt | interrup
26ff0 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 t].**
27000 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 or a run-time er
27010 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a ror occurs..**.*
27020 2a 20 7b 48 31 35 33 30 34 7d 20 20 57 68 65 6e * {H15304} When
27030 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
27040 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63 61 75 te3_step(S)] cau
27050 73 65 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 ses the [prepare
27060 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 d statement].**
27070 20 20 20 20 20 20 20 20 20 20 53 20 74 6f 20 72 S to r
27080 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e un to completion
27090 2c 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 , the function r
270a0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 eturns [SQLITE_D
270b0 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 ONE]..**.** {H15
270c0 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 306} When a cal
270d0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
270e0 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62 65 63 ep(S)] stops bec
270f0 61 75 73 65 20 69 74 20 69 73 20 72 65 61 64 79 ause it is ready
27100 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 to.**
27110 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20 return another
27120 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c row of the resul
27130 74 20 73 65 74 2c 20 69 74 20 72 65 74 75 72 6e t set, it return
27140 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a s [SQLITE_ROW]..
27150 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 38 7d 20 20 **.** {H15308}
27160 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 If a call to [sq
27170 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 65 lite3_step(S)] e
27180 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a 2a 2a 20 ncounters an.**
27190 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
271a0 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 e3_interrupt | i
271b0 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72 nterrupt] or a r
271c0 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 2c 0a 2a un-time error,.*
271d0 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 20 72 * it r
271e0 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 eturns an approp
271f0 72 69 61 74 65 20 65 72 72 6f 72 20 63 6f 64 65 riate error code
27200 20 74 68 61 74 20 69 73 20 6e 6f 74 20 6f 6e 65 that is not one
27210 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 of.**
27220 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b 53 [SQLITE_OK], [S
27230 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f 72 20 5b QLITE_ROW], or [
27240 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a SQLITE_DONE]..**
27250 0a 2a 2a 20 7b 48 31 35 33 31 30 7d 20 20 49 66 .** {H15310} If
27260 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 an [sqlite3_int
27270 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 errupt | interru
27280 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d pt] or a run-tim
27290 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 e error.**
272a0 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72 69 occurs duri
272b0 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 ng a call to [sq
272c0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 0a 2a lite3_step(S)].*
272d0 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 * for
272e0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
272f0 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74 65 64 ement] S created
27300 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 using.**
27310 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74 65 72 legacy inter
27320 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 faces [sqlite3_p
27330 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 repare()] or.**
27340 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
27350 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c e3_prepare16()],
27360 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 then the functi
27370 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 on returns eithe
27380 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b r.** [
27390 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b SQLITE_ERROR], [
273a0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 SQLITE_BUSY], or
273b0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
273c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
273d0 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 _step(sqlite3_st
273e0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
273f0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 I3REF: Number of
27400 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 columns in a re
27410 73 75 6c 74 20 73 65 74 20 7b 48 31 33 37 37 30 sult set {H13770
27420 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a } <S10700>.**.**
27430 20 52 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d Returns the num
27440 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e ber of values in
27450 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 the current row
27460 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
27470 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 et..**.** INVARI
27480 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 ANTS:.**.** {H13
27490 37 37 31 7d 20 20 41 66 74 65 72 20 61 20 63 61 771} After a ca
274a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
274b0 74 65 70 28 53 29 5d 20 74 68 61 74 20 72 65 74 tep(S)] that ret
274c0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 urns [SQLITE_ROW
274d0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 ],.**
274e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 the [sqlite3_dat
274f0 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 a_count(S)] rout
27500 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ine will return
27510 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 0a 2a the same value.*
27520 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20 74 * as t
27530 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 he [sqlite3_colu
27540 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66 75 6e mn_count(S)] fun
27550 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ction..**.** {H1
27560 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b 73 71 3772} After [sq
27570 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 lite3_step(S)] h
27580 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e 79 20 as returned any
27590 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e value other than
275a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 .** [S
275b0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 62 65 QLITE_ROW] or be
275c0 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 fore [sqlite3_st
275d0 65 70 28 53 29 5d 20 68 61 73 20 62 65 65 6e 20 ep(S)] has been
275e0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 0a 2a 2a called on the.**
275f0 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 [prep
27600 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
27610 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 74 69 for the first ti
27620 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61 73 0a me since it was.
27630 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 ** [sq
27640 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 lite3_prepare |
27650 70 72 65 70 61 72 65 64 5d 20 6f 72 20 5b 73 71 prepared] or [sq
27660 6c 69 74 65 33 5f 72 65 73 65 74 20 7c 20 72 65 lite3_reset | re
27670 73 65 74 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 set],.**
27680 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f the [sqlite3_
27690 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 data_count(S)] r
276a0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a outine returns z
276b0 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ero..*/.int sqli
276c0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 te3_data_count(s
276d0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
276e0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
276f0 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 3REF: Fundamenta
27700 6c 20 44 61 74 61 74 79 70 65 73 20 7b 48 31 30 l Datatypes {H10
27710 32 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53 31 265} <S10110><S1
27720 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0120>.** KEYWORD
27730 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a S: SQLITE_TEXT.*
27740 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45 76 *.** {H10266} Ev
27750 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c ery value in SQL
27760 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 ite has one of f
27770 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 ive fundamental
27780 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a datatypes:.**.**
27790 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 <ul>.** <li> 64
277a0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
277b0 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 ger.** <li> 64-b
277c0 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 it IEEE floating
277d0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a point number.**
277e0 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 <li> string.**
277f0 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 <li> BLOB.** <li
27800 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 > NULL.** </ul>
27810 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 {END}.**.** Thes
27820 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
27830 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f codes for each o
27840 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a f those types..*
27850 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 *.** Note that t
27860 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 he SQLITE_TEXT c
27870 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f onstant was also
27880 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 used in SQLite
27890 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 version 2.** for
278a0 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 a completely di
278b0 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e fferent meaning.
278c0 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 Software that
278d0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f links against bo
278e0 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 th.** SQLite ver
278f0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 sion 2 and SQLit
27900 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 e version 3 shou
27910 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 ld use SQLITE3_T
27920 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 EXT, not.** SQLI
27930 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 TE_TEXT..*/.#def
27940 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 ine SQLITE_INTEG
27950 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 ER 1.#define SQ
27960 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a LITE_FLOAT 2.
27970 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 #define SQLITE_B
27980 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e LOB 4.#defin
27990 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 e SQLITE_NULL
279a0 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 5.#ifdef SQLIT
279b0 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 E_TEXT.# undef S
279c0 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 QLITE_TEXT.#else
279d0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
279e0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 _TEXT 3.#end
279f0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 if.#define SQLIT
27a00 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f E3_TEXT 3../
27a10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
27a20 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f esult Values Fro
27a30 6d 20 41 20 51 75 65 72 79 20 7b 48 31 33 38 30 m A Query {H1380
27a40 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 0} <S10700>.** K
27a50 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e EYWORDS: {column
27a60 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e access function
27a70 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 s}.**.** These r
27a80 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 outines form the
27a90 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 75 65 "result set que
27aa0 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ry" interface..*
27ab0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
27ac0 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 nes return infor
27ad0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 mation about a s
27ae0 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 ingle column of
27af0 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 the current.** r
27b00 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 esult row of a q
27b10 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79 20 uery. In every
27b20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 case the first a
27b30 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
27b40 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b nter.** to the [
27b50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
27b60 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e nt] that is bein
27b70 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 g evaluated (the
27b80 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d [sqlite3_stmt*]
27b90 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 .** that was ret
27ba0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 urned from [sqli
27bb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
27bc0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 ] or one of its
27bd0 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 variants).** and
27be0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
27bf0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 ment is the inde
27c00 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 x of the column
27c10 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d for which inform
27c20 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 ation.** should
27c30 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 be returned. Th
27c40 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d e leftmost colum
27c50 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 n of the result
27c60 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 set has the inde
27c70 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 x 0..**.** If th
27c80 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
27c90 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 does not current
27ca0 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 ly point to a va
27cb0 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 lid row, or if t
27cc0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 he.** column ind
27cd0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e ex is out of ran
27ce0 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 ge, the result i
27cf0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 s undefined..**
27d00 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d These routines m
27d10 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 ay only be calle
27d20 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 d when the most
27d30 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a recent call to.*
27d40 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 * [sqlite3_step(
27d50 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 )] has returned
27d60 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 [SQLITE_ROW] and
27d70 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c neither.** [sql
27d80 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f ite3_reset()] no
27d90 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c r [sqlite3_final
27da0 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e ize()] have been
27db0 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 called subseque
27dc0 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 ntly..** If any
27dd0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
27de0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 s are called aft
27df0 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 er [sqlite3_rese
27e00 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 t()] or.** [sqli
27e10 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
27e20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 or after [sqlite
27e30 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 3_step()] has re
27e40 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 turned.** someth
27e50 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b ing other than [
27e60 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 SQLITE_ROW], the
27e70 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
27e80 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 efined..** If [s
27e90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f qlite3_step()] o
27ea0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
27eb0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
27ec0 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 finalize()].** a
27ed0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 re called from a
27ee0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
27ef0 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 d while any of t
27f00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a hese routines.**
27f10 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 are pending, th
27f20 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 en the results a
27f30 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a re undefined..**
27f40 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
27f50 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f column_type() ro
27f60 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
27f70 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 e.** [SQLITE_INT
27f80 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 EGER | datatype
27f90 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e code] for the in
27fa0 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a itial data type.
27fb0 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ** of the result
27fc0 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 column. The re
27fd0 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 turned value is
27fe0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 one of [SQLITE_I
27ff0 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c NTEGER],.** [SQL
28000 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c ITE_FLOAT], [SQL
28010 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 ITE_TEXT], [SQLI
28020 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 TE_BLOB], or [SQ
28030 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 LITE_NULL]. The
28040 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e value.** return
28050 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
28060 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f lumn_type() is o
28070 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 nly meaningful i
28080 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e f no type.** con
28090 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 versions have oc
280a0 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 curred as descri
280b0 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 bed below. Afte
280c0 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 r a type convers
280d0 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 ion,.** the valu
280e0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 e returned by sq
280f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
28100 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 e() is undefined
28110 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 . Future.** ver
28120 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
28130 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 may change the b
28140 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 ehavior of sqlit
28150 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
28160 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 .** following a
28170 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e type conversion.
28180 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 .**.** If the re
28190 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f sult is a BLOB o
281a0 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 r UTF-8 string t
281b0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f hen the sqlite3_
281c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a column_bytes().*
281d0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e * routine return
281e0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
281f0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c bytes in that BL
28200 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a OB or string..**
28210 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 If the result i
28220 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e s a UTF-16 strin
28230 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f g, then sqlite3_
28240 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 column_bytes() c
28250 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 onverts.** the s
28260 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 tring to UTF-8 a
28270 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 nd then returns
28280 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
28290 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 tes..** If the r
282a0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 esult is a numer
282b0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 ic value then sq
282c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
282d0 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 es() uses.** [sq
282e0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
282f0 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 ] to convert tha
28300 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 t value to a UTF
28310 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 -8 string and re
28320 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d turns.** the num
28330 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
28340 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 that string..**
28350 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e The value return
28360 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c ed does not incl
28370 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 ude the zero ter
28380 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 minator at the e
28390 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 nd.** of the str
283a0 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 ing. For clarit
283b0 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 y: the value ret
283c0 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d urned is the num
283d0 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 ber of.** bytes
283e0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e in the string, n
283f0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ot the number of
28400 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a characters..**.
28410 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 ** Strings retur
28420 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
28430 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 olumn_text() and
28440 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
28450 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 text16(),.** eve
28460 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c n empty strings,
28470 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f are always zero
28480 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 terminated. Th
28490 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 e return.** valu
284a0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 e from sqlite3_c
284b0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 olumn_blob() for
284c0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 a zero-length B
284d0 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74 72 LOB is an arbitr
284e0 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 ary.** pointer,
284f0 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 possibly even a
28500 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
28510 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
28520 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
28530 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 routine is simi
28540 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lar to sqlite3_c
28550 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a olumn_bytes().**
28560 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 but leaves the
28570 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 result in UTF-16
28580 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 in native byte
28590 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 order instead of
285a0 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a UTF-8..** The z
285b0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 ero terminator i
285c0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 s not included i
285d0 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a n this count..**
285e0 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72 .** The object r
285f0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
28600 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 te3_column_value
28610 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e ()] is an.** [un
28620 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
28630 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 3_value] object.
28640 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 An unprotected
28650 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
28660 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c bject.** may onl
28670 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b y be used with [
28680 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c sqlite3_bind_val
28690 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ue()] and [sqlit
286a0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
286b0 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 )]..** If the [u
286c0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
286d0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
286e0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
286f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
28700 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 value()] is used
28710 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 in any other wa
28720 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c y, including cal
28730 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 ls.** to routine
28740 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f s like [sqlite3_
28750 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 value_int()], [s
28760 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
28770 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c t()],.** or [sql
28780 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
28790 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 ()], then the be
287a0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
287b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ned..**.** These
287c0 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 routines attemp
287d0 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 t to convert the
287e0 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 value where app
287f0 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a ropriate. For.*
28800 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 * example, if th
28810 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 e internal repre
28820 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f sentation is FLO
28830 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 AT and a text re
28840 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 sult.** is reque
28850 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 sted, [sqlite3_s
28860 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 nprintf()] is us
28870 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f ed internally to
28880 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 perform the.**
28890 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d conversion autom
288a0 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 atically. The f
288b0 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 ollowing table d
288c0 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 etails the conve
288d0 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 rsions.** that a
288e0 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a re applied:.**.*
288f0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a * <blockquote>.*
28900 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d * <table border=
28910 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e "1">.** <tr><th>
28920 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 Internal<br>Typ
28930 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 e <th> Requested
28940 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 <br>Type <th> C
28950 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 onversion.**.**
28960 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
28970 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
28980 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
28990 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 0.** <tr><td> N
289a0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f ULL <td> FLO
289b0 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c AT <td> Resul
289c0 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e t is 0.0.** <tr>
289d0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
289e0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 d> TEXT <td
289f0 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c > Result is NULL
28a00 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e pointer.** <tr>
28a10 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
28a20 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
28a30 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c > Result is NULL
28a40 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e pointer.** <tr>
28a50 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 <td> INTEGER <t
28a60 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
28a70 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 > Convert from i
28a80 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a nteger to float.
28a90 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 ** <tr><td> INTE
28aa0 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 GER <td> TEXT
28ab0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 <td> ASCII r
28ac0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 endering of the
28ad0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c integer.** <tr><
28ae0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 td> INTEGER <td
28af0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
28b00 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 Same as INTEGER
28b10 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 ->TEXT.** <tr><t
28b20 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
28b30 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
28b40 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f Convert from flo
28b50 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a at to integer.**
28b60 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 <tr><td> FLOAT
28b70 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
28b80 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e <td> ASCII ren
28b90 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c dering of the fl
28ba0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 oat.** <tr><td>
28bb0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 FLOAT <td>
28bc0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d BLOB <td> Sam
28bd0 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 e as FLOAT->TEXT
28be0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 .** <tr><td> TE
28bf0 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 XT <td> INTEG
28c00 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 ER <td> Use at
28c10 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e oi().** <tr><td>
28c20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 TEXT <td>
28c30 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 FLOAT <td> Us
28c40 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e e atof().** <tr>
28c50 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
28c60 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
28c70 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c > No change.** <
28c80 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 tr><td> BLOB
28c90 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
28ca0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 <td> Convert to
28cb0 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 TEXT then use at
28cc0 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e oi().** <tr><td>
28cd0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 BLOB <td>
28ce0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f FLOAT <td> Co
28cf0 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 nvert to TEXT th
28d00 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a en use atof().**
28d10 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 <tr><td> BLOB
28d20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
28d30 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 <td> Add a zer
28d40 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 o terminator if
28d50 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c needed.** </tabl
28d60 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f e>.** </blockquo
28d70 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 te>.**.** The ta
28d80 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 ble above makes
28d90 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 reference to sta
28da0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 ndard C library
28db0 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 functions atoi()
28dc0 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 .** and atof().
28dd0 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 SQLite does not
28de0 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 really use thes
28df0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 e functions. It
28e00 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 has its.** own
28e10 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 equivalent inter
28e20 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 nal routines. T
28e30 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 he atoi() and at
28e40 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a of() names are.*
28e50 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 * used in the ta
28e60 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 ble for brevity
28e70 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 and because they
28e80 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f are familiar to
28e90 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 most.** C progr
28ea0 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f ammers..**.** No
28eb0 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 te that when typ
28ec0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 e conversions oc
28ed0 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 cur, pointers re
28ee0 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a turned by prior.
28ef0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ** calls to sqli
28f00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
28f10 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ), sqlite3_colum
28f20 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 n_text(), and/or
28f30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
28f40 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 mn_text16() may
28f50 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a be invalidated..
28f60 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 ** Type conversi
28f70 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 ons and pointer
28f80 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 invalidations mi
28f90 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 ght occur.** in
28fa0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 the following ca
28fb0 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ses:.**.** <ul>.
28fc0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 ** <li> The init
28fd0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 ial content is a
28fe0 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 BLOB and sqlite
28ff0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
29000 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 or.** sqlit
29010 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
29020 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 () is called. A
29030 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 zero-terminator
29040 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e might.** n
29050 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 eed to be added
29060 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f to the string.</
29070 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 li>.** <li> The
29080 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 initial content
29090 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e is UTF-8 text an
290a0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
290b0 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a _bytes16() or.**
290c0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f sqlite3_co
290d0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 lumn_text16() is
290e0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f called. The co
290f0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f ntent must be co
29100 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 nverted.**
29110 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a to UTF-16.</li>.
29120 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 ** <li> The init
29130 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 ial content is U
29140 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 TF-16 text and s
29150 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
29160 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 tes() or.**
29170 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
29180 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 text() is called
29190 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d . The content m
291a0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 ust be converted
291b0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d .** to UTF-
291c0 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 8.</li>.** </ul>
291d0 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f .**.** Conversio
291e0 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 ns between UTF-1
291f0 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 6be and UTF-16le
29200 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 are always done
29210 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f in place and do
29220 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 .** not invalida
29230 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 te a prior point
29240 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f er, though of co
29250 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 urse the content
29260 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a of the buffer.*
29270 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 * that the prior
29280 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 pointer points
29290 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 to will have bee
292a0 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 n modified. Oth
292b0 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 er kinds.** of c
292c0 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f onversion are do
292d0 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e ne in place when
292e0 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c it is possible,
292f0 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 but sometimes t
29300 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 hey.** are not p
29310 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 ossible and in t
29320 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 hose cases prior
29330 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e pointers are in
29340 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a validated..**.**
29350 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 The safest and
29360 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d easiest to remem
29370 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f ber policy is to
29380 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f invoke these ro
29390 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 utines.** in one
293a0 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e of the followin
293b0 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 g ways:.**.** <u
293c0 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 l>.** <li>sqlit
293d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
293e0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c followed by sql
293f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
29400 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 s()</li>.** <li
29410 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
29420 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 blob() followed
29430 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
29440 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a n_bytes()</li>.*
29450 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 * <li>sqlite3_c
29460 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 olumn_text16() f
29470 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 ollowed by sqlit
29480 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
29490 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 6()</li>.** </ul
294a0 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 >.**.** In other
294b0 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 words, you shou
294c0 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f ld call sqlite3_
294d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a column_text(),.*
294e0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
294f0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 _blob(), or sqli
29500 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
29510 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 6() first to for
29520 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a ce the result.**
29530 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 into the desire
29540 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 d format, then i
29550 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f nvoke sqlite3_co
29560 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a lumn_bytes() or.
29570 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
29580 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 n_bytes16() to f
29590 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ind the size of
295a0 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 the result. Do
295b0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a not mix calls.**
295c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
295d0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c mn_text() or sql
295e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
295f0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f () with calls to
29600 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
29610 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e mn_bytes16(), an
29620 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c d do not mix cal
29630 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ls to sqlite3_co
29640 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a lumn_text16().**
29650 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 with calls to s
29660 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
29670 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tes()..**.** The
29680 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e pointers return
29690 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 ed are valid unt
296a0 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 il a type conver
296b0 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a sion occurs as.*
296c0 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 * described abov
296d0 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c e, or until [sql
296e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 ite3_step()] or
296f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
29700 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
29710 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 _finalize()] is
29720 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d called. The mem
29730 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 ory space used t
29740 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a o hold strings.*
29750 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 * and BLOBs is f
29760 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c reed automatical
29770 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f ly. Do <b>not</
29780 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e b> pass the poin
29790 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a ters returned.**
297a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
297b0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 _blob()], [sqlit
297c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
297d0 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 ], etc. into.**
297e0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
297f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d ..**.** If a mem
29800 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 ory allocation e
29810 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 rror occurs duri
29820 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f ng the evaluatio
29830 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 n of any.** of t
29840 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 hese routines, a
29850 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 default value i
29860 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 s returned. The
29870 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a default value.*
29880 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 * is either the
29890 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 integer 0, the f
298a0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 loating point nu
298b0 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e mber 0.0, or a N
298c0 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 ULL.** pointer.
298d0 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c Subsequent call
298e0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 s to [sqlite3_er
298f0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 rcode()] will re
29900 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f turn.** [SQLITE_
29910 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e NOMEM]..**.** IN
29920 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
29930 7b 48 31 33 38 30 33 7d 20 54 68 65 20 5b 73 71 {H13803} The [sq
29940 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
29950 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 b(S,N)] interfac
29960 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a e converts the.*
29970 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 * Nth c
29980 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 olumn in the cur
29990 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 rent row of the
299a0 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a result set for.*
299b0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b * the [
299c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
299d0 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 42 4c 4f nt] S into a BLO
299e0 42 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 B and then retur
299f0 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 ns a.**
29a00 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
29a10 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e converted value.
29a20 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 36 7d 20 .**.** {H13806}
29a30 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c The [sqlite3_col
29a40 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20 umn_bytes(S,N)]
29a50 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
29a60 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
29a70 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 number of byte
29a80 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72 s in the BLOB or
29a90 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 string (exclusi
29aa0 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 ve of the.**
29ab0 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 zero termi
29ac0 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 nator on the str
29ad0 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 ing) that was re
29ae0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a turned by the.**
29af0 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 most r
29b00 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
29b10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
29b20 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 ob(S,N)] or.**
29b30 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
29b40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e _column_text(S,N
29b50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 )]..**.** {H1380
29b60 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 9} The [sqlite3_
29b70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 53 column_bytes16(S
29b80 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 ,N)] interface r
29b90 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 eturns the.**
29ba0 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 number of
29bb0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 bytes in the st
29bc0 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 ring (exclusive
29bd0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 of the.**
29be0 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 zero terminat
29bf0 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 or on the string
29c00 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 ) that was retur
29c10 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 ned by the.**
29c20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 most rece
29c30 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nt call to [sqli
29c40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
29c50 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 6(S,N)]..**.** {
29c60 48 31 33 38 31 32 7d 20 54 68 65 20 5b 73 71 6c H13812} The [sql
29c70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 ite3_column_doub
29c80 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 le(S,N)] interfa
29c90 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a ce converts the.
29ca0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 ** Nth
29cb0 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 column in the cu
29cc0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 rrent row of the
29cd0 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 result set for
29ce0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
29cf0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
29d00 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c ent] S into a fl
29d10 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
29d20 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 ue and.**
29d30 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 returns a cop
29d40 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e y of that value.
29d50 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 35 7d 20 .**.** {H13815}
29d60 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c The [sqlite3_col
29d70 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e umn_int(S,N)] in
29d80 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 terface converts
29d90 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
29da0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 Nth column in t
29db0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f he current row o
29dc0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
29dd0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 for the.**
29de0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 [prepared s
29df0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f tatement] S into
29e00 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 a 64-bit signed
29e10 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 integer and.**
29e20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 returns
29e30 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 the lower 32 bi
29e40 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 ts of that integ
29e50 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 er..**.** {H1381
29e60 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 8} The [sqlite3_
29e70 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e column_int64(S,N
29e80 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e )] interface con
29e90 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 verts the.**
29ea0 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e Nth column
29eb0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 in the current
29ec0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c row of the resul
29ed0 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a t set for the.**
29ee0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 [prepa
29ef0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
29f00 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 into a 64-bit s
29f10 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e igned integer an
29f20 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 d.** re
29f30 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 turns a copy of
29f40 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a that integer..**
29f50 0a 2a 2a 20 7b 48 31 33 38 32 31 7d 20 54 68 65 .** {H13821} The
29f60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
29f70 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69 6e 74 65 _text(S,N)] inte
29f80 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 rface converts t
29f90 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e he.** N
29fa0 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 th column in the
29fb0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 current row of
29fc0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 the result set f
29fd0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 or.** t
29fe0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
29ff0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 tement] S into a
2a000 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
2a010 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 UTF-8.**
2a020 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 string and re
2a030 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
2a040 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a to that string..
2a050 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 34 7d 20 54 **.** {H13824} T
2a060 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 he [sqlite3_colu
2a070 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 20 mn_text16(S,N)]
2a080 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 interface conver
2a090 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ts the.**
2a0a0 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e Nth column in
2a0b0 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 the current row
2a0c0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
2a0d0 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 et for the.**
2a0e0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 [prepared
2a0f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e statement] S in
2a100 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
2a110 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 ated 2-byte.**
2a120 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 aligned
2a130 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 UTF-16 native by
2a140 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67 20 te order string
2a150 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 and returns.**
2a160 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65 a pointe
2a170 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 r to that string
2a180 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 37 7d ..**.** {H13827}
2a190 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f The [sqlite3_co
2a1a0 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 5d 20 lumn_type(S,N)]
2a1b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2a1c0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e s.** on
2a1d0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c e of [SQLITE_NUL
2a1e0 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 L], [SQLITE_INTE
2a1f0 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c GER], [SQLITE_FL
2a200 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 OAT],.**
2a210 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c [SQLITE_TEXT],
2a220 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 or [SQLITE_BLOB
2a230 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 ] as appropriate
2a240 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 for.**
2a250 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
2a260 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 in the current r
2a270 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ow of the result
2a280 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 set for.**
2a290 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 the [prepar
2a2a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e ed statement] S.
2a2b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 33 30 7d 20 .**.** {H13830}
2a2c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c The [sqlite3_col
2a2d0 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20 umn_value(S,N)]
2a2e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2a2f0 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 s a.**
2a300 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 75 pointer to an [u
2a310 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
2a320 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
2a330 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 for the.**
2a340 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 Nth column
2a350 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 in the current r
2a360 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ow of the result
2a370 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 set for.**
2a380 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 the [prepar
2a390 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e ed statement] S.
2a3a0 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a .*/.const void *
2a3b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2a3c0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
2a3d0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e *, int iCol);.in
2a3e0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
2a3f0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 _bytes(sqlite3_s
2a400 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2a410 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
2a420 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 umn_bytes16(sqli
2a430 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
2a440 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c Col);.double sql
2a450 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 ite3_column_doub
2a460 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
2a470 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 , int iCol);.int
2a480 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2a490 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 int(sqlite3_stmt
2a4a0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 *, int iCol);.sq
2a4b0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
2a4c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 te3_column_int64
2a4d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2a4e0 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 int iCol);.const
2a4f0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a unsigned char *
2a500 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2a510 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ext(sqlite3_stmt
2a520 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f *, int iCol);.co
2a530 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
2a540 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2a550 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2a560 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 nt iCol);.int sq
2a570 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
2a580 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
2a590 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 int iCol);.sqli
2a5a0 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 te3_value *sqlit
2a5b0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
2a5c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2a5d0 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a nt iCol);../*.**
2a5e0 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 CAPI3REF: Destr
2a5f0 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 oy A Prepared St
2a600 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b atement Object {
2a610 48 31 33 33 30 30 7d 20 3c 53 37 30 33 30 30 3e H13300} <S70300>
2a620 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S30100>.**.** T
2a630 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c he sqlite3_final
2a640 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 ize() function i
2a650 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 s called to dele
2a660 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 te a [prepared s
2a670 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 tatement]..** If
2a680 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 the statement w
2a690 61 73 20 65 78 65 63 75 74 65 64 20 73 75 63 63 as executed succ
2a6a0 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 essfully or not
2a6b0 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c executed at all,
2a6c0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f then.** SQLITE_
2a6d0 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 OK is returned.
2a6e0 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 If execution of
2a6f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 the statement fa
2a700 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 iled then an.**
2a710 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 [error code] or
2a720 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
2a730 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
2a740 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f d..**.** This ro
2a750 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c utine can be cal
2a760 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 led at any point
2a770 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 during the exec
2a780 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 ution of the.**
2a790 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2a7a0 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69 ent]. If the vi
2a7b0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 rtual machine ha
2a7c0 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 s not.** complet
2a7d0 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 ed execution whe
2a7e0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 n this routine i
2a7f0 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 s called, that i
2a800 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e s like.** encoun
2a810 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 tering an error
2a820 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 or an [sqlite3_i
2a830 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 nterrupt | inter
2a840 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 rupt]..** Incomp
2a850 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 lete updates may
2a860 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 be rolled back
2a870 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 and transactions
2a880 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 canceled,.** de
2a890 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 pending on the c
2a8a0 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e ircumstances, an
2a8b0 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 d the.** [error
2a8c0 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 code] returned w
2a8d0 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 ill be [SQLITE_A
2a8e0 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 BORT]..**.** INV
2a8f0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
2a900 48 31 31 33 30 32 7d 20 54 68 65 20 5b 73 71 6c H11302} The [sql
2a910 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 ite3_finalize(S)
2a920 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73 74 ] interface dest
2a930 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 roys the.**
2a940 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 [prepared s
2a950 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20 tatement] S and
2a960 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 releases all.**
2a970 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 memory
2a980 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75 72 63 and file resourc
2a990 65 73 20 68 65 6c 64 20 62 79 20 74 68 61 74 20 es held by that
2a9a0 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 object..**.** {H
2a9b0 31 31 33 30 34 7d 20 49 66 20 74 68 65 20 6d 6f 11304} If the mo
2a9c0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
2a9d0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
2a9e0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 S)] for the.**
2a9f0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 [prepare
2aa00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 d statement] S r
2aa10 65 74 75 72 6e 65 64 20 61 6e 20 65 72 72 6f 72 eturned an error
2aa20 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 ,.** th
2aa30 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 en [sqlite3_fina
2aa40 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 72 6e 73 lize(S)] returns
2aa50 20 74 68 61 74 20 73 61 6d 65 20 65 72 72 6f 72 that same error
2aa60 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2aa70 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 _finalize(sqlite
2aa80 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
2aa90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2aaa0 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 Reset A Prepare
2aab0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 d Statement Obje
2aac0 63 74 20 7b 48 31 33 33 33 30 7d 20 3c 53 37 30 ct {H13330} <S70
2aad0 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 300>.**.** The s
2aae0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 qlite3_reset() f
2aaf0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 unction is calle
2ab00 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 d to reset a [pr
2ab10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2ab20 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b ].** object back
2ab30 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 to its initial
2ab40 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 state, ready to
2ab50 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a be re-executed..
2ab60 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 ** Any SQL state
2ab70 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 ment variables t
2ab80 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 hat had values b
2ab90 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 ound to them usi
2aba0 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 ng.** the [sqlit
2abb0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 e3_bind_blob | s
2abc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
2abd0 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 API] retain thei
2abe0 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 r values..** Use
2abf0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f [sqlite3_clear_
2ac00 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 bindings()] to r
2ac10 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 eset the binding
2ac20 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 32 s..**.** {H11332
2ac30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 } The [sqlite3_r
2ac40 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 eset(S)] interfa
2ac50 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 ce resets the [p
2ac60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2ac70 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 t] S.**
2ac80 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 back to the beg
2ac90 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 inning of its pr
2aca0 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ogram..**.** {H1
2acb0 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 1334} If the mos
2acc0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
2acd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
2ace0 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 )] for the.**
2acf0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 [prepared
2ad00 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 statement] S re
2ad10 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 turned [SQLITE_R
2ad20 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 OW] or [SQLITE_D
2ad30 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 ONE],.**
2ad40 20 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 or if [sqlite3
2ad50 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 _step(S)] has ne
2ad60 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 ver before been
2ad70 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 called on S,.**
2ad80 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 then [s
2ad90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
2ada0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
2adb0 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 _OK]..**.** {H11
2adc0 33 33 36 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 336} If the most
2add0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 recent call to
2ade0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
2adf0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 ] for the.**
2ae00 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 [prepared
2ae10 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 statement] S ind
2ae20 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c icated an error,
2ae30 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 then.**
2ae40 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 [sqlite3_reset
2ae50 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 (S)] returns an
2ae60 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 appropriate [err
2ae70 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 or code]..**.**
2ae80 7b 48 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71 {H11338} The [sq
2ae90 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 lite3_reset(S)]
2aea0 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e interface does n
2aeb0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 ot change the va
2aec0 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 lues.**
2aed0 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 of any [sqlite3
2aee0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 _bind_blob|bindi
2aef0 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 ngs] on the [pre
2af00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2af10 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 S..*/.int sqlit
2af20 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 e3_reset(sqlite3
2af30 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
2af40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2af50 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 Create Or Redefi
2af60 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 ne SQL Functions
2af70 20 7b 48 31 36 31 30 30 7d 20 3c 53 32 30 32 30 {H16100} <S2020
2af80 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 0>.** KEYWORDS:
2af90 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 {function creati
2afa0 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 on routines}.**
2afb0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 KEYWORDS: {appli
2afc0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
2afd0 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 QL function}.**
2afe0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 KEYWORDS: {appli
2aff0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
2b000 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a QL functions}.**
2b010 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20 66 75 .** These two fu
2b020 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 nctions (collect
2b030 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 ively known as "
2b040 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f function creatio
2b050 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 n routines").**
2b060 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 are used to add
2b070 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 SQL functions or
2b080 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 aggregates or t
2b090 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 o redefine the b
2b0a0 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 ehavior.** of ex
2b0b0 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 isting SQL funct
2b0c0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 ions or aggregat
2b0d0 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 es. The only di
2b0e0 66 66 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e fference between
2b0f0 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 the.** two is t
2b100 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 hat the second p
2b110 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 arameter, the na
2b120 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 me of the (scala
2b130 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a r) function or.*
2b140 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 * aggregate, is
2b150 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 encoded in UTF-8
2b160 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 for sqlite3_cre
2b170 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 ate_function() a
2b180 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 nd UTF-16.** for
2b190 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
2b1a0 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a function16()..**
2b1b0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 .** The first pa
2b1c0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b rameter is the [
2b1d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2b1e0 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 ion] to which th
2b1f0 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f e SQL.** functio
2b200 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 n is to be added
2b210 2e 20 20 49 66 20 61 20 73 69 6e 67 6c 65 20 70 . If a single p
2b220 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 rogram uses more
2b230 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 than one databa
2b240 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
2b250 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 internally, the
2b260 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 n SQL functions
2b270 6d 75 73 74 20 62 65 20 61 64 64 65 64 20 69 6e must be added in
2b280 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a dividually to.**
2b290 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 each database c
2b2a0 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a onnection..**.**
2b2b0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
2b2c0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d meter is the nam
2b2d0 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e e of the SQL fun
2b2e0 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 ction to be crea
2b2f0 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 ted or.** redefi
2b300 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e 67 74 68 ned. The length
2b310 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 of the name is
2b320 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 limited to 255 b
2b330 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 ytes, exclusive
2b340 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 of.** the zero-t
2b350 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 erminator. Note
2b360 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c that the name l
2b370 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 ength limit is i
2b380 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 n bytes, not.**
2b390 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79 characters. Any
2b3a0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 attempt to crea
2b3b0 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 te a function wi
2b3c0 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 th a longer name
2b3d0 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 .** will result
2b3e0 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 in [SQLITE_ERROR
2b3f0 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 ] being returned
2b400 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 ..**.** The thir
2b410 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
2b420 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 he number of arg
2b430 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 uments that the
2b440 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
2b450 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b ** aggregate tak
2b460 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72 61 es. If this para
2b470 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 meter is negativ
2b480 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 e, then the SQL
2b490 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 function or.** a
2b4a0 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b ggregate may tak
2b4b0 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 e any number of
2b4c0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a arguments..**.**
2b4d0 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 The fourth para
2b4e0 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c meter, eTextRep,
2b4f0 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a specifies what.
2b500 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 ** [SQLITE_UTF8
2b510 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d | text encoding]
2b520 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 this SQL functi
2b530 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a on prefers for.*
2b540 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 * its parameters
2b550 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 . Any SQL funct
2b560 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ion implementati
2b570 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c on should be abl
2b580 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 e to work.** wor
2b590 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 k with UTF-8, UT
2b5a0 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 F-16le, or UTF-1
2b5b0 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6be. But some i
2b5c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d mplementations m
2b5d0 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 ay be.** more ef
2b5e0 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 ficient with one
2b5f0 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 encoding than a
2b600 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20 61 nother. It is a
2b610 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 llowed to.** inv
2b620 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 oke sqlite3_crea
2b630 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 te_function() or
2b640 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
2b650 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c function16() mul
2b660 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 tiple.** times w
2b670 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e ith the same fun
2b680 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 ction but with d
2b690 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 ifferent values
2b6a0 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 of eTextRep..**
2b6b0 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d When multiple im
2b6c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
2b6d0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 the same functi
2b6e0 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 on are available
2b6f0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c , SQLite.** will
2b700 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 pick the one th
2b710 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 at involves the
2b720 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 least amount of
2b730 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e data conversion.
2b740 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 .** If there is
2b750 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d only a single im
2b760 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 plementation whi
2b770 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 ch does not care
2b780 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e what text.** en
2b790 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 coding is used,
2b7a0 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 then the fourth
2b7b0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
2b7c0 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e be [SQLITE_ANY].
2b7d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 .**.** The fifth
2b7e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e parameter is an
2b7f0 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 arbitrary point
2b800 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 er. The impleme
2b810 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a ntation of the.*
2b820 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 * function can g
2b830 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 ain access to th
2b840 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 is pointer using
2b850 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 [sqlite3_user_d
2b860 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 ata()]..**.** Th
2b870 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 e seventh, eight
2b880 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 h and ninth para
2b890 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 meters, xFunc, x
2b8a0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c Step and xFinal,
2b8b0 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 are.** pointers
2b8c0 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 to C-language f
2b8d0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d unctions that im
2b8e0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 plement the SQL
2b8f0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 function or.** a
2b900 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c ggregate. A scal
2b910 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ar SQL function
2b920 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c requires an impl
2b930 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
2b940 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 e xFunc.** callb
2b950 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 ack only, NULL p
2b960 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 ointers should b
2b970 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
2b980 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c xStep and xFinal
2b990 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 .** parameters.
2b9a0 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c An aggregate SQL
2b9b0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 function requir
2b9c0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 es an implementa
2b9d0 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a tion of xStep.**
2b9e0 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 and xFinal and
2b9f0 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 NULL should be p
2ba00 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e assed for xFunc.
2ba10 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 To delete an ex
2ba20 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 isting.** SQL fu
2ba30 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 nction or aggreg
2ba40 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 ate, pass NULL f
2ba50 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e or all three fun
2ba60 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e ction callbacks.
2ba70 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 .**.** It is per
2ba80 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 mitted to regist
2ba90 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c er multiple impl
2baa0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 ementations of t
2bab0 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 he same.** funct
2bac0 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 ions with the sa
2bad0 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 me name but with
2bae0 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e either differin
2baf0 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 g numbers of.**
2bb00 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 arguments or dif
2bb10 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 fering preferred
2bb20 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e text encodings.
2bb30 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 SQLite will us
2bb40 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 e.** the impleme
2bb50 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f ntation most clo
2bb60 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 sely matches the
2bb70 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 way in which th
2bb80 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f e.** SQL functio
2bb90 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a n is used..**.**
2bba0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
2bbb0 2a 2a 20 7b 48 31 36 31 30 33 7d 20 54 68 65 20 ** {H16103} The
2bbc0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2bbd0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 69 6e function16()] in
2bbe0 74 65 72 66 61 63 65 20 62 65 68 61 76 65 73 20 terface behaves
2bbf0 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 exactly.**
2bc00 20 20 20 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 like [sqlite
2bc10 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2bc20 6e 28 29 5d 20 69 6e 20 65 76 65 72 79 20 77 61 n()] in every wa
2bc30 79 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 y except that it
2bc40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 .** int
2bc50 65 72 70 72 65 74 73 20 74 68 65 20 7a 46 75 6e erprets the zFun
2bc60 63 74 69 6f 6e 4e 61 6d 65 20 61 72 67 75 6d 65 ctionName argume
2bc70 6e 74 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 nt as zero-termi
2bc80 6e 61 74 65 64 20 55 54 46 2d 31 36 0a 2a 2a 20 nated UTF-16.**
2bc90 20 20 20 20 20 20 20 20 20 6e 61 74 69 76 65 20 native
2bca0 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 byte order inste
2bcb0 61 64 20 6f 66 20 61 73 20 7a 65 72 6f 2d 74 65 ad of as zero-te
2bcc0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a rminated UTF-8..
2bcd0 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 36 7d 20 41 **.** {H16106} A
2bce0 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f successful invo
2bcf0 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 cation of.**
2bd00 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 the [sqlit
2bd10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2bd20 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d on(D,X,N,E,...)]
2bd30 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 interface regis
2bd40 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 ters.**
2bd50 20 6f 72 20 72 65 70 6c 61 63 65 73 20 63 61 6c or replaces cal
2bd60 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 lback functions
2bd70 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 in the [database
2bd80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a connection] D.*
2bd90 2a 20 20 20 20 20 20 20 20 20 20 75 73 65 64 20 * used
2bda0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 to implement the
2bdb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 SQL function na
2bdc0 6d 65 64 20 58 20 77 69 74 68 20 4e 20 70 61 72 med X with N par
2bdd0 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 ameters.**
2bde0 20 20 20 20 61 6e 64 20 68 61 76 69 6e 67 20 61 and having a
2bdf0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 preferred text
2be00 65 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a encoding of E..*
2be10 2a 0a 2a 2a 20 7b 48 31 36 31 30 39 7d 20 41 20 *.** {H16109} A
2be20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 successful call
2be30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 to [sqlite3_crea
2be40 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c te_function(D,X,
2be50 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a N,E,P,F,S,L)].**
2be60 20 20 20 20 20 20 20 20 20 20 72 65 70 6c 61 63 replac
2be70 65 73 20 74 68 65 20 50 2c 20 46 2c 20 53 2c 20 es the P, F, S,
2be80 61 6e 64 20 4c 20 76 61 6c 75 65 73 20 66 72 6f and L values fro
2be90 6d 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c m any prior call
2bea0 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 s with.**
2beb0 20 20 20 74 68 65 20 73 61 6d 65 20 44 2c 20 58 the same D, X
2bec0 2c 20 4e 2c 20 61 6e 64 20 45 20 76 61 6c 75 65 , N, and E value
2bed0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 32 s..**.** {H16112
2bee0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
2bef0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 reate_function(D
2bf00 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 ,X,...)] interfa
2bf10 63 65 20 66 61 69 6c 73 20 77 69 74 68 0a 2a 2a ce fails with.**
2bf20 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74 75 a retu
2bf30 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 rn code of [SQLI
2bf40 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 74 68 65 TE_ERROR] if the
2bf50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 SQL function na
2bf60 6d 65 20 58 20 69 73 0a 2a 2a 20 20 20 20 20 20 me X is.**
2bf70 20 20 20 20 6c 6f 6e 67 65 72 20 74 68 61 6e 20 longer than
2bf80 32 35 35 20 62 79 74 65 73 20 65 78 63 6c 75 73 255 bytes exclus
2bf90 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 20 ive of the zero
2bfa0 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a terminator..**.*
2bfb0 2a 20 7b 48 31 36 31 31 38 7d 20 45 69 74 68 65 * {H16118} Eithe
2bfc0 72 20 46 20 6d 75 73 74 20 62 65 20 4e 55 4c 4c r F must be NULL
2bfd0 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65 and S and L are
2bfe0 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72 20 65 6c 73 non-NULL or els
2bff0 65 20 46 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 e F.**
2c000 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20 is non-NULL and
2c010 53 20 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c 4c S and L are NULL
2c020 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 20 , otherwise.**
2c030 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
2c040 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2c050 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c (D,X,N,E,P,F,S,L
2c060 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 )] returns [SQLI
2c070 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a TE_ERROR]..**.**
2c080 20 7b 48 31 36 31 32 31 7d 20 54 68 65 20 5b 73 {H16121} The [s
2c090 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2c0a0 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69 nction(D,...)] i
2c0b0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 nterface fails w
2c0c0 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 ith an.**
2c0d0 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 error code of
2c0e0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 [SQLITE_BUSY] i
2c0f0 66 20 74 68 65 72 65 20 65 78 69 73 74 20 5b 70 f there exist [p
2c100 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2c110 74 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ts].**
2c120 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
2c130 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
2c140 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a nnection] D..**.
2c150 2a 2a 20 7b 48 31 36 31 32 34 7d 20 54 68 65 20 ** {H16124} The
2c160 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2c170 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e function(D,X,N,.
2c180 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 ..)] interface f
2c190 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 ails with an.**
2c1a0 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63 error c
2c1b0 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 ode of [SQLITE_E
2c1c0 52 52 4f 52 5d 20 69 66 20 70 61 72 61 6d 65 74 RROR] if paramet
2c1d0 65 72 20 4e 20 28 73 70 65 63 69 66 79 69 6e 67 er N (specifying
2c1e0 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 the number.**
2c1f0 20 20 20 20 20 20 20 20 6f 66 20 61 72 67 75 6d of argum
2c200 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20 ents to the SQL
2c210 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 72 function being r
2c220 65 67 69 73 74 65 72 65 64 29 20 69 73 20 6c 65 egistered) is le
2c230 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ss.** t
2c240 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 han -1 or greate
2c250 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a r than 127..**.*
2c260 2a 20 7b 48 31 36 31 32 37 7d 20 57 68 65 6e 20 * {H16127} When
2c270 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 N is non-negativ
2c280 65 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f e, the [sqlite3_
2c290 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
2c2a0 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 D,X,N,...)].**
2c2b0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 interfac
2c2c0 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63 e causes callbac
2c2d0 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 ks to be invoked
2c2e0 20 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e for the SQL fun
2c2f0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ction.**
2c300 20 20 6e 61 6d 65 64 20 58 20 77 68 65 6e 20 74 named X when t
2c310 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 he number of arg
2c320 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51 uments to the SQ
2c330 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a L function is.**
2c340 20 20 20 20 20 20 20 20 20 20 65 78 61 63 74 6c exactl
2c350 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 y N..**.** {H161
2c360 33 30 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d 31 30} When N is -1
2c370 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 , the [sqlite3_c
2c380 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 reate_function(D
2c390 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 ,X,N,...)].**
2c3a0 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 interface
2c3b0 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b causes callback
2c3c0 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 s to be invoked
2c3d0 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 for the SQL func
2c3e0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 tion.**
2c3f0 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 61 6e named X with an
2c400 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 y number of argu
2c410 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ments..**.** {H1
2c420 36 31 33 33 7d 20 57 68 65 6e 20 63 61 6c 6c 73 6133} When calls
2c430 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 to [sqlite3_cre
2c440 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 ate_function(D,X
2c450 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 ,N,...)].**
2c460 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c specify mul
2c470 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 tiple implementa
2c480 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
2c490 65 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 e function X.**
2c4a0 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68 65 and whe
2c4b0 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e 74 61 n one implementa
2c4c0 74 69 6f 6e 20 68 61 73 20 4e 3e 3d 30 20 61 6e tion has N>=0 an
2c4d0 64 20 74 68 65 20 6f 74 68 65 72 20 68 61 73 20 d the other has
2c4e0 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20 20 20 20 20 N=(-1).**
2c4f0 20 20 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 the implement
2c500 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e ation with a non
2c510 2d 7a 65 72 6f 20 4e 20 69 73 20 70 72 65 66 65 -zero N is prefe
2c520 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 rred..**.** {H16
2c530 31 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 136} When calls
2c540 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 to [sqlite3_crea
2c550 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c te_function(D,X,
2c560 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 N,E,...)].**
2c570 20 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75 specify mu
2c580 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 ltiple implement
2c590 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
2c5a0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 me function X wi
2c5b0 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 th.** t
2c5c0 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f he same number o
2c5d0 66 20 61 72 67 75 6d 65 6e 74 73 20 4e 20 62 75 f arguments N bu
2c5e0 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 t with different
2c5f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63 .** enc
2c600 6f 64 69 6e 67 73 20 45 2c 20 74 68 65 6e 20 74 odings E, then t
2c610 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
2c620 6e 20 77 68 65 72 65 20 45 20 6d 61 74 63 68 65 n where E matche
2c630 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
2c640 20 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 database encod
2c650 69 6e 67 20 69 73 20 70 72 65 66 65 72 72 65 64 ing is preferred
2c660 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 39 7d ..**.** {H16139}
2c670 20 46 6f 72 20 61 6e 20 61 67 67 72 65 67 61 74 For an aggregat
2c680 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 e SQL function c
2c690 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 reated using.**
2c6a0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
2c6b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2c6c0 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c n(D,X,N,E,P,0,S,
2c6d0 4c 29 5d 20 74 68 65 20 66 69 6e 61 6c 69 7a 65 L)] the finalize
2c6e0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 r.** fu
2c6f0 6e 63 74 69 6f 6e 20 4c 20 77 69 6c 6c 20 61 6c nction L will al
2c700 77 61 79 73 20 62 65 20 69 6e 76 6f 6b 65 64 20 ways be invoked
2c710 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 69 66 20 exactly once if
2c720 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
2c730 73 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 53 20 step function S
2c740 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 is called one or
2c750 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a more times..**.
2c760 2a 2a 20 7b 48 31 36 31 34 32 7d 20 57 68 65 6e ** {H16142} When
2c770 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 SQLite invokes
2c780 65 69 74 68 65 72 20 74 68 65 20 78 46 75 6e 63 either the xFunc
2c790 20 6f 72 20 78 53 74 65 70 20 66 75 6e 63 74 69 or xStep functi
2c7a0 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 on of.**
2c7b0 20 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e an application
2c7c0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
2c7d0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 ction or aggrega
2c7e0 74 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 20 20 te created.**
2c7f0 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 by [sqlit
2c800 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2c810 6f 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 on()] or [sqlite
2c820 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2c830 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 n16()],.**
2c840 20 20 20 20 74 68 65 6e 20 74 68 65 20 61 72 72 then the arr
2c850 61 79 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 ay of [sqlite3_v
2c860 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 20 70 61 alue] objects pa
2c870 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 20 ssed as the.**
2c880 20 20 20 20 20 20 20 20 74 68 69 72 64 20 70 61 third pa
2c890 72 61 6d 65 74 65 72 20 61 72 65 20 61 6c 77 61 rameter are alwa
2c8a0 79 73 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 ys [protected sq
2c8b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2c8c0 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ects..*/.int sql
2c8d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
2c8e0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 tion(. sqlite3
2c8f0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 *db,. const cha
2c900 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 r *zFunctionName
2c910 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 ,. int nArg,.
2c920 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 int eTextRep,.
2c930 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f void *pApp,. vo
2c940 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 id (*xFunc)(sqli
2c950 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
2c960 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
2c970 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 ),. void (*xSte
2c980 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 p)(sqlite3_conte
2c990 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
2c9a0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
2c9b0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 (*xFinal)(sqlit
2c9c0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a e3_context*).);.
2c9d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 int sqlite3_crea
2c9e0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 te_function16(.
2c9f0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 sqlite3 *db,.
2ca00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e const void *zFun
2ca10 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 ctionName,. int
2ca20 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 nArg,. int eTe
2ca30 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 xtRep,. void *p
2ca40 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 App,. void (*xF
2ca50 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e unc)(sqlite3_con
2ca60 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
2ca70 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
2ca80 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 id (*xStep)(sqli
2ca90 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
2caa0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
2cab0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e ),. void (*xFin
2cac0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 al)(sqlite3_cont
2cad0 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ext*).);../*.**
2cae0 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 CAPI3REF: Text E
2caf0 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30 32 36 37 ncodings {H10267
2cb00 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48 31 36 31 } <S50200> <H161
2cb10 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 00>.**.** These
2cb20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 constant define
2cb30 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 integer codes th
2cb40 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 at represent the
2cb50 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 various.** text
2cb60 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f encodings suppo
2cb70 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a rted by SQLite..
2cb80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
2cb90 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 E_UTF8
2cba0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
2cbb0 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 E_UTF16LE
2cbc0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
2cbd0 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 E_UTF16BE
2cbe0 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 3.#define SQLIT
2cbf0 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 E_UTF16
2cc00 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 4 /* Use nat
2cc10 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a ive byte order *
2cc20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2cc30 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 _ANY
2cc40 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 5 /* sqlite3_
2cc50 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 create_function
2cc60 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 only */.#define
2cc70 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 SQLITE_UTF16_ALI
2cc80 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 GNED 8 /* sq
2cc90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
2cca0 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a lation only */..
2ccb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2ccc0 4f 62 73 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f Obsolete Functio
2ccd0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 ns.**.** These f
2cce0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c unctions are all
2ccf0 20 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20 now obsolete.
2cd00 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e In order to main
2cd10 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 tain.** backward
2cd20 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 s compatibility
2cd30 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c with older code,
2cd40 20 77 65 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 we continue to
2cd50 73 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65 support.** these
2cd60 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77 functions. How
2cd70 65 76 65 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f ever, new develo
2cd80 70 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73 20 73 pment projects s
2cd90 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 hould avoid.** t
2cda0 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 he use of these
2cdb0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 functions. To h
2cdc0 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 elp encourage pe
2cdd0 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a ople to avoid.**
2cde0 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e using these fun
2cdf0 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e ctions, we are n
2ce00 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c ot going to tell
2ce10 20 79 6f 75 20 77 61 6e 74 20 74 68 65 79 20 64 you want they d
2ce20 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 o..*/.int sqlite
2ce30 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 3_aggregate_coun
2ce40 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
2ce50 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 t*);.int sqlite3
2ce60 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 _expired(sqlite3
2ce70 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c _stmt*);.int sql
2ce80 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 ite3_transfer_bi
2ce90 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 ndings(sqlite3_s
2cea0 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 tmt*, sqlite3_st
2ceb0 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 mt*);.int sqlite
2cec0 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 3_global_recover
2ced0 28 76 6f 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c (void);.void sql
2cee0 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 ite3_thread_clea
2cef0 6e 75 70 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 nup(void);.int s
2cf00 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c qlite3_memory_al
2cf10 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 arm(void(*)(void
2cf20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c *,sqlite3_int64,
2cf30 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 int),void*,sqlit
2cf40 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a e3_int64);../*.*
2cf50 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 * CAPI3REF: Obta
2cf60 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 ining SQL Functi
2cf70 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c on Parameter Val
2cf80 75 65 73 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 ues {H15100} <S2
2cf90 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0200>.**.** The
2cfa0 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 C-language imple
2cfb0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c mentation of SQL
2cfc0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 functions and a
2cfd0 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a ggregates uses.*
2cfe0 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e * this set of in
2cff0 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 terface routines
2d000 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 to access the p
2d010 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 arameter values
2d020 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 on.** the functi
2d030 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e on or aggregate.
2d040 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 .**.** The xFunc
2d050 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e (for scalar fun
2d060 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 ctions) or xStep
2d070 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 (for aggregates
2d080 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 ) parameters.**
2d090 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 to [sqlite3_crea
2d0a0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 te_function()] a
2d0b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
2d0c0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
2d0d0 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 .** define callb
2d0e0 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d acks that implem
2d0f0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 ent the SQL func
2d100 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 tions and aggreg
2d110 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 ates..** The 4th
2d120 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
2d130 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 ese callbacks is
2d140 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 an array of poi
2d150 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f nters to.** [pro
2d160 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2d170 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 alue] objects.
2d180 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 There is one [sq
2d190 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2d1a0 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 ect for.** each
2d1b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
2d1c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 SQL function.
2d1d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
2d1e0 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 re used to.** ex
2d1f0 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f tract values fro
2d200 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 m the [sqlite3_v
2d210 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a alue] objects..*
2d220 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
2d230 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 nes work only wi
2d240 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 th [protected sq
2d250 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2d260 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 ects..** Any att
2d270 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 empt to use thes
2d280 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e e routines on an
2d290 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
2d2a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 lite3_value].**
2d2b0 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 object results i
2d2c0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 n undefined beha
2d2d0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 vior..**.** Thes
2d2e0 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 e routines work
2d2f0 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f just like the co
2d300 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c rresponding [col
2d310 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 umn access funct
2d320 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 ions].** except
2d330 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 that these rout
2d340 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 ines take a sing
2d350 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 le [protected sq
2d360 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2d370 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 ect.** pointer i
2d380 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c nstead of a [sql
2d390 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e ite3_stmt*] poin
2d3a0 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 ter and an integ
2d3b0 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 er column number
2d3c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
2d3d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
2d3e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 () interface ext
2d3f0 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 racts a UTF-16 s
2d400 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 tring.** in the
2d410 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 native byte-orde
2d420 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 r of the host ma
2d430 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 chine. The.** s
2d440 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
2d450 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 t16be() and sqli
2d460 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
2d470 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a le() interfaces.
2d480 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 ** extract UTF-1
2d490 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 6 strings as big
2d4a0 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 -endian and litt
2d4b0 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 le-endian respec
2d4c0 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 tively..**.** Th
2d4d0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f e sqlite3_value_
2d4e0 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 numeric_type() i
2d4f0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 nterface attempt
2d500 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 s to apply.** nu
2d510 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 meric affinity t
2d520 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 o the value. Th
2d530 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e is means that an
2d540 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d attempt is.** m
2d550 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 ade to convert t
2d560 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 he value to an i
2d570 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 nteger or floati
2d580 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a ng point. If.**
2d590 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 such a conversi
2d5a0 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 on is possible w
2d5b0 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 ithout loss of i
2d5c0 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f nformation (in o
2d5d0 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 ther.** words, i
2d5e0 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 f the value is a
2d5f0 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f string that loo
2d600 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 ks like a number
2d610 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f ).** then the co
2d620 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 nversion is perf
2d630 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 ormed. Otherwis
2d640 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 e no conversion
2d650 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b occurs..** The [
2d660 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c SQLITE_INTEGER |
2d670 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 datatype] after
2d680 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 conversion is r
2d690 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 eturned..**.** P
2d6a0 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 lease pay partic
2d6b0 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 ular attention t
2d6c0 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 o the fact that
2d6d0 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 the pointer retu
2d6e0 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 rned.** from [sq
2d6f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 lite3_value_blob
2d700 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 ()], [sqlite3_va
2d710 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a lue_text()], or.
2d720 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ** [sqlite3_valu
2d730 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 e_text16()] can
2d740 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 be invalidated b
2d750 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 y a subsequent c
2d760 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 all to.** [sqlit
2d770 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 e3_value_bytes()
2d780 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
2d790 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 e_bytes16()], [s
2d7a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
2d7b0 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c t()],.** or [sql
2d7c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
2d7d0 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 6()]..**.** Thes
2d7e0 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 e routines must
2d7f0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 be called from t
2d800 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 he same thread a
2d810 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e s.** the SQL fun
2d820 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c ction that suppl
2d830 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ied the [sqlite3
2d840 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 _value*] paramet
2d850 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ers..**.** INVAR
2d860 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
2d870 35 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 5103} The [sqlit
2d880 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 e3_value_blob(V)
2d890 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 ] interface conv
2d8a0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 erts the.**
2d8b0 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 [protected
2d8c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
2d8d0 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 42 bject V into a B
2d8e0 4c 4f 42 20 61 6e 64 20 74 68 65 6e 0a 2a 2a 20 LOB and then.**
2d8f0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 returns
2d900 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
2d910 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 e converted valu
2d920 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 36 e..**.** {H15106
2d930 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 } The [sqlite3_v
2d940 61 6c 75 65 5f 62 79 74 65 73 28 56 29 5d 20 69 alue_bytes(V)] i
2d950 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
2d960 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
2d970 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2d980 20 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 in the BLOB or
2d990 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 string (exclusiv
2d9a0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 e of the.**
2d9b0 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e zero termin
2d9c0 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 ator on the stri
2d9d0 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 ng) that was ret
2d9e0 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 urned by the.**
2d9f0 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 most re
2da00 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 cent call to [sq
2da10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 lite3_value_blob
2da20 28 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 (V)] or.**
2da30 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c [sqlite3_val
2da40 75 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a ue_text(V)]..**.
2da50 2a 2a 20 7b 48 31 35 31 30 39 7d 20 54 68 65 20 ** {H15109} The
2da60 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
2da70 79 74 65 73 31 36 28 56 29 5d 20 69 6e 74 65 72 ytes16(V)] inter
2da80 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
2da90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d .** num
2daa0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
2dab0 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c the string (excl
2dac0 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 usive of the.**
2dad0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 zero te
2dae0 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 rminator on the
2daf0 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 string) that was
2db00 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
2db10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 .** mos
2db20 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
2db30 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2db40 74 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 text16(V)],.**
2db50 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
2db60 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 _value_text16be(
2db70 56 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 V)], or [sqlite3
2db80 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 _value_text16le(
2db90 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 V)]..**.** {H151
2dba0 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 12} The [sqlite3
2dbb0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 _value_double(V)
2dbc0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 ] interface conv
2dbd0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 erts the.**
2dbe0 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 [protected
2dbf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
2dc00 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 66 bject V into a f
2dc10 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 loating point va
2dc20 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 lue and.**
2dc30 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f returns a co
2dc40 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 py of that value
2dc50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 35 7d ..**.** {H15115}
2dc60 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 The [sqlite3_va
2dc70 6c 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 lue_int(V)] inte
2dc80 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 rface converts t
2dc90 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
2dca0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2dcb0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
2dcc0 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 V into a 64-bit
2dcd0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 signed integer a
2dce0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 nd.** r
2dcf0 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 eturns the lower
2dd00 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 32 bits of that
2dd10 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 integer..**.**
2dd20 7b 48 31 35 31 31 38 7d 20 54 68 65 20 5b 73 71 {H15118} The [sq
2dd30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 lite3_value_int6
2dd40 34 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 4(V)] interface
2dd50 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 converts the.**
2dd60 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 [protec
2dd70 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2dd80 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f e] object V into
2dd90 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 a 64-bit signed
2dda0 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 integer and.**
2ddb0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 returns
2ddc0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 a copy of that
2ddd0 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b integer..**.** {
2dde0 48 31 35 31 32 31 7d 20 54 68 65 20 5b 73 71 6c H15121} The [sql
2ddf0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 ite3_value_text(
2de00 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f V)] interface co
2de10 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 nverts the.**
2de20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 [protecte
2de30 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
2de40 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 object V into a
2de50 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
2de60 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 UTF-8.**
2de70 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 string and re
2de80 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
2de90 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a to that string..
2dea0 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 34 7d 20 54 **.** {H15124} T
2deb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
2dec0 65 5f 74 65 78 74 31 36 28 56 29 5d 20 69 6e 74 e_text16(V)] int
2ded0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 erface converts
2dee0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
2def0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
2df00 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
2df10 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 V into a zero-t
2df20 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 erminated 2-byte
2df30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 .** ali
2df40 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 gned UTF-16 nati
2df50 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a ve byte order.**
2df60 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 string
2df70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 and returns a p
2df80 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 ointer to that s
2df90 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 tring..**.** {H1
2dfa0 35 31 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 5127} The [sqlit
2dfb0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 e3_value_text16b
2dfc0 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 e(V)] interface
2dfd0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 converts the.**
2dfe0 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 [protec
2dff0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2e000 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f e] object V into
2e010 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
2e020 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 ed 2-byte.**
2e030 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 aligned UT
2e040 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a F-16 big-endian.
2e050 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 ** stri
2e060 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 ng and returns a
2e070 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 pointer to that
2e080 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b string..**.** {
2e090 48 31 35 31 33 30 7d 20 54 68 65 20 5b 73 71 6c H15130} The [sql
2e0a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
2e0b0 36 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 6le(V)] interfac
2e0c0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a e converts the.*
2e0d0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 * [prot
2e0e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2e0f0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e lue] object V in
2e100 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
2e110 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 ated 2-byte.**
2e120 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 aligned
2e130 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e UTF-16 little-en
2e140 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 dian.**
2e150 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 string and retu
2e160 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
2e170 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a that string..**
2e180 0a 2a 2a 20 7b 48 31 35 31 33 33 7d 20 54 68 65 .** {H15133} The
2e190 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2e1a0 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 type(V)] interfa
2e1b0 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 ce returns.**
2e1c0 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 one of [S
2e1d0 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 QLITE_NULL], [SQ
2e1e0 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b LITE_INTEGER], [
2e1f0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a SQLITE_FLOAT],.*
2e200 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 * [SQLI
2e210 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 TE_TEXT], or [SQ
2e220 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 LITE_BLOB] as ap
2e230 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a propriate for.**
2e240 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 the [s
2e250 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
2e260 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ject V..**.** {H
2e270 31 35 31 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 15136} The [sqli
2e280 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 te3_value_numeri
2e290 63 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 c_type(V)] inter
2e2a0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a face converts.**
2e2b0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 the [p
2e2c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2e2d0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 _value] object V
2e2e0 20 69 6e 74 6f 20 65 69 74 68 65 72 20 61 6e 20 into either an
2e2f0 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20 integer or.**
2e300 20 20 20 20 20 20 20 61 20 66 6c 6f 61 74 69 6e a floatin
2e310 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 69 66 g point value if
2e320 20 69 74 20 63 61 6e 20 64 6f 20 73 6f 20 77 69 it can do so wi
2e330 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a thout loss of.**
2e340 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d inform
2e350 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72 ation, and retur
2e360 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 ns one of [SQLIT
2e370 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20 E_NULL],.**
2e380 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 [SQLITE_INT
2e390 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 EGER], [SQLITE_F
2e3a0 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 LOAT], [SQLITE_T
2e3b0 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 EXT], or.**
2e3c0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f [SQLITE_BLO
2e3d0 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 B] as appropriat
2e3e0 65 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 e for the.**
2e3f0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 [protected
2e400 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
2e410 6f 62 6a 65 63 74 20 56 20 61 66 74 65 72 20 74 object V after t
2e420 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74 he conversion at
2e430 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 tempt..*/.const
2e440 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 void *sqlite3_va
2e450 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 lue_blob(sqlite3
2e460 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
2e470 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
2e480 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a s(sqlite3_value*
2e490 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 );.int sqlite3_v
2e4a0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c alue_bytes16(sql
2e4b0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f ite3_value*);.do
2e4c0 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c uble sqlite3_val
2e4d0 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 ue_double(sqlite
2e4e0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 3_value*);.int s
2e4f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 qlite3_value_int
2e500 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
2e510 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 ;.sqlite3_int64
2e520 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e sqlite3_value_in
2e530 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 t64(sqlite3_valu
2e540 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 e*);.const unsig
2e550 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 ned char *sqlite
2e560 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 3_value_text(sql
2e570 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f ite3_value*);.co
2e580 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
2e590 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 3_value_text16(s
2e5a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
2e5b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
2e5c0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
2e5d0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 le(sqlite3_value
2e5e0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a *);.const void *
2e5f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
2e600 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 xt16be(sqlite3_v
2e610 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 alue*);.int sqli
2e620 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 te3_value_type(s
2e630 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
2e640 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
2e650 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 e_numeric_type(s
2e660 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
2e670 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2e680 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 Obtain Aggregat
2e690 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 e Function Conte
2e6a0 78 74 20 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 xt {H16210} <S20
2e6b0 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 200>.**.** The i
2e6c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
2e6d0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 aggregate SQL f
2e6e0 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 unctions use thi
2e6f0 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c s routine to all
2e700 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 ocate.** a struc
2e710 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 ture for storing
2e720 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a their state..**
2e730 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 .** The first ti
2e740 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 me the sqlite3_a
2e750 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
2e760 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 () routine is ca
2e770 6c 6c 65 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 lled for a.** pa
2e780 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 rticular aggrega
2e790 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 te, SQLite alloc
2e7a0 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d ates nBytes of m
2e7b0 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 emory, zeroes ou
2e7c0 74 20 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 t that.** memory
2e7d0 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 , and returns a
2e7e0 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f pointer to it. O
2e7f0 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 n second and sub
2e800 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
2e810 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 .** sqlite3_aggr
2e820 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 egate_context()
2e830 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 for the same agg
2e840 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 regate function
2e850 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 index,.** the sa
2e860 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 me buffer is ret
2e870 75 72 6e 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 urned. The imple
2e880 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 mentation of the
2e890 20 61 67 67 72 65 67 61 74 65 20 63 61 6e 20 75 aggregate can u
2e8a0 73 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e se.** the return
2e8b0 65 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 63 ed buffer to acc
2e8c0 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a umulate data..**
2e8d0 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75 74 6f 6d .** SQLite autom
2e8e0 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 atically frees t
2e8f0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 he allocated buf
2e900 66 65 72 20 77 68 65 6e 20 74 68 65 20 61 67 67 fer when the agg
2e910 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 regate.** query
2e920 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a concludes..**.**
2e930 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
2e940 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 eter should be a
2e950 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 copy of the.**
2e960 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 [sqlite3_context
2e970 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 | SQL function
2e980 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 context] that is
2e990 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
2e9a0 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 eter.** to the c
2e9b0 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 allback routine
2e9c0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 that implements
2e9d0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 the aggregate fu
2e9e0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 nction..**.** Th
2e9f0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 is routine must
2ea00 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 be called from t
2ea10 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 he same thread i
2ea20 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 n which.** the a
2ea30 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e ggregate SQL fun
2ea40 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
2ea50 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
2ea60 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 TS:.**.** {H1621
2ea70 31 7d 20 54 68 65 20 66 69 72 73 74 20 69 6e 76 1} The first inv
2ea80 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 ocation of [sqli
2ea90 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
2eaa0 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a ntext(C,N)] for.
2eab0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 61 ** a pa
2eac0 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 rticular instanc
2ead0 65 20 6f 66 20 61 6e 20 61 67 67 72 65 67 61 74 e of an aggregat
2eae0 65 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20 e function (for
2eaf0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 a particular.**
2eb00 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74 context
2eb10 20 43 29 20 63 61 75 73 65 73 20 53 51 4c 69 74 C) causes SQLit
2eb20 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 4e 20 e to allocate N
2eb30 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c bytes of memory,
2eb40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 .** zer
2eb50 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 o that memory, a
2eb60 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e nd return a poin
2eb70 74 65 72 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 ter to the alloc
2eb80 61 74 65 64 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a ated memory..**.
2eb90 2a 2a 20 7b 48 31 36 32 31 33 7d 20 49 66 20 61 ** {H16213} If a
2eba0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
2ebb0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 on error occurs
2ebc0 64 75 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 during.**
2ebd0 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 [sqlite3_aggr
2ebe0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c egate_context(C,
2ebf0 4e 29 5d 20 74 68 65 6e 20 74 68 65 20 66 75 6e N)] then the fun
2ec00 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e ction returns 0.
2ec10 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 35 7d 20 .**.** {H16215}
2ec20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 Second and subse
2ec30 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e quent invocation
2ec40 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 s of.**
2ec50 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 [sqlite3_aggreg
2ec60 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 ate_context(C,N)
2ec70 5d 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 63 ] for the same c
2ec80 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 43 ontext pointer C
2ec90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 67 6e .** ign
2eca0 6f 72 65 20 74 68 65 20 4e 20 70 61 72 61 6d 65 ore the N parame
2ecb0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 20 61 ter and return a
2ecc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
2ecd0 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 same.**
2ece0 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 block of memory
2ecf0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
2ed00 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f first invocatio
2ed10 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 37 n..**.** {H16217
2ed20 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c } The memory all
2ed30 6f 63 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 ocated by [sqlit
2ed40 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
2ed50 74 65 78 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a text(C,N)] is.**
2ed60 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61 automa
2ed70 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e tically freed on
2ed80 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 the next call t
2ed90 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 o [sqlite3_reset
2eda0 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ()].**
2edb0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 or [sqlite3_fina
2edc0 6c 69 7a 65 28 29 5d 20 66 6f 72 20 74 68 65 20 lize()] for the
2edd0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2ede0 65 6e 74 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a ent] containing.
2edf0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
2ee00 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 aggregate functi
2ee10 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 on associated wi
2ee20 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f th context C..*/
2ee30 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 .void *sqlite3_a
2ee40 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
2ee50 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
2ee60 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a *, int nBytes);.
2ee70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2ee80 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 User Data For F
2ee90 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 unctions {H16240
2eea0 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a } <S20200>.**.**
2eeb0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 The sqlite3_use
2eec0 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 r_data() interfa
2eed0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 ce returns a cop
2eee0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e y of.** the poin
2eef0 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 ter that was the
2ef00 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d pUserData param
2ef10 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 eter (the 5th pa
2ef20 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 rameter).** of t
2ef30 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
2ef40 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a te_function()].*
2ef50 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 * and [sqlite3_c
2ef60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
2ef70 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 ()] routines tha
2ef80 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 t originally.**
2ef90 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 registered the a
2efa0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
2efb0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e ed function. {EN
2efc0 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f D}.**.** This ro
2efd0 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 utine must be ca
2efe0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 lled from the sa
2eff0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 me thread in whi
2f000 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 ch.** the applic
2f010 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
2f020 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
2f030 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 g..**.** INVARIA
2f040 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 NTS:.**.** {H162
2f050 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 43} The [sqlite3
2f060 5f 75 73 65 72 5f 64 61 74 61 28 43 29 5d 20 69 _user_data(C)] i
2f070 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
2f080 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a a copy of the.*
2f090 2a 20 20 20 20 20 20 20 20 20 20 50 20 70 6f 69 * P poi
2f0a0 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 nter from the [s
2f0b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2f0c0 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 nction(D,X,N,E,P
2f0d0 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 ,F,S,L)].**
2f0e0 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 or [sqlite3
2f0f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2f100 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 16(D,X,N,E,P,F,S
2f110 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a ,L)] call that.*
2f120 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 * regis
2f130 74 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 tered the SQL fu
2f140 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 nction associate
2f150 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f d with [sqlite3_
2f160 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 context] C..*/.v
2f170 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 oid *sqlite3_use
2f180 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 r_data(sqlite3_c
2f190 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a ontext*);../*.**
2f1a0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 CAPI3REF: Datab
2f1b0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 ase Connection F
2f1c0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 or Functions {H1
2f1d0 36 32 35 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 6250} <S60600><S
2f1e0 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20200>.**.** The
2f1f0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
2f200 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 _db_handle() int
2f210 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
2f220 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
2f230 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b pointer to the [
2f240 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2f250 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 ion] (the 1st pa
2f260 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 rameter).** of t
2f270 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
2f280 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a te_function()].*
2f290 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 * and [sqlite3_c
2f2a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
2f2b0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 ()] routines tha
2f2c0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 t originally.**
2f2d0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 registered the a
2f2e0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
2f2f0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a ed function..**.
2f300 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
2f310 2a 0a 2a 2a 20 7b 48 31 36 32 35 33 7d 20 54 68 *.** {H16253} Th
2f320 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 e [sqlite3_conte
2f330 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d xt_db_handle(C)]
2f340 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2f350 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 ns a copy of the
2f360 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 70 .** D p
2f370 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20 ointer from the
2f380 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2f390 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 function(D,X,N,E
2f3a0 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 ,P,F,S,L)].**
2f3b0 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 or [sqlit
2f3c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2f3d0 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 on16(D,X,N,E,P,F
2f3e0 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 ,S,L)] call that
2f3f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 .** reg
2f400 69 73 74 65 72 65 64 20 74 68 65 20 53 51 4c 20 istered the SQL
2f410 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 function associa
2f420 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 ted with [sqlite
2f430 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 3_context] C..*/
2f440 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 .sqlite3 *sqlite
2f450 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 3_context_db_han
2f460 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 dle(sqlite3_cont
2f470 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ext*);../*.** CA
2f480 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e PI3REF: Function
2f490 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 20 Auxiliary Data
2f4a0 7b 48 31 36 32 37 30 7d 20 3c 53 32 30 32 30 30 {H16270} <S20200
2f4b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c >.**.** The foll
2f4c0 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 owing two functi
2f4d0 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 ons may be used
2f4e0 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 by scalar SQL fu
2f4f0 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 nctions to.** as
2f500 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 sociate metadata
2f510 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 with argument v
2f520 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 alues. If the sa
2f530 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 me value is pass
2f540 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c ed to.** multipl
2f550 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 e invocations of
2f560 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 the same SQL fu
2f570 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 nction during qu
2f580 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 ery execution, u
2f590 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 nder.** some cir
2f5a0 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 cumstances the a
2f5b0 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 ssociated metada
2f5c0 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 ta may be preser
2f5d0 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a ved. This may.**
2f5e0 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 be used, for ex
2f5f0 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 ample, to add a
2f600 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 regular-expressi
2f610 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c on matching scal
2f620 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 ar.** function.
2f630 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 The compiled ver
2f640 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 sion of the regu
2f650 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 lar expression i
2f660 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d s stored as.** m
2f670 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 etadata associat
2f680 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 ed with the SQL
2f690 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 value passed as
2f6a0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 the regular expr
2f6b0 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 ession.** patter
2f6c0 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 n. The compiled
2f6d0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 regular express
2f6e0 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 ion can be reuse
2f6f0 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a d on multiple.**
2f700 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 invocations of
2f710 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
2f720 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 n so that the or
2f730 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 iginal pattern s
2f740 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f tring.** does no
2f750 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 t need to be rec
2f760 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 ompiled on each
2f770 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a invocation..**.*
2f780 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 * The sqlite3_ge
2f790 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 t_auxdata() inte
2f7a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
2f7b0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d pointer to the m
2f7c0 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 etadata.** assoc
2f7d0 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c iated by the sql
2f7e0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
2f7f0 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 () function with
2f800 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e the Nth argumen
2f810 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 t.** value to th
2f820 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
2f830 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 fined function.
2f840 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 If no metadata h
2f850 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 as been ever.**
2f860 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 been set for the
2f870 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 Nth argument of
2f880 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f the function, o
2f890 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 r if the corresp
2f8a0 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 onding.** functi
2f8b0 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 on parameter has
2f8c0 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 changed since t
2f8d0 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 he meta-data was
2f8e0 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 set,.** then sq
2f8f0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
2f900 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 a() returns a NU
2f910 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
2f920 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 * The sqlite3_se
2f930 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 t_auxdata() inte
2f940 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20 rface saves the
2f950 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e metadata.** poin
2f960 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 ted to by its 3r
2f970 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 d parameter as t
2f980 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 he metadata for
2f990 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 the N-th.** argu
2f9a0 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c ment of the appl
2f9b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
2f9c0 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 function. Subse
2f9d0 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 quent.** calls t
2f9e0 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 o sqlite3_get_au
2f9f0 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 xdata() might re
2fa00 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 turn this data,
2fa10 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 if it has.** not
2fa20 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e been destroyed.
2fa30 0a 2a 2a 20 49 66 20 69 74 20 69 73 20 6e 6f 74 .** If it is not
2fa40 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 NULL, SQLite wi
2fa50 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 ll invoke the de
2fa60 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 structor.** func
2fa70 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 tion given by th
2fa80 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
2fa90 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 to sqlite3_set_a
2faa0 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 uxdata() on.** t
2fab0 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e he metadata when
2fac0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
2fad0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 ng function para
2fae0 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a meter changes.**
2faf0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c or when the SQL
2fb00 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c statement compl
2fb10 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 etes, whichever
2fb20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a comes first..**.
2fb30 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 ** SQLite is fre
2fb40 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 e to call the de
2fb50 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f structor and dro
2fb60 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e p metadata on an
2fb70 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f y.** parameter o
2fb80 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 f any function a
2fb90 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 t any time. The
2fba0 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 only guarantee
2fbb0 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 is that.** the d
2fbc0 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 estructor will b
2fbd0 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 e called before
2fbe0 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 the metadata is
2fbf0 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 dropped..**.** I
2fc00 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 n practice, meta
2fc10 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 data is preserve
2fc20 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 d between functi
2fc30 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 on calls for.**
2fc40 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 expressions that
2fc50 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 are constant at
2fc60 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 compile time. T
2fc70 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 his includes lit
2fc80 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 eral.** values a
2fc90 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73 nd SQL variables
2fca0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
2fcb0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 utines must be c
2fcc0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 alled from the s
2fcd0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 ame thread in wh
2fce0 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 ich.** the SQL f
2fcf0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
2fd00 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 ng..**.** INVARI
2fd10 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 ANTS:.**.** {H16
2fd20 32 37 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 272} The [sqlite
2fd30 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 3_get_auxdata(C,
2fd40 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 N)] interface re
2fd50 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a turns a pointer.
2fd60 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 6d ** to m
2fd70 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 etadata associat
2fd80 65 64 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 ed with the Nth
2fd90 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 parameter of the
2fda0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a SQL function.**
2fdb0 20 20 20 20 20 20 20 20 20 20 77 68 6f 73 65 20 whose
2fdc0 63 6f 6e 74 65 78 74 20 69 73 20 43 2c 20 6f 72 context is C, or
2fdd0 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 NULL if there i
2fde0 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 61 73 s no metadata as
2fdf0 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 sociated.**
2fe00 20 20 20 20 20 77 69 74 68 20 74 68 61 74 20 70 with that p
2fe10 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
2fe20 7b 48 31 36 32 37 34 7d 20 54 68 65 20 5b 73 71 {H16274} The [sq
2fe30 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
2fe40 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 a(C,N,P,D)] inte
2fe50 72 66 61 63 65 20 61 73 73 69 67 6e 73 20 61 20 rface assigns a
2fe60 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 metadata.**
2fe70 20 20 20 20 20 70 6f 69 6e 74 65 72 20 50 20 74 pointer P t
2fe80 6f 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65 o the Nth parame
2fe90 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66 ter of the SQL f
2fea0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e unction with con
2feb0 74 65 78 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 text C..**.** {H
2fec0 31 36 32 37 36 7d 20 53 51 4c 69 74 65 20 77 69 16276} SQLite wi
2fed0 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 ll invoke the de
2fee0 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 structor D with
2fef0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
2ff00 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 t.** wh
2ff10 69 63 68 20 69 73 20 74 68 65 20 6d 65 74 61 64 ich is the metad
2ff20 61 74 61 20 70 6f 69 6e 74 65 72 20 50 20 66 6f ata pointer P fo
2ff30 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 llowing a call t
2ff40 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 o.** [s
2ff50 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
2ff60 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 ta(C,N,P,D)] whe
2ff70 6e 20 53 51 4c 69 74 65 20 63 65 61 73 65 73 20 n SQLite ceases
2ff80 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 to hold.**
2ff90 20 20 20 20 74 68 65 20 6d 65 74 61 64 61 74 61 the metadata
2ffa0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 37 7d ..**.** {H16277}
2ffb0 20 53 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 SQLite ceases t
2ffc0 6f 20 68 6f 6c 64 20 6d 65 74 61 64 61 74 61 20 o hold metadata
2ffd0 66 6f 72 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 for an SQL funct
2ffe0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a ion parameter.**
2fff0 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 20 74 when t
30000 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 he value of that
30010 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 parameter chang
30020 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 es..**.** {H1627
30030 38 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 8} When [sqlite3
30040 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e _set_auxdata(C,N
30050 2c 50 2c 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65 ,P,D)] is invoke
30060 64 2c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f d, the destructo
30070 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 r.** is
30080 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20 called for any
30090 70 72 69 6f 72 20 6d 65 74 61 64 61 74 61 20 61 prior metadata a
300a0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
300b0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e he same function
300c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e .** con
300d0 74 65 78 74 20 43 20 61 6e 64 20 70 61 72 61 6d text C and param
300e0 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 eter N..**.** {H
300f0 31 36 32 37 39 7d 20 53 51 4c 69 74 65 20 77 69 16279} SQLite wi
30100 6c 6c 20 63 61 6c 6c 20 64 65 73 74 72 75 63 74 ll call destruct
30110 6f 72 73 20 66 6f 72 20 61 6e 79 20 6d 65 74 61 ors for any meta
30120 64 61 74 61 20 69 74 20 69 73 20 68 6f 6c 64 69 data it is holdi
30130 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 ng.** i
30140 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b n a particular [
30150 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
30160 6e 74 5d 20 53 20 77 68 65 6e 20 65 69 74 68 65 nt] S when eithe
30170 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 r.** [s
30180 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
30190 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e or [sqlite3_fin
301a0 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c alize(S)] is cal
301b0 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 led..*/.void *sq
301c0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
301d0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
301e0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 t*, int N);.void
301f0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
30200 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e data(sqlite3_con
30210 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f text*, int N, vo
30220 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f id*, void (*)(vo
30230 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 id*));.../*.** C
30240 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e API3REF: Constan
30250 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 ts Defining Spec
30260 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 ial Destructor B
30270 65 68 61 76 69 6f 72 20 7b 48 31 30 32 38 30 7d ehavior {H10280}
30280 20 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S30100>.**.**
30290 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 These are specia
302a0 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 l values for the
302b0 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 destructor that
302c0 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 is passed in as
302d0 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 the.** final ar
302e0 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e gument to routin
302f0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 es like [sqlite3
30300 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e _result_blob()].
30310 20 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 If the destruc
30320 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 tor.** argument
30330 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 is SQLITE_STATIC
30340 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 , it means that
30350 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e the content poin
30360 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a ter is constant.
30370 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 ** and will neve
30380 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f r change. It do
30390 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 es not need to b
303a0 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 e destroyed. Th
303b0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e e.** SQLITE_TRAN
303c0 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e SIENT value mean
303d0 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 s that the conte
303e0 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 nt will likely c
303f0 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 hange in.** the
30400 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 near future and
30410 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 that SQLite shou
30420 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 ld make its own
30430 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a private copy of.
30440 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 ** the content b
30450 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e efore returning.
30460 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 .**.** The typed
30470 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 ef is necessary
30480 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 to work around p
30490 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 roblems in certa
304a0 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c in.** C++ compil
304b0 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 ers. See ticket
304c0 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 #2191..*/.typed
304d0 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 ef void (*sqlite
304e0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 3_destructor_typ
304f0 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 e)(void*);.#defi
30500 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 ne SQLITE_STATIC
30510 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f ((sqlite3_
30520 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 destructor_type)
30530 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0).#define SQLIT
30540 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 E_TRANSIENT ((
30550 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
30560 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a or_type)-1)../*.
30570 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 ** CAPI3REF: Set
30580 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 ting The Result
30590 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 Of An SQL Functi
305a0 6f 6e 20 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 on {H16400} <S20
305b0 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 200>.**.** These
305c0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 routines are us
305d0 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 ed by the xFunc
305e0 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 or xFinal callba
305f0 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c cks that.** impl
30600 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 ement SQL functi
30610 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 ons and aggregat
30620 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c es. See.** [sql
30630 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
30640 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c tion()] and [sql
30650 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
30660 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 tion16()].** for
30670 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f additional info
30680 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 rmation..**.** T
30690 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 hese functions w
306a0 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 ork very much li
306b0 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 ke the [paramete
306c0 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c r binding] famil
306d0 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e y of.** function
306e0 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 s used to bind v
306f0 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 alues to host pa
30700 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 rameters in prep
30710 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e ared statements.
30720 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 .** Refer to the
30730 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d [SQL parameter]
30740 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 documentation f
30750 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e or additional in
30760 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
30770 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
30780 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 ult_blob() inter
30790 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
307a0 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 sult from.** an
307b0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
307c0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
307d0 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 be the BLOB whos
307e0 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 e content is poi
307f0 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 nted.** to by th
30800 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
30810 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 er and which is
30820 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 N bytes long whe
30830 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 re N is the.** t
30840 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a hird parameter..
30850 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
30860 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 3_result_zeroblo
30870 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 b() interfaces s
30880 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 et the result of
30890 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
308a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
308b0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f tion to be a BLO
308c0 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c B containing all
308d0 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 zero.** bytes a
308e0 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 nd N bytes in si
308f0 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 ze, where N is t
30900 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
30910 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2nd parameter..*
30920 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
30930 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 _result_double()
30940 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
30950 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a the result from.
30960 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f ** an applicatio
30970 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
30980 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 on to be a float
30990 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 ing point value
309a0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 specified.** by
309b0 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 its 2nd argument
309c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
309d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
309e0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 () and sqlite3_r
309f0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 esult_error16()
30a00 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 functions.** cau
30a10 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 se the implement
30a20 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ed SQL function
30a30 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 to throw an exce
30a40 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 ption..** SQLite
30a50 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 uses the string
30a60 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 pointed to by t
30a70 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 he.** 2nd parame
30a80 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 ter of sqlite3_r
30a90 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 esult_error() or
30aa0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
30ab0 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 error16().** as
30ac0 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 the text of an e
30ad0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 53 rror message. S
30ae0 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 QLite interprets
30af0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 the error.** me
30b00 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f ssage string fro
30b10 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 m sqlite3_result
30b20 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d _error() as UTF-
30b30 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 8. SQLite.** int
30b40 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 erprets the stri
30b50 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ng from sqlite3_
30b60 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
30b70 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 as UTF-16 in na
30b80 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 tive.** byte ord
30b90 65 72 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 er. If the thir
30ba0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
30bb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
30bc0 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 ror().** or sqli
30bd0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
30be0 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 16() is negative
30bf0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b then SQLite tak
30c00 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a es as the error.
30c10 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 ** message all t
30c20 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 ext up through t
30c30 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 he first zero ch
30c40 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 aracter..** If t
30c50 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
30c60 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
30c70 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a sult_error() or.
30c80 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c ** sqlite3_resul
30c90 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e t_error16() is n
30ca0 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e on-negative then
30cb0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 SQLite takes th
30cc0 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 at many.** bytes
30cd0 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 (not characters
30ce0 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 ) from the 2nd p
30cf0 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 arameter as the
30d00 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a error message..*
30d10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
30d20 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 sult_error() and
30d30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
30d40 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 error16().** rou
30d50 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 tines make a pri
30d60 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 vate copy of the
30d70 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 error message t
30d80 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 ext before.** th
30d90 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 ey return. Henc
30da0 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 e, the calling f
30db0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c unction can deal
30dc0 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 locate or.** mod
30dd0 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 ify the text aft
30de0 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 er they return w
30df0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 ithout harm..**
30e00 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
30e10 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 lt_error_code()
30e20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 function changes
30e30 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a the error code.
30e40 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 ** returned by S
30e50 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c QLite as a resul
30e60 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e t of an error in
30e70 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 a function. By
30e80 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 default,.** the
30e90 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 error code is S
30ea0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 QLITE_ERROR. A
30eb0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 subsequent call
30ec0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c to sqlite3_resul
30ed0 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 t_error().** or
30ee0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
30ef0 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 rror16() resets
30f00 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 the error code t
30f10 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a o SQLITE_ERROR..
30f20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
30f30 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 3_result_toobig(
30f40 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 ) interface caus
30f50 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 es SQLite to thr
30f60 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 ow an error.** i
30f70 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 ndicating that a
30f80 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 string or BLOB
30f90 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 is to long to re
30fa0 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 present..**.** T
30fb0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
30fc0 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 t_nomem() interf
30fd0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 ace causes SQLit
30fe0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 e to throw an er
30ff0 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e ror.** indicatin
31000 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 g that a memory
31010 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 allocation faile
31020 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c d..**.** The sql
31030 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 ite3_result_int(
31040 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
31050 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
31060 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c e.** of the appl
31070 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
31080 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 function to be t
31090 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 he 32-bit signed
310a0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 integer.** valu
310b0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 e given in the 2
310c0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 nd argument..**
310d0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
310e0 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 lt_int64() inter
310f0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
31100 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 turn value.** of
31110 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
31120 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
31130 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 n to be the 64-b
31140 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 it signed intege
31150 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e r.** value given
31160 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 in the 2nd argu
31170 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ment..**.** The
31180 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e sqlite3_result_n
31190 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 ull() interface
311a0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 sets the return
311b0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 value.** of the
311c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
311d0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
311e0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 be NULL..**.** T
311f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
31200 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 t_text(), sqlite
31210 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 3_result_text16(
31220 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 ),.** sqlite3_re
31230 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c sult_text16le(),
31240 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 and sqlite3_res
31250 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 ult_text16be() i
31260 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 nterfaces.** set
31270 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
31280 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 e of the applica
31290 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
312a0 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 ction to be.** a
312b0 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 text string whi
312c0 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 ch is represente
312d0 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d d as UTF-8, UTF-
312e0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 16 native byte o
312f0 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 rder,.** UTF-16
31300 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f little endian, o
31310 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 r UTF-16 big end
31320 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c ian, respectivel
31330 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b y..** SQLite tak
31340 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 es the text resu
31350 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c lt from the appl
31360 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 ication from.**
31370 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
31380 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 r of the sqlite3
31390 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
313a0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 terfaces..** If
313b0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
313c0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
313d0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
313e0 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e terfaces.** is n
313f0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 egative, then SQ
31400 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c Lite takes resul
31410 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 t text from the
31420 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 2nd parameter.**
31430 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 through the fir
31440 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 st zero characte
31450 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 r..** If the 3rd
31460 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
31470 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
31480 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
31490 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 s.** is non-nega
314a0 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 tive, then as ma
314b0 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 ny bytes (not ch
314c0 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 aracters) of the
314d0 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 text.** pointed
314e0 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 to by the 2nd p
314f0 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b arameter are tak
31500 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 en as the applic
31510 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a ation-defined.**
31520 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 function result
31530 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 ..** If the 4th
31540 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
31550 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
31560 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
31570 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 .** or sqlite3_r
31580 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 esult_blob is a
31590 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 non-NULL pointer
315a0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 , then SQLite ca
315b0 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 lls that.** func
315c0 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 tion as the dest
315d0 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 ructor on the te
315e0 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c xt or BLOB resul
315f0 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a t when it has.**
31600 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 finished using
31610 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 that result..**
31620 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d If the 4th param
31630 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
31640 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
31650 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 0a 2a interfaces or.*
31660 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 * sqlite3_result
31670 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 _blob is the spe
31680 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 cial constant SQ
31690 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 LITE_STATIC, the
316a0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 n SQLite.** assu
316b0 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 mes that the tex
316c0 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 t or BLOB result
316d0 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 is in constant
316e0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e space and does n
316f0 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 69 ot.** copy the i
31700 74 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 t or call a dest
31710 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74 20 68 ructor when it h
31720 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e as finished usin
31730 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a g that result..*
31740 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 * If the 4th par
31750 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
31760 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
31770 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
31780 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
31790 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 lt_blob is the s
317a0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 pecial constant
317b0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
317c0 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 .** then SQLite
317d0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 makes a copy of
317e0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 the result into
317f0 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 space obtained f
31800 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c rom.** from [sql
31810 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 ite3_malloc()] b
31820 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 efore it returns
31830 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
31840 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
31850 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
31860 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a s the result of.
31870 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
31880 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
31890 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 ion to be a copy
318a0 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 the.** [unprote
318b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
318c0 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 ue] object speci
318d0 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 fied by the 2nd
318e0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 0a parameter. The.
318f0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c ** sqlite3_resul
31900 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 t_value() interf
31910 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 ace makes a copy
31920 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
31930 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 _value].** so th
31940 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f at the [sqlite3_
31950 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 value] specified
31960 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 in the paramete
31970 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a r may change or.
31980 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 ** be deallocate
31990 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f d after sqlite3_
319a0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 result_value() r
319b0 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 eturns without h
319c0 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 arm..** A [prote
319d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
319e0 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 ue] object may a
319f0 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 lways be used wh
31a00 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f ere an.** [unpro
31a10 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
31a20 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 alue] object is
31a30 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 required, so eit
31a40 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b her.** kind of [
31a50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
31a60 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 bject can be use
31a70 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 d with this inte
31a80 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 rface..**.** If
31a90 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 these routines a
31aa0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 re called from w
31ab0 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 ithin the differ
31ac0 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 ent thread.** th
31ad0 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 an the one conta
31ae0 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 ining the applic
31af0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
31b00 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 nction that rece
31b10 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c ived.** the [sql
31b20 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f ite3_context] po
31b30 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c inter, the resul
31b40 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
31b50 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
31b60 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 TS:.**.** {H1640
31b70 33 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 72 3} The default r
31b80 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d eturn value from
31b90 20 61 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f any SQL functio
31ba0 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a n is NULL..**.**
31bb0 20 7b 48 31 36 34 30 36 7d 20 54 68 65 20 5b 73 {H16406} The [s
31bc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
31bd0 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 ob(C,V,N,D)] int
31be0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 erface changes t
31bf0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 he.** r
31c00 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 eturn value of f
31c10 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 unction C to be
31c20 61 20 42 4c 4f 42 20 74 68 61 74 20 69 73 20 4e a BLOB that is N
31c30 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 bytes.**
31c40 20 20 20 69 6e 20 6c 65 6e 67 74 68 20 61 6e 64 in length and
31c50 20 77 69 74 68 20 63 6f 6e 74 65 6e 74 20 70 6f with content po
31c60 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2e 0a 2a inted to by V..*
31c70 2a 0a 2a 2a 20 7b 48 31 36 34 30 39 7d 20 54 68 *.** {H16409} Th
31c80 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c e [sqlite3_resul
31c90 74 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d 20 69 t_double(C,V)] i
31ca0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 nterface changes
31cb0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
31cc0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
31cd0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 function C to b
31ce0 65 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 e the floating p
31cf0 6f 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a 2a 2a oint value V..**
31d00 0a 2a 2a 20 7b 48 31 36 34 31 32 7d 20 54 68 65 .** {H16412} The
31d10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
31d20 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d 20 69 _error(C,V,N)] i
31d30 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 nterface changes
31d40 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 the return.**
31d50 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 value of
31d60 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 function C to b
31d70 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 e an exception w
31d80 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a ith error code.*
31d90 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 * [SQLI
31da0 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 TE_ERROR] and a
31db0 55 54 46 2d 38 20 65 72 72 6f 72 20 6d 65 73 73 UTF-8 error mess
31dc0 61 67 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 age copied from
31dd0 56 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20 V up to the.**
31de0 20 20 20 20 20 20 20 20 66 69 72 73 74 20 7a 65 first ze
31df0 72 6f 20 62 79 74 65 20 6f 72 20 75 6e 74 69 6c ro byte or until
31e00 20 4e 20 62 79 74 65 73 20 61 72 65 20 72 65 61 N bytes are rea
31e10 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 d if N is positi
31e20 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 ve..**.** {H1641
31e30 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 5} The [sqlite3_
31e40 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 43 result_error16(C
31e50 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 ,V,N)] interface
31e60 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 changes the ret
31e70 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 urn.**
31e80 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f value of functio
31e90 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 n C to be an exc
31ea0 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f eption with erro
31eb0 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 r code.**
31ec0 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 [SQLITE_ERROR
31ed0 5d 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 6e ] and a UTF-16 n
31ee0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
31ef0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a error message.*
31f00 2a 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65 * copie
31f10 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 d from V up to t
31f20 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 he first zero te
31f30 72 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 rminator or unti
31f40 6c 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 l N bytes.**
31f50 20 20 20 20 20 20 61 72 65 20 72 65 61 64 20 69 are read i
31f60 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e f N is positive.
31f70 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 38 7d 20 .**.** {H16418}
31f80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
31f90 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 ult_error_toobig
31fa0 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 (C)] interface c
31fb0 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 hanges the retur
31fc0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 n.** va
31fd0 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 lue of the funct
31fe0 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 ion C to be an e
31ff0 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 xception with er
32000 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 ror code.**
32010 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f [SQLITE_TOO
32020 42 49 47 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 BIG] and an appr
32030 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 opriate error me
32040 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ssage..**.** {H1
32050 36 34 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 6421} The [sqlit
32060 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
32070 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65 72 66 nomem(C)] interf
32080 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 ace changes the
32090 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 return.**
320a0 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 value of the
320b0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 function C to be
320c0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 an exception wi
320d0 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a th error code.**
320e0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 [SQLIT
320f0 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 E_NOMEM] and an
32100 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f appropriate erro
32110 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a r message..**.**
32120 20 7b 48 31 36 34 32 34 7d 20 54 68 65 20 5b 73 {H16424} The [s
32130 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
32140 72 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 ror_code(C,E)] i
32150 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 nterface changes
32160 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 the return.**
32170 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 value of
32180 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 the function C
32190 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 to be an excepti
321a0 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f on with error co
321b0 64 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20 de E..**
321c0 20 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73 The error mess
321d0 61 67 65 20 74 65 78 74 20 69 73 20 75 6e 63 68 age text is unch
321e0 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 anged..**.** {H1
321f0 36 34 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 6427} The [sqlit
32200 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c e3_result_int(C,
32210 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 V)] interface ch
32220 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 anges the.**
32230 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c return val
32240 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 ue of function C
32250 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 to be the 32-bi
32260 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 t integer value
32270 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 30 V..**.** {H16430
32280 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 } The [sqlite3_r
32290 65 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29 esult_int64(C,V)
322a0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e ] interface chan
322b0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ges the.**
322c0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 return value
322d0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 of function C t
322e0 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 o be the 64-bit
322f0 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e integer value V.
32300 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 33 7d 20 .**.** {H16433}
32310 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
32320 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 ult_null(C)] int
32330 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 erface changes t
32340 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 he.** r
32350 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 eturn value of f
32360 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 unction C to be
32370 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 NULL..**.** {H16
32380 34 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 436} The [sqlite
32390 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 3_result_text(C,
323a0 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 V,N,D)] interfac
323b0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a e changes the.**
323c0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e return
323d0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 value of functi
323e0 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 on C to be the U
323f0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 TF-8 string.**
32400 20 20 20 20 20 20 20 20 56 20 75 70 20 74 6f 20 V up to
32410 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 the first zero i
32420 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a f N is negative.
32430 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 ** or t
32440 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 he first N bytes
32450 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f of V if N is no
32460 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a n-negative..**.*
32470 2a 20 7b 48 31 36 34 33 39 7d 20 54 68 65 20 5b * {H16439} The [
32480 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
32490 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 ext16(C,V,N,D)]
324a0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 interface change
324b0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
324c0 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f return value o
324d0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 f function C to
324e0 62 65 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 be the UTF-16 na
324f0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a tive byte order.
32500 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 ** stri
32510 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 ng V up to the f
32520 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 irst zero if N i
32530 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 s negative.**
32540 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 or the fi
32550 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 rst N bytes of V
32560 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 if N is non-neg
32570 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ative..**.** {H1
32580 36 34 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 6442} The [sqlit
32590 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
325a0 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 be(C,V,N,D)] int
325b0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 erface changes t
325c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 he.** r
325d0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 eturn value of f
325e0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 unction C to be
325f0 74 68 65 20 55 54 46 2d 31 36 20 62 69 67 2d 65 the UTF-16 big-e
32600 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ndian.**
32610 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f string V up to
32620 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 the first zero
32630 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 if N is negative
32640 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
32650 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 the first N byte
32660 73 20 6f 72 20 56 20 69 66 20 4e 20 69 73 20 6e s or V if N is n
32670 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a on-negative..**.
32680 2a 2a 20 7b 48 31 36 34 34 35 7d 20 54 68 65 20 ** {H16445} The
32690 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
326a0 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 text16le(C,V,N,D
326b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 )] interface cha
326c0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 nges the.**
326d0 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 return valu
326e0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 e of function C
326f0 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 36 to be the UTF-16
32700 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a little-endian.*
32710 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e * strin
32720 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 g V up to the fi
32730 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 rst zero if N is
32740 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 negative.**
32750 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 or the fir
32760 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 st N bytes of V
32770 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 if N is non-nega
32780 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 tive..**.** {H16
32790 34 34 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 448} The [sqlite
327a0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 3_result_value(C
327b0 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 ,V)] interface c
327c0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 hanges the.**
327d0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 return va
327e0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 lue of function
327f0 43 20 74 6f 20 62 65 20 74 68 65 20 5b 75 6e 70 C to be the [unp
32800 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
32810 5f 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20 _value].**
32820 20 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a object V..**
32830 0a 2a 2a 20 7b 48 31 36 34 35 31 7d 20 54 68 65 .** {H16451} The
32840 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
32850 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 _zeroblob(C,N)]
32860 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 interface change
32870 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
32880 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f return value o
32890 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 f function C to
328a0 62 65 20 61 6e 20 4e 2d 62 79 74 65 20 42 4c 4f be an N-byte BLO
328b0 42 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a B of all zeros..
328c0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 34 7d 20 54 **.** {H16454} T
328d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 he [sqlite3_resu
328e0 6c 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e 64 20 lt_error()] and
328f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
32900 65 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20 error16()].**
32910 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 interface
32920 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 s make a copy of
32930 20 74 68 65 69 72 20 65 72 72 6f 72 20 6d 65 73 their error mes
32940 73 61 67 65 20 73 74 72 69 6e 67 73 20 62 65 66 sage strings bef
32950 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ore.**
32960 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a returning..**.**
32970 20 7b 48 31 36 34 35 37 7d 20 49 66 20 74 68 65 {H16457} If the
32980 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 D destructor pa
32990 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
329a0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
329b0 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 C,V,N,D)],.**
329c0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
329d0 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c result_text(C,V,
329e0 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f N,D)], [sqlite3_
329f0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c result_text16(C,
32a00 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 V,N,D)],.**
32a10 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 [sqlite3_re
32a20 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c sult_text16be(C,
32a30 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 V,N,D)], or.**
32a40 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
32a50 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 _result_text16le
32a60 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 (C,V,N,D)] is th
32a70 65 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 e constant [SQLI
32a80 54 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20 TE_STATIC].**
32a90 20 20 20 20 20 20 20 74 68 65 6e 20 6e 6f 20 64 then no d
32aa0 65 73 74 72 75 63 74 6f 72 20 69 73 20 65 76 65 estructor is eve
32ab0 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 r called on the
32ac0 70 6f 69 6e 74 65 72 20 56 20 61 6e 64 20 53 51 pointer V and SQ
32ad0 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 Lite.**
32ae0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 56 20 assumes that V
32af0 69 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a is immutable..**
32b00 0a 2a 2a 20 7b 48 31 36 34 36 30 7d 20 49 66 20 .** {H16460} If
32b10 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 the D destructor
32b20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
32b30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
32b40 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a ob(C,V,N,D)],.**
32b50 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
32b60 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 e3_result_text(C
32b70 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 ,V,N,D)], [sqlit
32b80 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
32b90 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 (C,V,N,D)],.**
32ba0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
32bb0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 _result_text16be
32bc0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a (C,V,N,D)], or.*
32bd0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
32be0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
32bf0 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 6le(C,V,N,D)] is
32c00 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a the constant.**
32c10 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 [SQLIT
32c20 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 E_TRANSIENT] the
32c30 6e 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 n the interfaces
32c40 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 makes a copy of
32c50 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
32c60 20 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e content of V an
32c70 64 20 72 65 74 61 69 6e 73 20 74 68 65 20 63 6f d retains the co
32c80 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 py..**.** {H1646
32c90 33 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 3} If the D dest
32ca0 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 ructor parameter
32cb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
32cc0 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 ult_blob(C,V,N,D
32cd0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 )],.**
32ce0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
32cf0 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 text(C,V,N,D)],
32d00 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
32d10 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d text16(C,V,N,D)]
32d20 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 ,.** [s
32d30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
32d40 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d xt16be(C,V,N,D)]
32d50 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 , or.**
32d60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
32d70 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c _text16le(C,V,N,
32d80 44 29 5d 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 D)] is some valu
32d90 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 e other than.**
32da0 20 20 20 20 20 20 20 20 20 74 68 65 20 63 6f 6e the con
32db0 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53 stants [SQLITE_S
32dc0 54 41 54 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49 TATIC] and [SQLI
32dd0 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 TE_TRANSIENT] th
32de0 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 en.** S
32df0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b QLite will invok
32e00 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 e the destructor
32e10 20 44 20 77 69 74 68 20 56 20 61 73 20 69 74 73 D with V as its
32e20 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a only argument.*
32e30 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 20 * when
32e40 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 it has finished
32e50 77 69 74 68 20 74 68 65 20 56 20 76 61 6c 75 65 with the V value
32e60 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ..*/.void sqlite
32e70 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 3_result_blob(sq
32e80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
32e90 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
32ea0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
32eb0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
32ec0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 result_double(sq
32ed0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
32ee0 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 double);.void sq
32ef0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
32f00 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 or(sqlite3_conte
32f10 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a xt*, const char*
32f20 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c , int);.void sql
32f30 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
32f40 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 r16(sqlite3_cont
32f50 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ext*, const void
32f60 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 *, int);.void sq
32f70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
32f80 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 or_toobig(sqlite
32f90 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 3_context*);.voi
32fa0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
32fb0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c _error_nomem(sql
32fc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
32fd0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
32fe0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 ult_error_code(s
32ff0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
33000 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 int);.void sqli
33010 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 te3_result_int(s
33020 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
33030 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 int);.void sqli
33040 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 te3_result_int64
33050 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
33060 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
33070 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
33080 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 result_null(sqli
33090 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 te3_context*);.v
330a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
330b0 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f lt_text(sqlite3_
330c0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
330d0 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 char*, int, void
330e0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
330f0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
33100 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f _text16(sqlite3_
33110 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
33120 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 void*, int, void
33130 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
33140 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
33150 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 _text16le(sqlite
33160 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
33170 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 t void*, int,voi
33180 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f d(*)(void*));.vo
33190 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
331a0 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 t_text16be(sqlit
331b0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
331c0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f st void*, int,vo
331d0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 id(*)(void*));.v
331e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
331f0 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 lt_value(sqlite3
33200 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 _context*, sqlit
33210 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 e3_value*);.void
33220 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33230 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 zeroblob(sqlite3
33240 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e _context*, int n
33250 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
33260 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 EF: Define New C
33270 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 ollating Sequenc
33280 65 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 es {H16600} <S20
33290 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 300>.**.** These
332a0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 functions are u
332b0 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 sed to add new c
332c0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
332d0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 es to the.** [da
332e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
332f0 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 n] specified as
33300 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
33310 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 nt..**.** The na
33320 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f me of the new co
33330 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
33340 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73 is specified as
33350 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a a UTF-8 string.
33360 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 ** for sqlite3_c
33370 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 reate_collation(
33380 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 ) and sqlite3_cr
33390 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
333a0 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2().** and a UTF
333b0 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 -16 string for s
333c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
333d0 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 llation16(). In
333e0 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 all cases.** the
333f0 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 name is passed
33400 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 as the second fu
33410 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e nction argument.
33420 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 .**.** The third
33430 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 argument may be
33440 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 one of the cons
33450 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 tants [SQLITE_UT
33460 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f F8],.** [SQLITE_
33470 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c UTF16LE] or [SQL
33480 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e ITE_UTF16BE], in
33490 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 dicating that th
334a0 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a e user-supplied.
334b0 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 ** routine expec
334c0 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 ts to be passed
334d0 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 pointers to stri
334e0 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e ngs encoded usin
334f0 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d g UTF-8,.** UTF-
33500 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 16 little-endian
33510 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d , or UTF-16 big-
33520 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 endian, respecti
33530 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 vely. The.** thi
33540 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 rd argument migh
33550 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 t also be [SQLIT
33560 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d E_UTF16_ALIGNED]
33570 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
33580 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 t.** the routine
33590 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 expects pointer
335a0 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 s to 16-bit word
335b0 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 aligned strings
335c0 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e .** of UTF-16 in
335d0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
335e0 20 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f order of the ho
335f0 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a st computer..**.
33600 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** A pointer to
33610 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 the user supplie
33620 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 d routine must b
33630 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
33640 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e fifth.** argumen
33650 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c t. If it is NUL
33660 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73 L, this is the s
33670 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 ame as deleting
33680 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a the collation.**
33690 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 sequence (so th
336a0 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 at SQLite cannot
336b0 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 call it anymore
336c0 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 )..** Each time
336d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
336e0 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f supplied functio
336f0 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 n is invoked, it
33700 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 is passed.** as
33710 20 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d its first param
33720 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74 eter a copy of t
33730 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 he void* passed
33740 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 as the fourth ar
33750 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c gument.** to sql
33760 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
33770 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 ation() or sqlit
33780 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
33790 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 ion16()..**.** T
337a0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 he remaining arg
337b0 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 uments to the ap
337c0 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 plication-suppli
337d0 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 ed routine are t
337e0 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 wo strings,.** e
337f0 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 ach represented
33800 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 by a (length, da
33810 74 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 ta) pair and enc
33820 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f oded in the enco
33830 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 ding.** that was
33840 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 passed as the t
33850 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 hird argument wh
33860 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e en the collation
33870 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a sequence was.**
33880 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e registered. {EN
33890 44 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 D} The applicat
338a0 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c ion defined coll
338b0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 ation routine sh
338c0 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e ould.** return n
338d0 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 egative, zero or
338e0 20 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 65 positive if the
338f0 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 first string is
33900 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 less than,.** e
33910 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 qual to, or grea
33920 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 ter than the sec
33930 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e ond string. i.e.
33940 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 (STRING1 - STRI
33950 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 NG2)..**.** The
33960 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
33970 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f ollation_v2() wo
33980 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 rks like sqlite3
33990 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
339a0 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 n().** except th
339b0 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 at it takes an e
339c0 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 xtra argument wh
339d0 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63 ich is a destruc
339e0 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 tor for.** the c
339f0 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 ollation. The d
33a00 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c estructor is cal
33a10 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c led when the col
33a20 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 lation is.** des
33a30 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 troyed and is pa
33a40 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 ssed a copy of t
33a50 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
33a60 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 ter void* pointe
33a70 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 r.** of the sqli
33a80 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
33a90 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f tion_v2()..** Co
33aa0 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 llations are des
33ab0 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79 troyed when they
33ac0 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 are overridden
33ad0 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 by later calls t
33ae0 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 o the.** collati
33af0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 on creation func
33b00 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 tions or when th
33b10 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
33b20 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 ection] is close
33b30 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 d.** using [sqli
33b40 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a te3_close()]..**
33b50 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
33b60 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 33 7d 20 41 **.** {H16603} A
33b70 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
33b80 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 to the.**
33b90 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 [sqlite3_cre
33ba0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
33bb0 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 (B,X,E,P,F,D)] i
33bc0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 nterface.**
33bd0 20 20 20 20 20 72 65 67 69 73 74 65 72 73 20 66 registers f
33be0 75 6e 63 74 69 6f 6e 20 46 20 61 73 20 74 68 65 unction F as the
33bf0 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 comparison func
33c00 74 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 tion used to.**
33c10 20 20 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 impleme
33c20 6e 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f nt collation X o
33c30 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 n the [database
33c40 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f connection] B fo
33c50 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 r.** da
33c60 74 61 62 61 73 65 73 20 68 61 76 69 6e 67 20 65 tabases having e
33c70 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a ncoding E..**.**
33c80 20 7b 48 31 36 36 30 34 7d 20 53 51 4c 69 74 65 {H16604} SQLite
33c90 20 75 6e 64 65 72 73 74 61 6e 64 73 20 74 68 65 understands the
33ca0 20 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a X parameter to.
33cb0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
33cc0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
33cd0 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 ation_v2(B,X,E,P
33ce0 2c 46 2c 44 29 5d 20 61 73 20 61 20 7a 65 72 6f ,F,D)] as a zero
33cf0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 -terminated.**
33d00 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 UTF-8 st
33d10 72 69 6e 67 20 69 6e 20 77 68 69 63 68 20 63 61 ring in which ca
33d20 73 65 20 69 73 20 69 67 6e 6f 72 65 64 20 66 6f se is ignored fo
33d30 72 20 41 53 43 49 49 20 63 68 61 72 61 63 74 65 r ASCII characte
33d40 72 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 rs and.**
33d50 20 20 20 69 73 20 73 69 67 6e 69 66 69 63 61 6e is significan
33d60 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 t for non-ASCII
33d70 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a characters..**.*
33d80 2a 20 7b 48 31 36 36 30 36 7d 20 53 75 63 63 65 * {H16606} Succe
33d90 73 73 69 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b ssive calls to [
33da0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
33db0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c ollation_v2(B,X,
33dc0 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 E,P,F,D)].**
33dd0 20 20 20 20 20 20 77 69 74 68 20 74 68 65 20 73 with the s
33de0 61 6d 65 20 76 61 6c 75 65 73 20 66 6f 72 20 42 ame values for B
33df0 2c 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 , X, and E, over
33e00 72 69 64 65 20 70 72 69 6f 72 20 76 61 6c 75 65 ride prior value
33e10 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 s.** of
33e20 20 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a P, F, and D..**
33e30 0a 2a 2a 20 7b 48 31 36 36 30 39 7d 20 49 66 20 .** {H16609} If
33e40 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 the destructor D
33e50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 in [sqlite3_cre
33e60 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
33e70 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a (B,X,E,P,F,D)].*
33e80 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f * is no
33e90 74 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 t NULL then it i
33ea0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 72 s called with ar
33eb0 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 20 74 68 gument P when th
33ec0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f e.** co
33ed0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
33ee0 20 69 73 20 64 72 6f 70 70 65 64 20 62 79 20 53 is dropped by S
33ef0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 QLite..**.** {H1
33f00 36 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 6612} A collatin
33f10 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 g function is dr
33f20 6f 70 70 65 64 20 77 68 65 6e 20 69 74 20 69 73 opped when it is
33f30 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a overloaded..**.
33f40 2a 2a 20 7b 48 31 36 36 31 35 7d 20 41 20 63 6f ** {H16615} A co
33f50 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
33f60 20 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e is dropped when
33f70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
33f80 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 nnection.**
33f90 20 20 20 20 20 69 73 20 63 6c 6f 73 65 64 20 75 is closed u
33fa0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c sing [sqlite3_cl
33fb0 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ose()]..**.** {H
33fc0 31 36 36 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 16618} The point
33fd0 65 72 20 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 er P in [sqlite3
33fe0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
33ff0 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 n_v2(B,X,E,P,F,D
34000 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 )].** i
34010 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 s passed through
34020 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 as the first pa
34030 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 rameter to the c
34040 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 omparison.**
34050 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 function F
34060 20 66 6f 72 20 61 6c 6c 20 73 75 62 73 65 71 75 for all subsequ
34070 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 ent invocations
34080 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 of F..**.** {H16
34090 36 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 621} A call to [
340a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
340b0 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 ollation(B,X,E,P
340c0 2c 46 29 5d 20 69 73 20 65 78 61 63 74 6c 79 0a ,F)] is exactly.
340d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
340e0 73 61 6d 65 20 61 73 20 61 20 63 61 6c 6c 20 74 same as a call t
340f0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 o [sqlite3_creat
34100 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 e_collation_v2()
34110 5d 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 ] with.**
34120 20 20 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 the same para
34130 6d 65 74 65 72 73 20 61 6e 64 20 61 20 4e 55 4c meters and a NUL
34140 4c 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a L destructor..**
34150 0a 2a 2a 20 7b 48 31 36 36 32 34 7d 20 46 6f 6c .** {H16624} Fol
34160 6c 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 lowing a [sqlite
34170 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
34180 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c on_v2(B,X,E,P,F,
34190 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 D)],.**
341a0 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 SQLite uses the
341b0 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 comparison func
341c0 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 tion F for all t
341d0 65 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a ext comparison.*
341e0 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65 72 61 * opera
341f0 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 5b 64 61 tions on the [da
34200 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
34210 6e 5d 20 42 20 6f 6e 20 74 65 78 74 20 76 61 6c n] B on text val
34220 75 65 73 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 ues that.**
34230 20 20 20 20 20 75 73 65 20 74 68 65 20 63 6f 6c use the col
34240 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 lating sequence
34250 6e 61 6d 65 64 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b named X..**.** {
34260 48 31 36 36 32 37 7d 20 54 68 65 20 5b 73 71 6c H16627} The [sql
34270 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
34280 61 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c ation16(B,X,E,P,
34290 46 29 5d 20 77 6f 72 6b 73 20 74 68 65 20 73 61 F)] works the sa
342a0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 me.** a
342b0 73 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 s [sqlite3_creat
342c0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c e_collation(B,X,
342d0 45 2c 50 2c 46 29 5d 20 65 78 63 65 70 74 20 74 E,P,F)] except t
342e0 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 hat the.**
342f0 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 collation na
34300 6d 65 20 58 20 69 73 20 75 6e 64 65 72 73 74 6f me X is understo
34310 6f 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 od as UTF-16 in
34320 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
34330 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e r.** in
34340 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a stead of UTF-8..
34350 2a 2a 0a 2a 2a 20 7b 48 31 36 36 33 30 7d 20 57 **.** {H16630} W
34360 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d hen multiple com
34370 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e parison function
34380 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 s are available
34390 66 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 for the same.**
343a0 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 collati
343b0 6e 67 20 73 65 71 75 65 6e 63 65 2c 20 53 51 4c ng sequence, SQL
343c0 69 74 65 20 63 68 6f 6f 73 65 73 20 74 68 65 20 ite chooses the
343d0 6f 6e 65 20 77 68 6f 73 65 20 74 65 78 74 20 65 one whose text e
343e0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 ncoding.**
343f0 20 20 20 20 72 65 71 75 69 72 65 73 20 74 68 65 requires the
34400 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 least amount of
34410 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d conversion from
34420 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 the default.**
34430 20 20 20 20 20 20 20 20 20 74 65 78 74 20 65 6e text en
34440 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 64 61 coding of the da
34450 74 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 tabase..*/.int s
34460 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
34470 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 llation(. sqlit
34480 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 e3*, . const ch
34490 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e ar *zName, . in
344a0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 t eTextRep, . v
344b0 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f oid*,. int(*xCo
344c0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 mpare)(void*,int
344d0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 ,const void*,int
344e0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b ,const void*).);
344f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
34500 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
34510 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 (. sqlite3*, .
34520 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
34530 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 me, . int eText
34540 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 Rep, . void*,.
34550 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 int(*xCompare)(
34560 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
34570 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
34580 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a void*),. void(*
34590 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 xDestroy)(void*)
345a0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
345b0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
345c0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 16(. sqlite3*,
345d0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a . const void *z
345e0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 Name,. int eTex
345f0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a tRep, . void*,.
34600 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 int(*xCompare)
34610 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
34620 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 void*,int,const
34630 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a void*).);../*.*
34640 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c * CAPI3REF: Coll
34650 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c ation Needed Cal
34660 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 lbacks {H16700}
34670 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S20300>.**.** T
34680 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 o avoid having t
34690 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 o register all c
346a0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
346b0 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 es before a data
346c0 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 base.** can be u
346d0 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 sed, a single ca
346e0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
346f0 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 may be registere
34700 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 d with the.** [d
34710 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
34720 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 on] to be called
34730 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 whenever an und
34740 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e efined collation
34750 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 .** sequence is
34760 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
34770 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 If the function
34780 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 is registered us
34790 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
347a0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
347b0 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 () API,.** then
347c0 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 it is passed the
347d0 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 names of undefi
347e0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 ned collation se
347f0 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e quences as strin
34800 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e gs.** encoded in
34810 20 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d UTF-8. {H16703}
34820 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c If sqlite3_coll
34830 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 ation_needed16()
34840 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 is used,.** the
34850 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 names are passe
34860 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d d as UTF-16 in m
34870 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 achine native by
34880 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 te order..** A c
34890 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 all to either fu
348a0 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 nction replaces
348b0 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c any existing cal
348c0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 lback..**.** Whe
348d0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 n the callback i
348e0 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 s invoked, the f
348f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 irst argument pa
34900 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a ssed is a copy.*
34910 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 * of the second
34920 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
34930 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
34940 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c eded() or.** sql
34950 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
34960 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 eeded16(). The
34970 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
34980 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a is the database.
34990 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 ** connection.
349a0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
349b0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 nt is one of [SQ
349c0 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c LITE_UTF8], [SQL
349d0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a ITE_UTF16BE],.**
349e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 or [SQLITE_UTF1
349f0 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 6LE], indicating
34a00 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 the most desira
34a10 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 ble form of the
34a20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 collation.** seq
34a30 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 uence function r
34a40 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f equired. The fo
34a50 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
34a60 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
34a70 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f e.** required co
34a80 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
34a90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c ..**.** The call
34aa0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 back function sh
34ab0 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 ould register th
34ac0 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 e desired collat
34ad0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ion using.** [sq
34ae0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
34af0 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 lation()], [sqli
34b00 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
34b10 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a tion16()], or.**
34b20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
34b30 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d _collation_v2()]
34b40 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
34b50 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 TS:.**.** {H1670
34b60 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 2} A successful
34b70 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
34b80 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 _collation_neede
34b90 64 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 d(D,P,F)].**
34ba0 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 or [sqlite
34bb0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
34bc0 65 64 31 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 ed16(D,P,F)] cau
34bd0 73 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ses.**
34be0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
34bf0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 nnection] D to i
34c00 6e 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 nvoke callback F
34c10 20 77 69 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 with first.**
34c20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 paramete
34c30 72 20 50 20 77 68 65 6e 65 76 65 72 20 69 74 20 r P whenever it
34c40 6e 65 65 64 73 20 61 20 63 6f 6d 70 61 72 69 73 needs a comparis
34c50 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 on function for
34c60 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f a.** co
34c70 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 llating sequence
34c80 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f that it does no
34c90 74 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a t know about..**
34ca0 0a 2a 2a 20 7b 48 31 36 37 30 34 7d 20 45 61 63 .** {H16704} Eac
34cb0 68 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c h successful cal
34cc0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f l to [sqlite3_co
34cd0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 llation_needed()
34ce0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 ] or.**
34cf0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 [sqlite3_collat
34d00 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 ion_needed16()]
34d10 6f 76 65 72 72 69 64 65 73 20 74 68 65 20 63 61 overrides the ca
34d20 6c 6c 62 61 63 6b 20 72 65 67 69 73 74 65 72 65 llback registere
34d30 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e d.** on
34d40 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 the same [datab
34d50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
34d60 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 by prior calls t
34d70 6f 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 o either.**
34d80 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 2e 0a interface..
34d90 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 36 7d 20 54 **.** {H16706} T
34da0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 he name of the r
34db0 65 71 75 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 equested collati
34dc0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 ng function pass
34dd0 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 ed in the.**
34de0 20 20 20 20 20 20 34 74 68 20 70 61 72 61 6d 65 4th parame
34df0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 ter to the callb
34e00 61 63 6b 20 69 73 20 69 6e 20 55 54 46 2d 38 20 ack is in UTF-8
34e10 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a if the callback.
34e20 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61 73 20 ** was
34e30 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 registered using
34e40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 [sqlite3_collat
34e50 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e ion_needed()] an
34e60 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 d.** is
34e70 20 69 6e 20 55 54 46 2d 31 36 20 6e 61 74 69 76 in UTF-16 nativ
34e80 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 e byte order if
34e90 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 the callback was
34ea0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 .** reg
34eb0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 istered using [s
34ec0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
34ed0 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f _needed16()]..*/
34ee0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
34ef0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 lation_needed(.
34f00 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f sqlite3*, . vo
34f10 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 id*, . void(*)(
34f20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 void*,sqlite3*,i
34f30 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 nt eTextRep,cons
34f40 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 t char*).);.int
34f50 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
34f60 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 n_needed16(. sq
34f70 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a lite3*, . void*
34f80 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 ,. void(*)(void
34f90 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 *,sqlite3*,int e
34fa0 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f TextRep,const vo
34fb0 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 id*).);../*.** S
34fc0 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 pecify the key f
34fd0 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 or an encrypted
34fe0 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 database. This
34ff0 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 routine should b
35000 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 e.** called righ
35010 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f t after sqlite3_
35020 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 open()..**.** Th
35030 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d e code to implem
35040 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 ent this API is
35050 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e not available in
35060 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 the public rele
35070 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 ase.** of SQLite
35080 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
35090 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 _key(. sqlite3
350a0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
350b0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
350c0 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 se to be rekeyed
350d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
350e0 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 *pKey, int nKey
350f0 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 /* The key
35100 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 */.);../*.** Cha
35110 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 nge the key on a
35120 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e n open database.
35130 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 If the current
35140 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 database is not
35150 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 .** encrypted, t
35160 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c his routine will
35170 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 encrypt it. If
35180 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 pNew==0 or nNew
35190 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 ==0, the.** data
351a0 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 base is decrypte
351b0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 d..**.** The cod
351c0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 e to implement t
351d0 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 his API is not a
351e0 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 vailable in the
351f0 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a public release.*
35200 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a * of SQLite..*/.
35210 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 int sqlite3_reke
35220 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 y(. sqlite3 *db
35230 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
35240 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
35250 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f to be rekeyed */
35260 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 . const void *p
35270 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 Key, int nKey
35280 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 /* The new key
35290 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
352a0 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 PI3REF: Suspend
352b0 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 Execution For A
352c0 53 68 6f 72 74 20 54 69 6d 65 20 7b 48 31 30 35 Short Time {H105
352d0 33 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 30} <S40410>.**.
352e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 ** The sqlite3_s
352f0 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 leep() function
35300 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 causes the curre
35310 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 nt thread to sus
35320 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a pend execution.*
35330 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 * for at least a
35340 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 number of milli
35350 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 seconds specifie
35360 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 d in its paramet
35370 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 er..**.** If the
35380 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
35390 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f m does not suppo
353a0 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 rt sleep request
353b0 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 s with.** millis
353c0 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c econd time resol
353d0 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 ution, then the
353e0 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 time will be rou
353f0 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 nded up to.** th
35400 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 e nearest second
35410 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 . The number of
35420 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 milliseconds of
35430 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a sleep actually.*
35440 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d * requested from
35450 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
35460 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 ystem is returne
35470 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 d..**.** SQLite
35480 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 implements this
35490 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c interface by cal
354a0 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 ling the xSleep(
354b0 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 ).** method of t
354c0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 he default [sqli
354d0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
354e0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
354f0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 33 S:.**.** {H10533
35500 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 } The [sqlite3_s
35510 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 leep(M)] interfa
35520 63 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 ce invokes the x
35530 53 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20 20 20 Sleep.**
35540 20 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 method of the
35550 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
35560 5f 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64 _vfs|VFS] in ord
35570 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 er to.**
35580 20 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 suspend execut
35590 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 ion of the curre
355a0 6e 74 20 74 68 72 65 61 64 20 66 6f 72 20 61 74 nt thread for at
355b0 20 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 least.**
355c0 20 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 M millisecond
355d0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 36 s..**.** {H10536
355e0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 } The [sqlite3_s
355f0 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 leep(M)] interfa
35600 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ce returns the n
35610 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 umber of.**
35620 20 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 millisecond
35630 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 s of sleep actua
35640 6c 6c 79 20 72 65 71 75 65 73 74 65 64 20 6f 66 lly requested of
35650 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a the operating.*
35660 2a 20 20 20 20 20 20 20 20 20 20 73 79 73 74 65 * syste
35670 6d 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 m, which might b
35680 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 e larger than th
35690 65 20 70 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a e parameter M..*
356a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c /.int sqlite3_sl
356b0 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a eep(int);../*.**
356c0 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 CAPI3REF: Name
356d0 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f Of The Folder Ho
356e0 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 lding Temporary
356f0 46 69 6c 65 73 20 7b 48 31 30 33 31 30 7d 20 3c Files {H10310} <
35700 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 S20000>.**.** If
35710 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 this global var
35720 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f iable is made to
35730 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 point to a stri
35740 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 ng which is.** t
35750 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c he name of a fol
35760 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 der (a.k.a. dire
35770 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c ctory), then all
35780 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 temporary files
35790 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 .** created by S
357a0 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c QLite will be pl
357b0 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 aced in that dir
357c0 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 ectory. If this
357d0 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 variable.** is
357e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
357f0 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 then SQLite perf
35800 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f orms a search fo
35810 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 r an appropriate
35820 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 .** temporary fi
35830 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a le directory..**
35840 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 .** It is not sa
35850 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 69 fe to modify thi
35860 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63 65 20 s variable once
35870 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
35880 65 63 74 69 6f 6e 5d 0a 2a 2a 20 68 61 73 20 62 ection].** has b
35890 65 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 een opened. It
358a0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 is intended that
358b0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 this variable b
358c0 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 e set once.** as
358d0 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 part of process
358e0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
358f0 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 and before any S
35900 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a QLite interface.
35910 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 ** routines have
35920 20 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 been call and r
35930 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 emain unchanged
35940 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 thereafter..*/.S
35950 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 QLITE_EXTERN cha
35960 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f r *sqlite3_temp_
35970 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a directory;../*.*
35980 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 * CAPI3REF: Test
35990 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 For Auto-Commit
359a0 20 4d 6f 64 65 20 7b 48 31 32 39 33 30 7d 20 3c Mode {H12930} <
359b0 53 36 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S60200>.** KEYWO
359c0 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 RDS: {autocommit
359d0 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 mode}.**.** The
359e0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 sqlite3_get_aut
359f0 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 ocommit() interf
35a00 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ace returns non-
35a10 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 zero or.** zero
35a20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 if the given dat
35a30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
35a40 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e is or is not in
35a50 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 autocommit mode
35a60 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c ,.** respectivel
35a70 79 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d y. Autocommit m
35a80 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 ode is on by def
35a90 61 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d ault..** Autocom
35aa0 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 mit mode is disa
35ab0 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e bled by a [BEGIN
35ac0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 ] statement..**
35ad0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 Autocommit mode
35ae0 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 is re-enabled by
35af0 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b a [COMMIT] or [
35b00 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a ROLLBACK]..**.**
35b10 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 If certain kind
35b20 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 s of errors occu
35b30 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 r on a statement
35b40 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d within a multi-
35b50 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 statement.** tra
35b60 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 nsaction (errors
35b70 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 including [SQLI
35b80 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 TE_FULL], [SQLIT
35b90 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 E_IOERR],.** [SQ
35ba0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 LITE_NOMEM], [SQ
35bb0 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 LITE_BUSY], and
35bc0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 [SQLITE_INTERRUP
35bd0 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 T]) then the.**
35be0 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 transaction migh
35bf0 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b t be rolled back
35c00 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 automatically.
35c10 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f The only way to
35c20 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 .** find out whe
35c30 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f ther SQLite auto
35c40 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 matically rolled
35c50 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 back the transa
35c60 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 ction after.** a
35c70 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 n error is to us
35c80 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e e this function.
35c90 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
35ca0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 31 S:.**.** {H12931
35cb0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 } The [sqlite3_g
35cc0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 44 29 et_autocommit(D)
35cd0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
35ce0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a rns non-zero or.
35cf0 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f ** zero
35d00 20 69 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 if the [databas
35d10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 e connection] D
35d20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 is or is not in
35d30 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20 autocommit.**
35d40 20 20 20 20 20 20 20 6d 6f 64 65 2c 20 72 65 73 mode, res
35d50 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a pectively..**.**
35d60 20 7b 48 31 32 39 33 32 7d 20 41 75 74 6f 63 6f {H12932} Autoco
35d70 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 mmit mode is on
35d80 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a by default..**.*
35d90 2a 20 7b 48 31 32 39 33 33 7d 20 41 75 74 6f 63 * {H12933} Autoc
35da0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 ommit mode is di
35db0 73 61 62 6c 65 64 20 62 79 20 61 20 73 75 63 63 sabled by a succ
35dc0 65 73 73 66 75 6c 20 5b 42 45 47 49 4e 5d 20 73 essful [BEGIN] s
35dd0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 tatement..**.**
35de0 7b 48 31 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d {H12934} Autocom
35df0 6d 69 74 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 mit mode is enab
35e00 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73 led by a success
35e10 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 ful [COMMIT] or
35e20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20 [ROLLBACK].**
35e30 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 statement
35e40 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 ..**.** ASSUMPTI
35e50 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 39 ONS:.**.** {A129
35e60 33 36 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74 36} If another t
35e70 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 hread changes th
35e80 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 e autocommit sta
35e90 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 tus of the datab
35ea0 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ase.**
35eb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 connection while
35ec0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
35ed0 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 running, then t
35ee0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a he return value.
35ef0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 75 ** is u
35f00 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 ndefined..*/.int
35f10 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 sqlite3_get_aut
35f20 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a ocommit(sqlite3*
35f30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
35f40 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 EF: Find The Dat
35f50 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 abase Handle Of
35f60 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
35f70 6d 65 6e 74 20 7b 48 31 33 31 32 30 7d 20 3c 53 ment {H13120} <S
35f80 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 60600>.**.** The
35f90 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 sqlite3_db_hand
35fa0 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 le interface ret
35fb0 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 urns the [databa
35fc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 se connection] h
35fd0 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 andle.** to whic
35fe0 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 h a [prepared st
35ff0 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 atement] belongs
36000 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 . The database
36010 68 61 6e 64 6c 65 20 72 65 74 75 72 6e 65 64 20 handle returned
36020 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 by.** sqlite3_db
36030 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 _handle is the s
36040 61 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 6e ame database han
36050 64 6c 65 20 74 68 61 74 20 77 61 73 20 74 68 65 dle that was the
36060 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a first argument.
36070 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 ** to the [sqlit
36080 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
36090 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 call (or its va
360a0 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 riants) that was
360b0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 used to.** crea
360c0 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 te the statement
360d0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c in the first pl
360e0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ace..**.** INVAR
360f0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
36100 33 31 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 3123} The [sqlit
36110 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 53 29 5d e3_db_handle(S)]
36120 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
36130 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 ns a pointer.**
36140 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 to the
36150 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
36160 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 tion] associated
36170 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 20 20 20 with the.**
36180 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 [prepared
36190 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f statement] S..*/
361a0 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 .sqlite3 *sqlite
361b0 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 3_db_handle(sqli
361c0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
361d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e ** CAPI3REF: Fin
361e0 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 d the next prepa
361f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 7b 48 red statement {H
36200 31 33 31 34 30 7d 20 3c 53 36 30 36 30 30 3e 0a 13140} <S60600>.
36210 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
36220 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
36230 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 ointer to the ne
36240 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 xt [prepared sta
36250 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a tement] after.**
36260 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 pStmt associate
36270 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 d with the [data
36280 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
36290 20 70 44 62 2e 20 20 49 66 20 70 53 74 6d 74 20 pDb. If pStmt
362a0 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 is NULL.** then
362b0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 this interface r
362c0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
362d0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 to the first pr
362e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
362f0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 .** associated w
36300 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 ith the database
36310 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e connection pDb.
36320 20 20 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 If no prepared
36330 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 statement.** sa
36340 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 tisfies the cond
36350 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 itions of this r
36360 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 outine, it retur
36370 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 ns NULL..**.** I
36380 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
36390 20 7b 48 31 33 31 34 33 7d 20 49 66 20 44 20 69 {H13143} If D i
363a0 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f s a [database co
363b0 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 nnection] that h
363c0 6f 6c 64 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 olds one or more
363d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 66 .** unf
363e0 69 6e 61 6c 69 7a 65 64 20 5b 70 72 65 70 61 72 inalized [prepar
363f0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 ed statements] a
36400 6e 64 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 nd S is a NULL p
36410 6f 69 6e 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20 ointer,.**
36420 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 then [sqlite
36430 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 3_next_stmt(D, S
36440 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c )] routine shall
36450 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 return a pointe
36460 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f r.** to
36470 20 6f 6e 65 20 6f 66 20 74 68 65 20 70 72 65 70 one of the prep
36480 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 ared statements
36490 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
364a0 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 36 D..**.** {H13146
364b0 7d 20 49 66 20 44 20 69 73 20 61 20 5b 64 61 74 } If D is a [dat
364c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
364d0 5d 20 74 68 61 74 20 68 6f 6c 64 73 20 6e 6f 20 ] that holds no
364e0 75 6e 66 69 6e 61 6c 69 7a 65 64 0a 2a 2a 20 20 unfinalized.**
364f0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 [prepare
36500 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e d statements] an
36510 64 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f d S is a NULL po
36520 69 6e 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 inter, then.**
36530 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
36540 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 _next_stmt(D, S)
36550 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 ] routine shall
36560 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f return a NULL po
36570 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 inter..**.** {H1
36580 33 31 34 39 7d 20 49 66 20 53 20 69 73 20 61 20 3149} If S is a
36590 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
365a0 65 6e 74 5d 20 69 6e 20 74 68 65 20 5b 64 61 74 ent] in the [dat
365b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
365c0 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ] D.**
365d0 61 6e 64 20 53 20 69 73 20 6e 6f 74 20 74 68 65 and S is not the
365e0 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73 last prepared s
365f0 74 61 74 65 6d 65 6e 74 20 69 6e 20 44 2c 20 74 tatement in D, t
36600 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hen.**
36610 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 [sqlite3_next_st
36620 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e mt(D, S)] routin
36630 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 e shall return a
36640 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 pointer.**
36650 20 20 20 20 20 74 6f 20 74 68 65 20 6e 65 78 74 to the next
36660 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
36670 65 6e 74 20 69 6e 20 44 20 61 66 74 65 72 20 53 ent in D after S
36680 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 35 32 7d ..**.** {H13152}
36690 20 49 66 20 53 20 69 73 20 74 68 65 20 6c 61 73 If S is the las
366a0 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 t [prepared stat
366b0 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65 0a 2a 2a ement] in the.**
366c0 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 [datab
366d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
366e0 44 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 D then the [sqli
366f0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c te3_next_stmt(D,
36700 20 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 S)].**
36710 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 routine shall r
36720 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 eturn a NULL poi
36730 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 nter..**.** ASSU
36740 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b MPTIONS:.**.** {
36750 41 31 33 31 35 34 7d 20 54 68 65 20 5b 64 61 74 A13154} The [dat
36760 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
36770 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 ] pointer D in a
36780 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 call to.**
36790 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 [sqlite3_ne
367a0 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 xt_stmt(D,S)] mu
367b0 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f st refer to an o
367c0 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 pen database.**
367d0 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 connect
367e0 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 ion and in parti
367f0 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 cular must not b
36800 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 e a NULL pointer
36810 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d ..*/.sqlite3_stm
36820 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f t *sqlite3_next_
36830 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 stmt(sqlite3 *pD
36840 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 b, sqlite3_stmt
36850 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
36860 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 CAPI3REF: Commit
36870 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f And Rollback No
36880 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 tification Callb
36890 61 63 6b 73 20 7b 48 31 32 39 35 30 7d 20 3c 53 acks {H12950} <S
368a0 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 60400>.**.** The
368b0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f sqlite3_commit_
368c0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 hook() interface
368d0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c registers a cal
368e0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f lback.** functio
368f0 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 n to be invoked
36900 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 whenever a trans
36910 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 action is commit
36920 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c ted..** Any call
36930 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 back set by a pr
36940 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 evious call to s
36950 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f qlite3_commit_ho
36960 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 ok().** for the
36970 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f same database co
36980 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 nnection is over
36990 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 ridden..** The s
369a0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f qlite3_rollback_
369b0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 hook() interface
369c0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c registers a cal
369d0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f lback.** functio
369e0 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 n to be invoked
369f0 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 whenever a trans
36a00 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 action is commit
36a10 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c ted..** Any call
36a20 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 back set by a pr
36a30 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 evious call to s
36a40 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f qlite3_commit_ho
36a50 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 ok().** for the
36a60 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f same database co
36a70 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 nnection is over
36a80 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 ridden..** The p
36a90 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 Arg argument is
36aa0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 passed through t
36ab0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a o the callback..
36ac0 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 ** If the callba
36ad0 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 ck on a commit h
36ae0 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 ook function ret
36af0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a urns non-zero,.*
36b00 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 * then the commi
36b10 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 t is converted i
36b20 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a nto a rollback..
36b30 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 **.** If another
36b40 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 function was pr
36b50 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 eviously registe
36b60 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 red, its.** pArg
36b70 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e value is return
36b80 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e ed. Otherwise N
36b90 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e ULL is returned.
36ba0 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 .**.** Registeri
36bb0 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 ng a NULL functi
36bc0 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 on disables the
36bd0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 callback..**.**
36be0 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 For the purposes
36bf0 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 of this API, a
36c00 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 transaction is s
36c10 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e aid to have been
36c20 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 .** rolled back
36c30 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 if an explicit "
36c40 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d ROLLBACK" statem
36c50 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c ent is executed,
36c60 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 or.** an error
36c70 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 or constraint ca
36c80 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 uses an implicit
36c90 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 rollback to occ
36ca0 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 ur..** The rollb
36cb0 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ack callback is
36cc0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 not invoked if a
36cd0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a transaction is.
36ce0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ** automatically
36cf0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 rolled back bec
36d00 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73 ause the databas
36d10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
36d20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72 closed..** The r
36d30 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b ollback callback
36d40 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 is not invoked
36d50 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e if a transaction
36d60 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 is.** rolled ba
36d70 63 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d ck because a com
36d80 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 mit callback ret
36d90 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a urned non-zero..
36da0 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20 ** <todo> Check
36db0 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a on this </todo>.
36dc0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
36dd0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 31 7d :.**.** {H12951}
36de0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f The [sqlite3_co
36df0 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 mmit_hook(D,F,P)
36e00 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ] interface regi
36e10 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 sters the.**
36e20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 callback f
36e30 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 unction F to be
36e40 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 invoked with arg
36e50 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 ument P whenever
36e60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 .** a t
36e70 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 ransaction commi
36e80 74 73 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 ts on the [datab
36e90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
36ea0 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 32 D..**.** {H12952
36eb0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
36ec0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 ommit_hook(D,F,P
36ed0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
36ee0 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d urns the P argum
36ef0 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ent.**
36f00 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 from the previou
36f10 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20 s call with the
36f20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 same [database c
36f30 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a onnection] D,.**
36f40 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c or NUL
36f50 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 63 L on the first c
36f60 61 6c 6c 20 66 6f 72 20 61 20 70 61 72 74 69 63 all for a partic
36f70 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 63 6f ular database co
36f80 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a nnection D..**.*
36f90 2a 20 7b 48 31 32 39 35 33 7d 20 45 61 63 68 20 * {H12953} Each
36fa0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
36fb0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 _commit_hook()]
36fc0 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20 63 overwrites the c
36fd0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 allback.**
36fe0 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 62 registered b
36ff0 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a y prior calls..*
37000 2a 0a 2a 2a 20 7b 48 31 32 39 35 34 7d 20 49 66 *.** {H12954} If
37010 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20 the F argument
37020 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d to [sqlite3_comm
37030 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 it_hook(D,F,P)]
37040 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 is NULL.**
37050 20 20 20 20 74 68 65 6e 20 74 68 65 20 63 6f 6d then the com
37060 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 mit hook callbac
37070 6b 20 69 73 20 63 61 6e 63 65 6c 65 64 20 61 6e k is canceled an
37080 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a d no callback.**
37090 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 is inv
370a0 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e oked when a tran
370b0 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e saction commits.
370c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 35 7d 20 .**.** {H12955}
370d0 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 63 61 If the commit ca
370e0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e llback returns n
370f0 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 on-zero then the
37100 20 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a 20 20 20 commit is.**
37110 20 20 20 20 20 20 20 63 6f 6e 76 65 72 74 65 64 converted
37120 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b into a rollback
37130 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 31 7d ..**.** {H12961}
37140 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f The [sqlite3_ro
37150 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c llback_hook(D,F,
37160 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 P)] interface re
37170 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 gisters the.**
37180 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b callback
37190 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 function F to b
371a0 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 e invoked with a
371b0 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 rgument P whenev
371c0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 er.** a
371d0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c transaction rol
371e0 6c 73 20 62 61 63 6b 20 6f 6e 20 74 68 65 20 5b ls back on the [
371f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
37200 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ion] D..**.** {H
37210 31 32 39 36 32 7d 20 54 68 65 20 5b 73 71 6c 69 12962} The [sqli
37220 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f te3_rollback_hoo
37230 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 k(D,F,P)] interf
37240 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
37250 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 P.** ar
37260 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 gument from the
37270 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 previous call wi
37280 74 68 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 th the same.**
37290 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 [databas
372a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c e connection] D,
372b0 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 or NULL on the
372c0 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 first call.**
372d0 20 20 20 20 20 20 20 66 6f 72 20 61 20 70 61 72 for a par
372e0 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 ticular database
372f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a connection D..*
37300 2a 0a 2a 2a 20 7b 48 31 32 39 36 33 7d 20 45 61 *.** {H12963} Ea
37310 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ch call to [sqli
37320 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f te3_rollback_hoo
37330 6b 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 k()] overwrites
37340 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 the callback.**
37350 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 registe
37360 72 65 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c red by prior cal
37370 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 ls..**.** {H1296
37380 34 7d 20 49 66 20 74 68 65 20 46 20 61 72 67 75 4} If the F argu
37390 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
373a0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 _rollback_hook(D
373b0 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a ,F,P)] is NULL.*
373c0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 * then
373d0 74 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f the rollback hoo
373e0 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 k callback is ca
373f0 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 nceled and no ca
37400 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 llback.**
37410 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 is invoked wh
37420 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e en a transaction
37430 20 72 6f 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a rolls back..*/.
37440 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
37450 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 mmit_hook(sqlite
37460 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 3*, int(*)(void*
37470 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 ), void*);.void
37480 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 *sqlite3_rollbac
37490 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c k_hook(sqlite3*,
374a0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 void(*)(void *)
374b0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a , void*);../*.**
374c0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 CAPI3REF: Data
374d0 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 Change Notificat
374e0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 ion Callbacks {H
374f0 31 32 39 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a 12970} <S60400>.
37500 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
37510 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 3_update_hook()
37520 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
37530 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ers a callback f
37540 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 unction.** with
37550 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
37560 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 nnection] identi
37570 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 fied by the firs
37580 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f t argument.** to
37590 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e be invoked when
375a0 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 ever a row is up
375b0 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 dated, inserted
375c0 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 or deleted..** A
375d0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 ny callback set
375e0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 by a previous ca
375f0 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 ll to this funct
37600 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 ion.** for the s
37610 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
37620 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 nection is overr
37630 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 idden..**.** The
37640 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
37650 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
37660 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f the function to
37670 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a invoke when a.*
37680 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 * row is updated
37690 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 , inserted or de
376a0 6c 65 74 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69 leted..** The fi
376b0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
376c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 the callback is
376d0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 a copy of the th
376e0 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 ird argument.**
376f0 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 to sqlite3_updat
37700 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 e_hook()..** The
37710 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b second callback
37720 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 argument is one
37730 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 of [SQLITE_INSE
37740 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c RT], [SQLITE_DEL
37750 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c ETE],.** or [SQL
37760 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 ITE_UPDATE], dep
37770 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 ending on the op
37780 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 eration that cau
37790 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b sed the callback
377a0 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 .** to be invoke
377b0 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 d..** The third
377c0 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d and fourth argum
377d0 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c ents to the call
377e0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 back contain poi
377f0 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 nters to the.**
37800 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 database and tab
37810 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 le name containi
37820 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20 ng the affected
37830 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 row..** The fina
37840 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d l callback param
37850 65 74 65 72 20 69 73 20 74 68 65 20 72 6f 77 69 eter is the rowi
37860 64 20 6f 66 20 74 68 65 20 72 6f 77 2e 20 49 6e d of the row. In
37870 20 74 68 65 20 63 61 73 65 20 6f 66 0a 2a 2a 20 the case of.**
37880 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 an update, this
37890 69 73 20 74 68 65 20 72 6f 77 69 64 20 61 66 74 is the rowid aft
378a0 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61 er the update ta
378b0 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a kes place..**.**
378c0 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b The update hook
378d0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 is not invoked
378e0 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 when internal sy
378f0 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a stem tables are.
37900 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 ** modified (i.e
37910 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 . sqlite_master
37920 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 and sqlite_seque
37930 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 nce)..**.** If a
37940 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 nother function
37950 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 was previously r
37960 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 egistered, its p
37970 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 Arg value.** is
37980 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 returned. Other
37990 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 wise NULL is ret
379a0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 urned..**.** INV
379b0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
379c0 48 31 32 39 37 31 7d 20 54 68 65 20 5b 73 71 6c H12971} The [sql
379d0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b ite3_update_hook
379e0 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 (D,F,P)] interfa
379f0 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 ce causes the ca
37a00 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 llback.**
37a10 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f function F to
37a20 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 be invoked with
37a30 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
37a40 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 P whenever.**
37a50 20 20 20 20 20 20 20 20 61 20 74 61 62 6c 65 20 a table
37a60 72 6f 77 20 69 73 20 6d 6f 64 69 66 69 65 64 2c row is modified,
37a70 20 69 6e 73 65 72 74 65 64 2c 20 6f 72 20 64 65 inserted, or de
37a80 6c 65 74 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 leted on.**
37a90 20 20 20 20 20 74 68 65 20 5b 64 61 74 61 62 61 the [databa
37aa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
37ab0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 33 7d ..**.** {H12973}
37ac0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 The [sqlite3_up
37ad0 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 date_hook(D,F,P)
37ae0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
37af0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a rns the value.**
37b00 20 20 20 20 20 20 20 20 20 20 6f 66 20 50 20 66 of P f
37b10 6f 72 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 or the previous
37b20 63 61 6c 6c 20 6f 6e 20 74 68 65 20 73 61 6d 65 call on the same
37b30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
37b40 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 ction] D,.**
37b50 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 66 6f or NULL fo
37b60 72 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c r the first call
37b70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 35 7d ..**.** {H12975}
37b80 20 49 66 20 74 68 65 20 75 70 64 61 74 65 20 68 If the update h
37b90 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 46 20 69 ook callback F i
37ba0 6e 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 n [sqlite3_updat
37bb0 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 0a 2a e_hook(D,F,P)].*
37bc0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 4e 55 * is NU
37bd0 4c 4c 20 74 68 65 6e 20 74 68 65 20 6e 6f 20 75 LL then the no u
37be0 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 73 20 pdate callbacks
37bf0 61 72 65 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 are made..**.**
37c00 7b 48 31 32 39 37 37 7d 20 45 61 63 68 20 63 61 {H12977} Each ca
37c10 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 75 ll to [sqlite3_u
37c20 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 pdate_hook(D,F,P
37c30 29 5d 20 6f 76 65 72 72 69 64 65 73 20 70 72 69 )] overrides pri
37c40 6f 72 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 or calls.**
37c50 20 20 20 20 20 74 6f 20 74 68 65 20 73 61 6d 65 to the same
37c60 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 20 74 68 interface on th
37c70 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 e same [database
37c80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a connection] D..
37c90 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 39 7d 20 54 **.** {H12979} T
37ca0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 he update hook c
37cb0 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 allback is not i
37cc0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 nvoked when inte
37cd0 72 6e 61 6c 20 73 79 73 74 65 6d 0a 2a 2a 20 20 rnal system.**
37ce0 20 20 20 20 20 20 20 20 74 61 62 6c 65 73 20 73 tables s
37cf0 75 63 68 20 61 73 20 73 71 6c 69 74 65 5f 6d 61 uch as sqlite_ma
37d00 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f ster and sqlite_
37d10 73 65 71 75 65 6e 63 65 20 61 72 65 20 6d 6f 64 sequence are mod
37d20 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ified..**.** {H1
37d30 32 39 38 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 2981} The second
37d40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
37d50 65 20 75 70 64 61 74 65 20 63 61 6c 6c 62 61 63 e update callbac
37d60 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 k.** is
37d70 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
37d80 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 INSERT], [SQLITE
37d90 5f 44 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c _DELETE] or [SQL
37da0 49 54 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 ITE_UPDATE],.**
37db0 20 20 20 20 20 20 20 20 20 64 65 70 65 6e 64 69 dependi
37dc0 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 ng on the operat
37dd0 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 ion that caused
37de0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 the callback to
37df0 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a be invoked..**.*
37e00 2a 20 7b 48 31 32 39 38 33 7d 20 54 68 65 20 74 * {H12983} The t
37e10 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 hird and fourth
37e20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 arguments to the
37e30 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 callback contai
37e40 6e 20 70 6f 69 6e 74 65 72 73 0a 2a 2a 20 20 20 n pointers.**
37e50 20 20 20 20 20 20 20 74 6f 20 7a 65 72 6f 2d 74 to zero-t
37e60 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 erminated UTF-8
37e70 73 74 72 69 6e 67 73 20 77 68 69 63 68 20 61 72 strings which ar
37e80 65 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 e the names of t
37e90 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 he.** d
37ea0 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c atabase and tabl
37eb0 65 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 e that is being
37ec0 75 70 64 61 74 65 64 2e 0a 0a 2a 2a 20 7b 48 31 updated...** {H1
37ed0 32 39 38 35 7d 20 54 68 65 20 66 69 6e 61 6c 20 2985} The final
37ee0 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 callback paramet
37ef0 65 72 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 er is the rowid
37f00 6f 66 20 74 68 65 20 72 6f 77 20 61 66 74 65 72 of the row after
37f10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
37f20 20 63 68 61 6e 67 65 20 6f 63 63 75 72 73 2e 0a change occurs..
37f30 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 */.void *sqlite3
37f40 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 _update_hook(.
37f50 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 sqlite3*, . voi
37f60 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 d(*)(void *,int
37f70 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 ,char const *,ch
37f80 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 ar const *,sqlit
37f90 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 e3_int64),. voi
37fa0 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 d*.);../*.** CAP
37fb0 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 I3REF: Enable Or
37fc0 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 Disable Shared
37fd0 50 61 67 65 72 20 43 61 63 68 65 20 7b 48 31 30 Pager Cache {H10
37fe0 33 33 30 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a 330} <S30900>.**
37ff0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 KEYWORDS: {shar
38000 65 64 20 63 61 63 68 65 7d 20 7b 73 68 61 72 65 ed cache} {share
38010 64 20 63 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a d cache mode}.**
38020 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
38030 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 enables or disa
38040 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 bles the sharing
38050 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
38060 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 cache.** and sc
38070 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 hema data struct
38080 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 ures between [da
38090 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
380a0 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d n | connections]
380b0 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 .** to the same
380c0 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e database. Sharin
380d0 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 g is enabled if
380e0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 the argument is
380f0 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 true.** and disa
38100 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 bled if the argu
38110 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a ment is false..*
38120 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 *.** Cache shari
38130 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e ng is enabled an
38140 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 d disabled for a
38150 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 n entire process
38160 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 69 73 20 . {END}.** This
38170 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f is a change as o
38180 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e f SQLite version
38190 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 3.5.0. In prior
381a0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
381b0 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 ite,.** sharing
381c0 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 was enabled or d
381d0 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 isabled for each
381e0 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65 thread separate
381f0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 ly..**.** The ca
38200 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 che sharing mode
38210 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 set by this int
38220 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61 erface effects a
38230 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a ll subsequent.**
38240 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
38250 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
38260 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c ite3_open_v2()],
38270 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 and [sqlite3_op
38280 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 en16()]..** Exis
38290 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f ting database co
382a0 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e nnections contin
382b0 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69 ue use the shari
382c0 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 ng mode.** that
382d0 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 was in effect at
382e0 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 the time they w
382f0 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a ere opened..**.*
38300 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 * Virtual tables
38310 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 cannot be used
38320 77 69 74 68 20 61 20 73 68 61 72 65 64 20 63 61 with a shared ca
38330 63 68 65 2e 20 20 57 68 65 6e 20 73 68 61 72 65 che. When share
38340 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e d.** cache is en
38350 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 abled, the [sqli
38360 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c te3_create_modul
38370 65 28 29 5d 20 41 50 49 20 75 73 65 64 20 74 6f e()] API used to
38380 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 register.** vir
38390 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c tual tables will
383a0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 always return a
383b0 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 n error..**.** T
383c0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
383d0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 rns [SQLITE_OK]
383e0 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20 if shared cache
383f0 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 was enabled or d
38400 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 isabled.** succe
38410 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 ssfully. An [er
38420 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 ror code] is ret
38430 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e urned otherwise.
38440 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 .**.** Shared ca
38450 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 che is disabled
38460 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 by default. But
38470 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 this might chang
38480 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 e in.** future r
38490 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
384a0 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 e. Applications
384b0 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 that care about
384c0 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 shared.** cache
384d0 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 setting should
384e0 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c set it explicitl
384f0 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 y..**.** INVARIA
38500 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 33 NTS:.**.** {H103
38510 33 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 31} A successful
38520 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b invocation of [
38530 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 sqlite3_enable_s
38540 68 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d 0a hared_cache(B)].
38550 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c ** will
38560 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 enable or disab
38570 6c 65 20 73 68 61 72 65 64 20 63 61 63 68 65 20 le shared cache
38580 6d 6f 64 65 20 66 6f 72 20 61 6e 79 20 73 75 62 mode for any sub
38590 73 65 71 75 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 sequently.**
385a0 20 20 20 20 20 20 63 72 65 61 74 65 64 20 5b 64 created [d
385b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
385c0 6f 6e 5d 20 69 6e 20 74 68 65 20 73 61 6d 65 20 on] in the same
385d0 70 72 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b process..**.** {
385e0 48 31 30 33 33 36 7d 20 57 68 65 6e 20 73 68 61 H10336} When sha
385f0 72 65 64 20 63 61 63 68 65 20 69 73 20 65 6e 61 red cache is ena
38600 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 bled, the [sqlit
38610 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 e3_create_module
38620 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ()].**
38630 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 61 interface will a
38640 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 lways return an
38650 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 error..**.** {H1
38660 30 33 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 0337} The [sqlit
38670 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 e3_enable_shared
38680 5f 63 61 63 68 65 28 42 29 5d 20 69 6e 74 65 72 _cache(B)] inter
38690 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 face returns.**
386a0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 [SQLITE
386b0 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 _OK] if shared c
386c0 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 ache was enabled
386d0 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75 63 or disabled suc
386e0 63 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a cessfully..**.**
386f0 20 7b 48 31 30 33 33 39 7d 20 53 68 61 72 65 64 {H10339} Shared
38700 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c cache is disabl
38710 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a ed by default..*
38720 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e /.int sqlite3_en
38730 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 able_shared_cach
38740 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 e(int);../*.** C
38750 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 API3REF: Attempt
38760 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 To Free Heap Me
38770 6d 6f 72 79 20 7b 48 31 37 33 34 30 7d 20 3c 53 mory {H17340} <S
38780 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 30220>.**.** The
38790 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 sqlite3_release
387a0 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 _memory() interf
387b0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ace attempts to
387c0 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 free N bytes.**
387d0 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 of heap memory b
387e0 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e y deallocating n
387f0 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d on-essential mem
38800 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a ory allocations.
38810 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 ** held by the d
38820 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e atabase library.
38830 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 {END} Memory u
38840 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 sed to cache dat
38850 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 abase.** pages t
38860 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 o improve perfor
38870 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d mance is an exam
38880 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e ple of non-essen
38890 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 tial memory..**
388a0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f sqlite3_release_
388b0 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 memory() returns
388c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
388d0 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 ytes actually fr
3