0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 ms copyright to
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a . In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d sing:.**.** M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 nd not evil..**
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 May you find
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 forgiveness for
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 give others..**
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 aking more than
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43 rograms. If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69 ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 s file, then it
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20 ite, is subject
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53 grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74 e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 erimental". Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64 s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20 to SQLite. We
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 e changes.** to
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65 erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20 r changes if.**
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20 experience from
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64 use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63 " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65 hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67 ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74 e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69 ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68 m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66 is file. This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65 ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61 suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 me of this file
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74 under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69 ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65 .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69 r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20 s file (such as
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65 inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29 version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73 and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65 name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20 3.h" as.** part
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29 cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e 69 $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 33 37 39 20 32 30 30 38 2f 30 n,v 1.379 2008/0
05f0: 37 2f 32 35 20 30 38 3a 34 39 3a 30 30 20 64 61 7/25 08:49:00 da
0600: 6e 69 65 6c 6b 31 39 37 37 20 45 78 70 20 24 0a nielk1977 Exp $.
0610: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49 */.#ifndef _SQLI
0620: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f TE3_H_.#define _
0630: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c SQLITE3_H_.#incl
0640: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 ude <stdarg.h>
0650: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 /* Needed for
0660: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 the definition
0670: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f of va_list */../
0680: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 *.** Make sure w
0690: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 e can call this
06a0: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a stuff from C++..
06b0: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 */.#ifdef __cplu
06c0: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22 splus.extern "C"
06d0: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a {.#endif.../*.*
06e0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74 * Add the abilit
06f0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65 y to override 'e
0700: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 xtern'.*/.#ifnde
0710: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a f SQLITE_EXTERN.
0720: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
0730: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 EXTERN extern.#e
0740: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 ndif../*.** Ensu
0750: 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 re these symbols
0760: 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 were not define
0770: 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f d by some previo
0780: 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a us header file..
0790: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 */.#ifdef SQLITE
07a0: 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 _VERSION.# undef
07b0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a SQLITE_VERSION.
07c0: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 #endif.#ifdef SQ
07d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
07e0: 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 BER.# undef SQLI
07f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
0800: 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 R.#endif../*.**
0810: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c CAPI3REF: Compil
0820: 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 e-Time Library V
0830: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b ersion Numbers {
0840: 48 31 30 30 31 30 7d 20 3c 53 36 30 31 30 30 3e H10010} <S60100>
0850: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 .**.** The SQLIT
0860: 45 5f 56 45 52 53 49 4f 4e 20 61 6e 64 20 53 51 E_VERSION and SQ
0870: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
0880: 42 45 52 20 23 64 65 66 69 6e 65 73 20 69 6e 0a BER #defines in.
0890: 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 ** the sqlite3.h
08a0: 20 66 69 6c 65 20 73 70 65 63 69 66 79 20 74 68 file specify th
08b0: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c e version of SQL
08c0: 69 74 65 20 77 69 74 68 20 77 68 69 63 68 0a 2a ite with which.*
08d0: 2a 20 74 68 61 74 20 68 65 61 64 65 72 20 66 69 * that header fi
08e0: 6c 65 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 le is associated
08f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 76 65 72 ..**.** The "ver
0900: 73 69 6f 6e 22 20 6f 66 20 53 51 4c 69 74 65 20 sion" of SQLite
0910: 69 73 20 61 20 73 74 72 69 6e 67 20 6f 66 20 74 is a string of t
0920: 68 65 20 66 6f 72 6d 20 22 58 2e 59 2e 5a 22 2e he form "X.Y.Z".
0930: 0a 2a 2a 20 54 68 65 20 70 68 72 61 73 65 20 22 .** The phrase "
0940: 61 6c 70 68 61 22 20 6f 72 20 22 62 65 74 61 22 alpha" or "beta"
0950: 20 6d 69 67 68 74 20 62 65 20 61 70 70 65 6e 64 might be append
0960: 65 64 20 61 66 74 65 72 20 74 68 65 20 5a 2e 0a ed after the Z..
0970: 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20 69 ** The X value i
0980: 73 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 s major version
0990: 6e 75 6d 62 65 72 20 61 6c 77 61 79 73 20 33 20 number always 3
09a0: 69 6e 20 53 51 4c 69 74 65 33 2e 0a 2a 2a 20 54 in SQLite3..** T
09b0: 68 65 20 58 20 76 61 6c 75 65 20 6f 6e 6c 79 20 he X value only
09c0: 63 68 61 6e 67 65 73 20 77 68 65 6e 20 62 61 63 changes when bac
09d0: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
09e0: 6c 69 74 79 20 69 73 0a 2a 2a 20 62 72 6f 6b 65 lity is.** broke
09f0: 6e 20 61 6e 64 20 77 65 20 69 6e 74 65 6e 64 20 n and we intend
0a00: 74 6f 20 6e 65 76 65 72 20 62 72 65 61 6b 20 62 to never break b
0a10: 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
0a20: 62 69 6c 69 74 79 2e 0a 2a 2a 20 54 68 65 20 59 bility..** The Y
0a30: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6d 69 value is the mi
0a40: 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 nor version numb
0a50: 65 72 20 61 6e 64 20 6f 6e 6c 79 20 63 68 61 6e er and only chan
0a60: 67 65 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65 72 ges when.** ther
0a70: 65 20 61 72 65 20 6d 61 6a 6f 72 20 66 65 61 74 e are major feat
0a80: 75 72 65 20 65 6e 68 61 6e 63 65 6d 65 6e 74 73 ure enhancements
0a90: 20 74 68 61 74 20 61 72 65 20 66 6f 72 77 61 72 that are forwar
0aa0: 64 73 20 63 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a ds compatible.**
0ab0: 20 62 75 74 20 6e 6f 74 20 62 61 63 6b 77 61 72 but not backwar
0ac0: 64 73 20 63 6f 6d 70 61 74 69 62 6c 65 2e 0a 2a ds compatible..*
0ad0: 2a 20 54 68 65 20 5a 20 76 61 6c 75 65 20 69 73 * The Z value is
0ae0: 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d the release num
0af0: 62 65 72 20 61 6e 64 20 69 73 20 69 6e 63 72 65 ber and is incre
0b00: 6d 65 6e 74 65 64 20 77 69 74 68 0a 2a 2a 20 65 mented with.** e
0b10: 61 63 68 20 72 65 6c 65 61 73 65 20 62 75 74 20 ach release but
0b20: 72 65 73 65 74 73 20 62 61 63 6b 20 74 6f 20 30 resets back to 0
0b30: 20 77 68 65 6e 65 76 65 72 20 59 20 69 73 20 69 whenever Y is i
0b40: 6e 63 72 65 6d 65 6e 74 65 64 2e 0a 2a 2a 0a 2a ncremented..**.*
0b50: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
0b60: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
0b70: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
0b80: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 libversion_numbe
0b90: 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 r()]..**.** INVA
0ba0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
0bb0: 31 30 30 31 31 7d 20 54 68 65 20 53 51 4c 49 54 10011} The SQLIT
0bc0: 45 5f 56 45 52 53 49 4f 4e 20 23 64 65 66 69 6e E_VERSION #defin
0bd0: 65 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 e in the sqlite3
0be0: 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 20 73 .h header file s
0bf0: 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 hall.**
0c00: 20 65 76 61 6c 75 61 74 65 20 74 6f 20 61 20 73 evaluate to a s
0c10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 tring literal th
0c20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 at is the SQLite
0c30: 20 76 65 72 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 version.**
0c40: 20 20 20 20 20 77 69 74 68 20 77 68 69 63 68 20 with which
0c50: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20 the header file
0c60: 69 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a is associated..*
0c70: 2a 0a 2a 2a 20 7b 48 31 30 30 31 34 7d 20 54 68 *.** {H10014} Th
0c80: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e e SQLITE_VERSION
0c90: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 20 _NUMBER #define
0ca0: 73 68 61 6c 6c 20 72 65 73 6f 6c 76 65 20 74 6f shall resolve to
0cb0: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 an integer.**
0cc0: 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65 with the
0cd0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30 value (X*100000
0ce0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 0 + Y*1000 + Z)
0cf0: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 where X, Y, and
0d00: 5a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 Z.** ar
0d10: 65 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 e the major vers
0d20: 69 6f 6e 2c 20 6d 69 6e 6f 72 20 76 65 72 73 69 ion, minor versi
0d30: 6f 6e 2c 20 61 6e 64 20 72 65 6c 65 61 73 65 20 on, and release
0d40: 6e 75 6d 62 65 72 2e 0a 2a 2f 0a 23 64 65 66 69 number..*/.#defi
0d50: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f ne SQLITE_VERSIO
0d60: 4e 20 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52 N "--VER
0d70: 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c S--".#define SQL
0d80: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
0d90: 45 52 20 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 ER --VERSION-NU
0da0: 4d 42 45 52 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 MBER--../*.** CA
0db0: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 PI3REF: Run-Time
0dc0: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e Library Version
0dd0: 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 32 30 Numbers {H10020
0de0: 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 20 4b 45 } <S60100>.** KE
0df0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f YWORDS: sqlite3_
0e00: 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 version.**.** Th
0e10: 65 73 65 20 66 65 61 74 75 72 65 73 20 70 72 6f ese features pro
0e20: 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e vide the same in
0e30: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 formation as the
0e40: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
0e50: 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 ].** and [SQLITE
0e60: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d _VERSION_NUMBER]
0e70: 20 23 64 65 66 69 6e 65 73 20 69 6e 20 74 68 65 #defines in the
0e80: 20 68 65 61 64 65 72 2c 20 62 75 74 20 61 72 65 header, but are
0e90: 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 associated.** w
0ea0: 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 ith the library
0eb0: 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 instead of the h
0ec0: 65 61 64 65 72 20 66 69 6c 65 2e 20 20 43 61 75 eader file. Cau
0ed0: 74 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d 65 72 tious programmer
0ee0: 73 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63 6c 75 s might.** inclu
0ef0: 64 65 20 61 20 63 68 65 63 6b 20 69 6e 20 74 68 de a check in th
0f00: 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 eir application
0f10: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 0a 2a to verify that.*
0f20: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 * sqlite3_libver
0f30: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 61 6c sion_number() al
0f40: 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 ways returns the
0f50: 20 76 61 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49 54 value.** [SQLIT
0f60: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
0f70: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ]..**.** The sql
0f80: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
0f90: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 ) function retur
0fa0: 6e 73 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f ns the same info
0fb0: 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a 2a 2a rmation as is.**
0fc0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f in the sqlite3_
0fd0: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 version[] string
0fe0: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 constant. The
0ff0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 function is prov
1000: 69 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73 65 20 ided.** for use
1010: 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c in DLLs since DL
1020: 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 L users usually
1030: 64 6f 20 6e 6f 74 20 68 61 76 65 20 64 69 72 65 do not have dire
1040: 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 ct access to str
1050: 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 ing.** constants
1060: 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e within the DLL.
1070: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
1080: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 31 S:.**.** {H10021
1090: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c } The [sqlite3_l
10a0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 ibversion_number
10b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 ()] interface sh
10c0: 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 all return.**
10d0: 20 20 20 20 20 20 20 61 6e 20 69 6e 74 65 67 65 an intege
10e0: 72 20 65 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49 r equal to [SQLI
10f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
1100: 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 R]..**.** {H1002
1110: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 2} The [sqlite3_
1120: 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 version] string
1130: 63 6f 6e 73 74 61 6e 74 20 73 68 61 6c 6c 20 63 constant shall c
1140: 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 ontain.**
1150: 20 20 20 74 68 65 20 74 65 78 74 20 6f 66 20 74 the text of t
1160: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 he [SQLITE_VERSI
1170: 4f 4e 5d 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a ON] string..**.*
1180: 2a 20 7b 48 31 30 30 32 33 7d 20 54 68 65 20 5b * {H10023} The [
1190: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
11a0: 6f 6e 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 on()] function s
11b0: 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 hall return.**
11c0: 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65 a pointe
11d0: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 r to the [sqlite
11e0: 33 5f 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 3_version] strin
11f0: 67 20 63 6f 6e 73 74 61 6e 74 2e 0a 2a 2f 0a 53 g constant..*/.S
1200: 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e QLITE_EXTERN con
1210: 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f st char sqlite3_
1220: 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 version[];.const
1230: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c char *sqlite3_l
1240: 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b ibversion(void);
1250: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 .int sqlite3_lib
1260: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 version_number(v
1270: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 oid);../*.** CAP
1280: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 I3REF: Test To S
1290: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 ee If The Librar
12a0: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 20 y Is Threadsafe
12b0: 7b 48 31 30 31 30 30 7d 20 3c 53 36 30 31 30 30 {H10100} <S60100
12c0: 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 >.**.** SQLite c
12d0: 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 an be compiled w
12e0: 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d ith or without m
12f0: 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a utexes. When.**
1300: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
1310: 45 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 EADSAFE] C prepr
1320: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 ocessor macro is
1330: 20 74 72 75 65 2c 20 6d 75 74 65 78 65 73 0a 2a true, mutexes.*
1340: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e * are enabled an
1350: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 d SQLite is thre
1360: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 adsafe. When th
1370: 61 74 20 6d 61 63 72 6f 20 69 73 20 66 61 6c 73 at macro is fals
1380: 65 2c 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 e,.** the mutexe
1390: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 s are omitted.
13a0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 Without the mute
13b0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 xes, it is not s
13c0: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 afe.** to use SQ
13d0: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c Lite concurrentl
13e0: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e y from more than
13f0: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a one thread..**.
1400: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 ** Enabling mute
1410: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 xes incurs a mea
1420: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 surable performa
1430: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 nce penalty..**
1440: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f So if speed is o
1450: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 f utmost importa
1460: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 nce, it makes se
1470: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a nse to disable.*
1480: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 * the mutexes.
1490: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 But for maximum
14a0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 safety, mutexes
14b0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 should be enable
14c0: 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c d..** The defaul
14d0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f t behavior is fo
14e0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 r mutexes to be
14f0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 enabled..**.** T
1500: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 his interface ca
1510: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 20 70 n be used by a p
1520: 72 6f 67 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73 rogram to make s
1530: 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 ure that the.**
1540: 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 version of SQLit
1550: 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e e that it is lin
1560: 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 king against was
1570: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
1580: 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 * the desired se
1590: 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 tting of the [SQ
15a0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d LITE_THREADSAFE]
15b0: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 macro..**.** Th
15c0: 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c is interface onl
15d0: 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 y reports on the
15e0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 compile-time mu
15f0: 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f tex setting.** o
1600: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 f the [SQLITE_TH
1610: 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 READSAFE] flag.
1620: 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f If SQLite is co
1630: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 mpiled with.** S
1640: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
1650: 3d 31 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 =1 then mutexes
1660: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 are enabled by d
1670: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 efault but.** ca
1680: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 n be fully or pa
1690: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 rtially disabled
16a0: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f using a call to
16b0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
16c0: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ()].** with the
16d0: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f verbs [SQLITE_CO
16e0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
16f0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 D], [SQLITE_CONF
1700: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c IG_MULTITHREAD],
1710: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 .** or [SQLITE_C
1720: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 54 ONFIG_MUTEX]. T
1730: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
1740: 6f 66 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e of this function
1750: 20 73 68 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 shows.** only t
1760: 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6d 70 69 he default compi
1770: 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 2c le-time setting,
1780: 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d not any run-tim
1790: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 e changes.** to
17a0: 74 68 61 74 20 73 65 74 74 69 6e 67 2e 0a 2a 2a that setting..**
17b0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
17c0: 2a 2a 0a 2a 2a 20 7b 48 31 30 31 30 31 7d 20 54 **.** {H10101} T
17d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 he [sqlite3_thre
17e0: 61 64 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69 adsafe()] functi
17f0: 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 on shall return
1800: 6e 6f 6e 7a 65 72 6f 20 69 66 0a 2a 2a 20 20 20 nonzero if.**
1810: 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 77 61 SQLite wa
1820: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
1830: 74 68 65 20 69 74 73 20 6d 75 74 65 78 65 73 20 the its mutexes
1840: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 enabled by defau
1850: 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f lt.** o
1860: 72 20 7a 65 72 6f 20 69 66 20 53 51 4c 69 74 65 r zero if SQLite
1870: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 73 75 was compiled su
1880: 63 68 20 74 68 61 74 20 6d 75 74 65 78 65 73 20 ch that mutexes
1890: 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 are.**
18a0: 70 65 72 6d 61 6e 65 6e 74 6c 79 20 64 69 73 61 permanently disa
18b0: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 bled..**.** {H10
18c0: 31 30 32 7d 20 54 68 65 20 76 61 6c 75 65 20 72 102} The value r
18d0: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 5b eturned by the [
18e0: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 sqlite3_threadsa
18f0: 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a fe()] function.*
1900: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c * shall
1910: 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 65 6e not change when
1920: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 20 61 mutex setting a
1930: 72 65 20 6d 6f 64 69 66 69 65 64 20 61 74 0a 2a re modified at.*
1940: 2a 20 20 20 20 20 20 20 20 20 20 72 75 6e 74 69 * runti
1950: 6d 65 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 me using the [sq
1960: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
1970: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 0a 2a interface and .*
1980: 2a 20 20 20 20 20 20 20 20 20 20 65 73 70 65 63 * espec
1990: 69 61 6c 6c 79 20 74 68 65 20 5b 53 51 4c 49 54 ially the [SQLIT
19a0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
19b0: 48 52 45 41 44 5d 2c 0a 2a 2a 20 20 20 20 20 20 HREAD],.**
19c0: 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 [SQLITE_CONF
19d0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c IG_MULTITHREAD],
19e0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
19f0: 53 45 52 49 41 4c 49 5a 45 44 5d 2c 0a 2a 2a 20 SERIALIZED],.**
1a00: 20 20 20 20 20 20 20 20 20 61 6e 64 20 5b 53 51 and [SQ
1a10: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
1a20: 58 5d 20 76 65 72 62 73 2e 0a 2a 2f 0a 69 6e 74 X] verbs..*/.int
1a30: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 sqlite3_threads
1a40: 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a afe(void);../*.*
1a50: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 * CAPI3REF: Data
1a60: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 base Connection
1a70: 48 61 6e 64 6c 65 20 7b 48 31 32 30 30 30 7d 20 Handle {H12000}
1a80: 3c 53 34 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 <S40200>.** KEYW
1a90: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 ORDS: {database
1aa0: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 connection} {dat
1ab0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1ac0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 s}.**.** Each op
1ad0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 en SQLite databa
1ae0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 se is represente
1af0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 d by a pointer t
1b00: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
1b10: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 .** the opaque s
1b20: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 tructure named "
1b30: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 sqlite3". It is
1b40: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b useful to think
1b50: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a of an sqlite3.*
1b60: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 * pointer as an
1b70: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 object. The [sq
1b80: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b lite3_open()], [
1b90: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
1ba0: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
1bb0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e e3_open_v2()] in
1bc0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 terfaces are its
1bd0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 constructors, a
1be0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 nd [sqlite3_clos
1bf0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 e()].** is its d
1c00: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72 estructor. Ther
1c10: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 e are many other
1c20: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 interfaces (suc
1c30: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 h as.** [sqlite3
1c40: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 _prepare_v2()],
1c50: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
1c60: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 function()], and
1c70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 .** [sqlite3_bus
1c80: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 y_timeout()] to
1c90: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 name but three)
1ca0: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 that are methods
1cb0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 on an.** sqlite
1cc0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 3 object..*/.typ
1cd0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
1ce0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a te3 sqlite3;../*
1cf0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 .** CAPI3REF: 64
1d00: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 -Bit Integer Typ
1d10: 65 73 20 7b 48 31 30 32 30 30 7d 20 3c 53 31 30 es {H10200} <S10
1d20: 31 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 110>.** KEYWORDS
1d30: 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 : sqlite_int64 s
1d40: 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a qlite_uint64.**.
1d50: 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 ** Because there
1d60: 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 is no cross-pla
1d70: 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 tform way to spe
1d80: 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 cify 64-bit inte
1d90: 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c ger types.** SQL
1da0: 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 ite includes typ
1db0: 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 edefs for 64-bit
1dc0: 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 signed and unsi
1dd0: 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a gned integers..*
1de0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
1df0: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 _int64 and sqlit
1e00: 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 e3_uint64 are th
1e10: 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 e preferred type
1e20: 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a definitions..**
1e30: 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 The sqlite_int6
1e40: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 4 and sqlite_uin
1e50: 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 t64 types are su
1e60: 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b pported for back
1e70: 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 wards.** compati
1e80: 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a bility only..**.
1e90: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
1ea0: 2a 0a 2a 2a 20 7b 48 31 30 32 30 31 7d 20 54 68 *.** {H10201} Th
1eb0: 65 20 5b 73 71 6c 69 74 65 5f 69 6e 74 36 34 5d e [sqlite_int64]
1ec0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 69 6e and [sqlite3_in
1ed0: 74 36 34 5d 20 74 79 70 65 20 73 68 61 6c 6c 20 t64] type shall
1ee0: 73 70 65 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 specify.**
1ef0: 20 20 20 20 61 20 36 34 2d 62 69 74 20 73 69 67 a 64-bit sig
1f00: 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a ned integer..**.
1f10: 2a 2a 20 7b 48 31 30 32 30 32 7d 20 54 68 65 20 ** {H10202} The
1f20: 5b 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20 [sqlite_uint64]
1f30: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e and [sqlite3_uin
1f40: 74 36 34 5d 20 74 79 70 65 20 73 68 61 6c 6c 20 t64] type shall
1f50: 73 70 65 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 specify.**
1f60: 20 20 20 20 61 20 36 34 2d 62 69 74 20 75 6e 73 a 64-bit uns
1f70: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a igned integer..*
1f80: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f /.#ifdef SQLITE_
1f90: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 INT64_TYPE. typ
1fa0: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 edef SQLITE_INT6
1fb0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 4_TYPE sqlite_in
1fc0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 t64;. typedef u
1fd0: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 nsigned SQLITE_I
1fe0: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 NT64_TYPE sqlite
1ff0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 _uint64;.#elif d
2000: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 efined(_MSC_VER)
2010: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f || defined(__BO
2020: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 RLANDC__). type
2030: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 def __int64 sqli
2040: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 te_int64;. type
2050: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 def unsigned __i
2060: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 nt64 sqlite_uint
2070: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64;.#else. type
2080: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e def long long in
2090: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a t sqlite_int64;.
20a0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e typedef unsign
20b0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 ed long long int
20c0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a sqlite_uint64;.
20d0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 #endif.typedef s
20e0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 qlite_int64 sqli
20f0: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 te3_int64;.typed
2100: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 ef sqlite_uint64
2110: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b sqlite3_uint64;
2120: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 ../*.** If compi
2130: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 ling for a proce
2140: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 ssor that lacks
2150: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 floating point s
2160: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 upport,.** subst
2170: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f itute integer fo
2180: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 r floating-point
2190: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 ..*/.#ifdef SQLI
21a0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 TE_OMIT_FLOATING
21b0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 _POINT.# define
21c0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 double sqlite3_i
21d0: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a nt64.#endif../*.
21e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f ** CAPI3REF: Clo
21f0: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 sing A Database
2200: 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 30 Connection {H120
2210: 31 30 7d 20 3c 53 33 30 31 30 30 3e 3c 53 34 30 10} <S30100><S40
2220: 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 200>.**.** This
2230: 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64 routine is the d
2240: 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 estructor for th
2250: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 e [sqlite3] obje
2260: 63 74 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 ct..**.** Applic
2270: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 ations should [s
2280: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 qlite3_finalize
2290: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 | finalize] all
22a0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
22b0: 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 ents].** and [sq
22c0: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 lite3_blob_close
22d0: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 | close] all [B
22e0: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 LOB handles] ass
22f0: 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 ociated with.**
2300: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 the [sqlite3] ob
2310: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 ject prior to at
2320: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 tempting to clos
2330: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a e the object..**
2340: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65 The [sqlite3_ne
2350: 78 74 5f 73 74 6d 74 28 29 5d 20 69 6e 74 65 72 xt_stmt()] inter
2360: 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 face can be used
2370: 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a to locate all.*
2380: 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
2390: 65 6d 65 6e 74 73 5d 20 61 73 73 6f 63 69 61 74 ements] associat
23a0: 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 ed with a [datab
23b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
23c0: 69 66 20 64 65 73 69 72 65 64 2e 0a 2a 2a 20 54 if desired..** T
23d0: 79 70 69 63 61 6c 20 63 6f 64 65 20 6d 69 67 68 ypical code migh
23e0: 74 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 69 73 t look like this
23f0: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
2400: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c ote><pre>.** sql
2410: 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
2420: 3b 0a 2a 2a 20 77 68 69 6c 65 28 20 28 70 53 74 ;.** while( (pSt
2430: 6d 74 20 3d 20 73 71 6c 69 74 65 33 5f 6e 65 78 mt = sqlite3_nex
2440: 74 5f 73 74 6d 74 28 64 62 2c 20 30 29 29 21 3d t_stmt(db, 0))!=
2450: 30 20 29 7b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 0 ){.**
2460: 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
2470: 65 28 70 53 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a e(pStmt);.** }.*
2480: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
2490: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b uote>.**.** If [
24a0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d sqlite3_close()]
24b0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c is invoked whil
24c0: 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 e a transaction
24d0: 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 is open,.** the
24e0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 transaction is a
24f0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c utomatically rol
2500: 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 led back..**.**
2510: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
2520: 2a 20 7b 48 31 32 30 31 31 7d 20 41 20 73 75 63 * {H12011} A suc
2530: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 cessful call to
2540: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 [sqlite3_close(C
2550: 29 5d 20 73 68 61 6c 6c 20 64 65 73 74 72 6f 79 )] shall destroy
2560: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
2570: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2580: 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 20 43 2e ction] object C.
2590: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 32 7d 20 .**.** {H12012}
25a0: 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c A successful cal
25b0: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c l to [sqlite3_cl
25c0: 6f 73 65 28 43 29 5d 20 73 68 61 6c 6c 20 72 65 ose(C)] shall re
25d0: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a turn SQLITE_OK..
25e0: 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 33 7d 20 41 **.** {H12013} A
25f0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
2600: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f to [sqlite3_clo
2610: 73 65 28 43 29 5d 20 73 68 61 6c 6c 20 72 65 6c se(C)] shall rel
2620: 65 61 73 65 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 ease all.**
2630: 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 memory and
2640: 73 79 73 74 65 6d 20 72 65 73 6f 75 72 63 65 73 system resources
2650: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
2660: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2670: 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 ction].**
2680: 20 20 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 C..**.** {H12
2690: 30 31 34 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 014} A call to [
26a0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 sqlite3_close(C)
26b0: 5d 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 ] on a [database
26c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 20 74 connection] C t
26d0: 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hat.**
26e0: 68 61 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 has one or more
26f0: 6f 70 65 6e 20 5b 70 72 65 70 61 72 65 64 20 73 open [prepared s
2700: 74 61 74 65 6d 65 6e 74 73 5d 20 73 68 61 6c 6c tatements] shall
2710: 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20 fail with.**
2720: 20 20 20 20 20 20 20 61 6e 20 5b 53 51 4c 49 54 an [SQLIT
2730: 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 63 6f E_BUSY] error co
2740: 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 de..**.** {H1201
2750: 35 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 5} A call to [sq
2760: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 lite3_close(C)]
2770: 77 68 65 72 65 20 43 20 69 73 20 61 20 4e 55 4c where C is a NUL
2780: 4c 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 0a L pointer shall.
2790: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
27a0: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a rn SQLITE_OK..**
27b0: 0a 2a 2a 20 7b 48 31 32 30 31 39 7d 20 57 68 65 .** {H12019} Whe
27c0: 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 n [sqlite3_close
27d0: 28 43 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 (C)] is invoked
27e0: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 on a [database c
27f0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 0a 2a 2a 20 onnection] C.**
2800: 20 20 20 20 20 20 20 20 20 74 68 61 74 20 68 61 that ha
2810: 73 20 61 20 70 65 6e 64 69 6e 67 20 74 72 61 6e s a pending tran
2820: 73 61 63 74 69 6f 6e 2c 20 74 68 65 20 74 72 61 saction, the tra
2830: 6e 73 61 63 74 69 6f 6e 20 73 68 61 6c 6c 20 62 nsaction shall b
2840: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f e.** ro
2850: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a lled back..**.**
2860: 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a ASSUMPTIONS:.**
2870: 0a 2a 2a 20 7b 41 31 32 30 31 36 7d 20 54 68 65 .** {A12016} The
2880: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 C parameter to
2890: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 [sqlite3_close(C
28a0: 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 )] must be eithe
28b0: 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 r a NULL.**
28c0: 20 20 20 20 20 70 6f 69 6e 74 65 72 20 6f 72 20 pointer or
28d0: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a an [sqlite3] obj
28e0: 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 ect pointer obta
28f0: 69 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 ined.**
2900: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f from [sqlite3_o
2910: 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
2920: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a _open16()], or.*
2930: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
2940: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 te3_open_v2()],
2950: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 and not previous
2960: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e ly closed..*/.in
2970: 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 t sqlite3_close(
2980: 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a sqlite3 *);../*.
2990: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 ** The type for
29a0: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
29b0: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 ion..** This is
29c0: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 legacy and depre
29d0: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e cated. It is in
29e0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f cluded for histo
29f0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 rical.** compati
2a00: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f bility and is no
2a10: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f t documented..*/
2a20: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 .typedef int (*s
2a30: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 qlite3_callback)
2a40: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a (void*,int,char*
2a50: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a *, char**);../*.
2a60: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 ** CAPI3REF: One
2a70: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 -Step Query Exec
2a80: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 20 ution Interface
2a90: 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30 30 30 {H12100} <S10000
2aa0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
2ab0: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 te3_exec() inter
2ac0: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e face is a conven
2ad0: 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75 6e 6e ient way of runn
2ae0: 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a ing one or more.
2af0: 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
2b00: 73 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 s without having
2b10: 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f 74 20 to write a lot
2b20: 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68 65 20 of C code. The
2b30: 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a 2a 2a UTF-8 encoded.**
2b40: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
2b50: 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61 73 are passed in as
2b60: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
2b70: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
2b80: 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68 65 20 _exec()..** The
2b90: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 statements are e
2ba0: 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79 20 valuated one by
2bb0: 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68 65 72 one until either
2bc0: 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a 2a 20 an error or.**
2bd0: 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73 20 an interrupt is
2be0: 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f 72 20 encountered, or
2bf0: 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 20 61 until they are a
2c00: 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 33 72 ll done. The 3r
2c10: 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 d parameter.** i
2c20: 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63 61 s an optional ca
2c30: 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 20 69 llback that is i
2c40: 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 nvoked once for
2c50: 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e 79 20 each row of any
2c60: 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c 74 73 query.** results
2c70: 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 68 65 produced by the
2c80: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e SQL statements.
2c90: 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 The 5th parame
2ca0: 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 65 0a ter tells where.
2cb0: 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e 79 20 ** to write any
2cc0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 2e 0a error messages..
2cd0: 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f 72 20 **.** The error
2ce0: 6d 65 73 73 61 67 65 20 70 61 73 73 65 64 20 62 message passed b
2cf0: 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 ack through the
2d00: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 5th parameter is
2d10: 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d 6f held.** in memo
2d20: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ry obtained from
2d30: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
2d40: 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64 20 61 ()]. To avoid a
2d50: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a 2a memory leak,.**
2d60: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61 70 70 the calling app
2d70: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
2d80: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 call [sqlite3_fr
2d90: 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65 72 72 ee()] on any err
2da0: 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 72 65 or.** message re
2db0: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 turned through t
2dc0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
2dd0: 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e when it has fin
2de0: 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 ished using.** t
2df0: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
2e00: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 ..**.** If the S
2e10: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 QL statement in
2e20: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
2e30: 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 r is NULL or an
2e40: 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a 2a 20 empty string.**
2e50: 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 or a string cont
2e60: 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 69 74 aining only whit
2e70: 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d 6d 65 espace and comme
2e80: 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c nts, then no SQL
2e90: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 61 .** statements a
2ea0: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 re evaluated and
2eb0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
2ec0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a not changed..**
2ed0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
2ee0: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 exec() interface
2ef0: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 is implemented
2f00: 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b in terms of.** [
2f10: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2f20: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f v2()], [sqlite3_
2f30: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 step()], and [sq
2f40: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
2f50: 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 ]..** The sqlite
2f60: 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69 6e 65 3_exec() routine
2f70: 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74 6f does nothing to
2f80: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68 the database th
2f90: 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e at cannot be don
2fa0: 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 e.** by [sqlite3
2fb0: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 _prepare_v2()],
2fc0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2fd0: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 , and [sqlite3_f
2fe0: 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a inalize()]..**.*
2ff0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
3000: 0a 2a 2a 20 7b 48 31 32 31 30 31 7d 20 41 20 73 .** {H12101} A s
3010: 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 uccessful invoca
3020: 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
3030: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 _exec(D,S,C,A,E)
3040: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 ].** sh
3050: 61 6c 6c 20 73 65 71 75 65 6e 74 69 61 6c 6c 79 all sequentially
3060: 20 65 76 61 6c 75 61 74 65 20 61 6c 6c 20 6f 66 evaluate all of
3070: 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 the UTF-8 encod
3080: 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ed,.**
3090: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 semicolon-separa
30a0: 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ted SQL statemen
30b0: 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 ts in the zero-t
30c0: 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 erminated.**
30d0: 20 20 20 20 20 20 73 74 72 69 6e 67 20 53 20 77 string S w
30e0: 69 74 68 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 ithin the contex
30f0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 t of the [databa
3100: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
3110: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 32 7d ..**.** {H12102}
3120: 20 49 66 20 74 68 65 20 53 20 70 61 72 61 6d 65 If the S parame
3130: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
3140: 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d exec(D,S,C,A,E)]
3150: 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a is NULL then.**
3160: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 63 the ac
3170: 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 69 6e 74 tions of the int
3180: 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62 65 20 erface shall be
3190: 74 68 65 20 73 61 6d 65 20 61 73 20 69 66 20 74 the same as if t
31a0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 he.** S
31b0: 20 70 61 72 61 6d 65 74 65 72 20 77 65 72 65 20 parameter were
31c0: 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e an empty string.
31d0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 34 7d 20 .**.** {H12104}
31e0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 The return value
31f0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 of [sqlite3_exe
3200: 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 5b 53 c()] shall be [S
3210: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6c 6c QLITE_OK] if all
3220: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c .** SQL
3230: 20 73 74 61 74 65 6d 65 6e 74 73 20 72 75 6e 20 statements run
3240: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61 6e 64 successfully and
3250: 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a to completion..
3260: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 35 7d 20 54 **.** {H12105} T
3270: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
3280: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 of [sqlite3_exec
3290: 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 61 6e 20 ()] shall be an
32a0: 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 20 appropriate.**
32b0: 20 20 20 20 20 20 20 20 6e 6f 6e 2d 7a 65 72 6f non-zero
32c0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
32d0: 20 61 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 any SQL stateme
32e0: 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 nt fails..**.**
32f0: 7b 48 31 32 31 30 37 7d 20 49 66 20 6f 6e 65 20 {H12107} If one
3300: 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 53 or more of the S
3310: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 68 61 QL statements ha
3320: 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 nded to [sqlite3
3330: 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 _exec()].**
3340: 20 20 20 20 20 72 65 74 75 72 6e 20 72 65 73 75 return resu
3350: 6c 74 73 20 61 6e 64 20 74 68 65 20 33 72 64 20 lts and the 3rd
3360: 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 74 parameter is not
3370: 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 2a 2a 20 20 NULL, then.**
3380: 20 20 20 20 20 20 20 20 74 68 65 20 63 61 6c 6c the call
3390: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 70 back function sp
33a0: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 33 ecified by the 3
33b0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 68 61 rd parameter sha
33c0: 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 ll be.**
33d0: 20 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 invoked once f
33e0: 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 72 or each row of r
33f0: 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 esult..**.** {H1
3400: 32 31 31 30 7d 20 49 66 20 74 68 65 20 63 61 6c 2110} If the cal
3410: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 lback returns a
3420: 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65 20 74 non-zero value t
3430: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 hen [sqlite3_exe
3440: 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 c()].**
3450: 20 73 68 61 6c 6c 20 61 62 6f 72 74 20 74 68 65 shall abort the
3460: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 SQL statement i
3470: 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 65 t is currently e
3480: 76 61 6c 75 61 74 69 6e 67 2c 0a 2a 2a 20 20 20 valuating,.**
3490: 20 20 20 20 20 20 20 73 6b 69 70 20 61 6c 6c 20 skip all
34a0: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 subsequent SQL s
34b0: 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 72 tatements, and r
34c0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 41 42 eturn [SQLITE_AB
34d0: 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ORT]..**.** {H12
34e0: 31 31 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 113} The [sqlite
34f0: 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 3_exec()] routin
3500: 65 20 73 68 61 6c 6c 20 70 61 73 73 20 69 74 73 e shall pass its
3510: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
3520: 68 72 6f 75 67 68 0a 2a 2a 20 20 20 20 20 20 20 hrough.**
3530: 20 20 20 61 73 20 74 68 65 20 31 73 74 20 70 61 as the 1st pa
3540: 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 63 rameter of the c
3550: 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b allback..**.** {
3560: 48 31 32 31 31 36 7d 20 54 68 65 20 5b 73 71 6c H12116} The [sql
3570: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 ite3_exec()] rou
3580: 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 tine shall set t
3590: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
35a0: 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 of its.**
35b0: 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 callback to
35c0: 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 be the number of
35d0: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
35e0: 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 0a 2a current row of.*
35f0: 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c * resul
3600: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 39 t..**.** {H12119
3610: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 } The [sqlite3_e
3620: 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 xec()] routine s
3630: 68 61 6c 6c 20 73 65 74 20 74 68 65 20 33 72 64 hall set the 3rd
3640: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 parameter of it
3650: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 s.** ca
3660: 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 llback to be an
3670: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 array of pointer
3680: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c s to strings hol
3690: 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 ding the.**
36a0: 20 20 20 20 20 76 61 6c 75 65 73 20 66 6f 72 20 values for
36b0: 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 each column in t
36c0: 68 65 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c he current resul
36d0: 74 20 73 65 74 20 72 6f 77 20 61 73 0a 2a 2a 20 t set row as.**
36e0: 20 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 obtaine
36f0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
3700: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a column_text()]..
3710: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 32 7d 20 54 **.** {H12122} T
3720: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 he [sqlite3_exec
3730: 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c ()] routine shal
3740: 6c 20 73 65 74 20 74 68 65 20 34 74 68 20 70 61 l set the 4th pa
3750: 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a rameter of its.*
3760: 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 * callb
3770: 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72 ack to be an arr
3780: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 ay of pointers t
3790: 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e o strings holdin
37a0: 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 g the.**
37b0: 20 20 6e 61 6d 65 73 20 6f 66 20 72 65 73 75 6c names of resul
37c0: 74 20 63 6f 6c 75 6d 6e 73 20 61 73 20 6f 62 74 t columns as obt
37d0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
37e0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
37f0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 )]..**.** {H1212
3800: 35 7d 20 49 66 20 74 68 65 20 33 72 64 20 70 61 5} If the 3rd pa
3810: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
3820: 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 4e te3_exec()] is N
3830: 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 ULL then.**
3840: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 [sqlite3_ex
3850: 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 69 6c 65 ec()] shall sile
3860: 6e 74 6c 79 20 64 69 73 63 61 72 64 20 71 75 65 ntly discard que
3870: 72 79 20 72 65 73 75 6c 74 73 2e 0a 2a 2a 0a 2a ry results..**.*
3880: 2a 20 7b 48 31 32 31 33 31 7d 20 49 66 20 61 6e * {H12131} If an
3890: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 error occurs wh
38a0: 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72 20 65 ile parsing or e
38b0: 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20 6f 66 valuating any of
38c0: 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20 20 20 the SQL.**
38d0: 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20 statements
38e0: 69 6e 20 74 68 65 20 53 20 70 61 72 61 6d 65 74 in the S paramet
38f0: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 er of [sqlite3_e
3900: 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 xec(D,S,C,A,E)]
3910: 61 6e 64 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 and if.**
3920: 20 20 20 74 68 65 20 45 20 70 61 72 61 6d 65 74 the E paramet
3930: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 er is not NULL,
3940: 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 then [sqlite3_ex
3950: 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 74 6f 72 ec()] shall stor
3960: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e e.** in
3970: 20 2a 45 20 61 6e 20 61 70 70 72 6f 70 72 69 61 *E an appropria
3980: 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 te error message
3990: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 written into me
39a0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a mory obtained.**
39b0: 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 5b from [
39c0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
39d0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 34 ]..**.** {H12134
39e0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 } The [sqlite3_e
39f0: 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 xec(D,S,C,A,E)]
3a00: 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 routine shall se
3a10: 74 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a t the value of.*
3a20: 2a 20 20 20 20 20 20 20 20 20 20 2a 45 20 74 6f * *E to
3a30: 20 4e 55 4c 4c 20 69 66 20 45 20 69 73 20 6e 6f NULL if E is no
3a40: 74 20 4e 55 4c 4c 20 61 6e 64 20 74 68 65 72 65 t NULL and there
3a50: 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a are no errors..
3a60: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 37 7d 20 54 **.** {H12137} T
3a70: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 he [sqlite3_exec
3a80: 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 66 75 6e (D,S,C,A,E)] fun
3a90: 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20 ction shall set
3aa0: 74 68 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d the [error code]
3ab0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 .** and
3ac0: 20 6d 65 73 73 61 67 65 20 61 63 63 65 73 73 69 message accessi
3ad0: 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 ble via [sqlite3
3ae0: 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 _errcode()],.**
3af0: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
3b00: 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 3_errmsg()], and
3b10: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
3b20: 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 16()]..**.** {H1
3b30: 32 31 33 38 7d 20 49 66 20 74 68 65 20 53 20 70 2138} If the S p
3b40: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
3b50: 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c ite3_exec(D,S,C,
3b60: 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 6f 72 A,E)] is NULL or
3b70: 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 an.**
3b80: 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 empty string or
3b90: 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 contains nothing
3ba0: 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74 other than whit
3bb0: 65 73 70 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 espace, comments
3bc0: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e ,.** an
3bd0: 64 2f 6f 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c d/or semicolons,
3be0: 20 74 68 65 6e 20 72 65 73 75 6c 74 73 20 6f 66 then results of
3bf0: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
3c00: 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 e()],.**
3c10: 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 [sqlite3_errms
3c20: 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 g()], and [sqlit
3c30: 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a e3_errmsg16()].*
3c40: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c * shall
3c50: 20 72 65 73 65 74 20 74 6f 20 69 6e 64 69 63 61 reset to indica
3c60: 74 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a te no errors..**
3c70: 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a .** ASSUMPTIONS:
3c80: 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 31 7d 20 .**.** {A12141}
3c90: 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
3ca0: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
3cb0: 65 78 65 63 28 29 5d 20 6d 75 73 74 20 62 65 20 exec()] must be
3cc0: 61 6e 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 an valid and ope
3cd0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 n.** [d
3ce0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3cf0: 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 on]..**.** {A121
3d00: 34 32 7d 20 54 68 65 20 64 61 74 61 62 61 73 65 42} The database
3d10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 connection must
3d20: 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20 77 not be closed w
3d30: 68 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 hile.**
3d40: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
3d50: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a ] is running..**
3d60: 0a 2a 2a 20 7b 41 31 32 31 34 33 7d 20 54 68 65 .** {A12143} The
3d70: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f calling functio
3d80: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 n should use [sq
3d90: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f lite3_free()] to
3da0: 20 66 72 65 65 0a 2a 2a 20 20 20 20 20 20 20 20 free.**
3db0: 20 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 the memory tha
3dc0: 74 20 2a 65 72 72 6d 73 67 20 69 73 20 6c 65 66 t *errmsg is lef
3dd0: 74 20 70 6f 69 6e 74 69 6e 67 20 61 74 20 6f 6e t pointing at on
3de0: 63 65 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 ce the error.**
3df0: 20 20 20 20 20 20 20 20 20 6d 65 73 73 61 67 65 message
3e00: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 is no longer ne
3e10: 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 eded..**.** {A12
3e20: 31 34 35 7d 20 54 68 65 20 53 51 4c 20 73 74 61 145} The SQL sta
3e30: 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 20 74 tement text in t
3e40: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
3e50: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 to [sqlite3_exe
3e60: 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 c()].**
3e70: 20 6d 75 73 74 20 72 65 6d 61 69 6e 20 75 6e 63 must remain unc
3e80: 68 61 6e 67 65 64 20 77 68 69 6c 65 20 5b 73 71 hanged while [sq
3e90: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 lite3_exec()] is
3ea0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 running..*/.int
3eb0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 sqlite3_exec(.
3ec0: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 sqlite3*,
3ed0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3ee0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 /* A
3ef0: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 n open database
3f00: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
3f10: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 *sql,
3f20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3f30: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 /* SQL to be eva
3f40: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 luated */. int
3f50: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 (*callback)(void
3f60: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 *,int,char**,cha
3f70: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 r**), /* Callba
3f80: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 ck function */.
3f90: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 void *,
3fa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3fb0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 /* 1
3fc0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 st argument to c
3fd0: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 allback */. cha
3fe0: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 r **errmsg
3ff0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4000: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 /* Error
4010: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 msg written her
4020: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 e */.);../*.** C
4030: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 API3REF: Result
4040: 43 6f 64 65 73 20 7b 48 31 30 32 31 30 7d 20 3c Codes {H10210} <
4050: 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S10700>.** KEYWO
4060: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b RDS: SQLITE_OK {
4070: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 error code} {err
4080: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 or codes}.** KEY
4090: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 WORDS: {result c
40a0: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 ode} {result cod
40b0: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 es}.**.** Many S
40c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 QLite functions
40d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 return an intege
40e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 r result code fr
40f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e om the set shown
4100: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 .** here in orde
4110: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 r to indicates s
4120: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 uccess or failur
4130: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 e..**.** New err
4140: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 or codes may be
4150: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
4160: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
4170: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c te..**.** See al
4180: 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 so: [SQLITE_IOER
4190: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 R_READ | extende
41a0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a d result codes].
41b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
41c0: 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 E_OK 0
41d0: 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c /* Successful
41e0: 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 result */./* be
41f0: 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 ginning-of-error
4200: 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e -codes */.#defin
4210: 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 e SQLITE_ERROR
4220: 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 1 /* SQL
4230: 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e error or missin
4240: 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 g database */.#d
4250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 efine SQLITE_INT
4260: 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a ERNAL 2 /*
4270: 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 Internal logic
4280: 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 error in SQLite
4290: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
42a0: 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 E_PERM 3
42b0: 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 /* Access per
42c0: 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a mission denied *
42d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
42e0: 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 _ABORT 4
42f0: 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f /* Callback ro
4300: 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 utine requested
4310: 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 an abort */.#def
4320: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 ine SQLITE_BUSY
4330: 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 5 /* T
4340: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
4350: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 is locked */.#d
4360: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
4370: 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a KED 6 /*
4380: 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 A table in the
4390: 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b database is lock
43a0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
43b0: 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 LITE_NOMEM
43c0: 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 7 /* A mallo
43d0: 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 c() failed */.#d
43e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
43f0: 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a DONLY 8 /*
4400: 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 Attempt to writ
4410: 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 e a readonly dat
4420: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 abase */.#define
4430: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 SQLITE_INTERRUP
4440: 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 T 9 /* Oper
4450: 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 ation terminated
4460: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 by sqlite3_inte
4470: 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e rrupt()*/.#defin
4480: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 e SQLITE_IOERR
4490: 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 10 /* Som
44a0: 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 e kind of disk I
44b0: 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 /O error occurre
44c0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
44d0: 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 ITE_CORRUPT
44e0: 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 11 /* The data
44f0: 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 base disk image
4500: 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a is malformed */.
4510: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
4520: 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 OTFOUND 12
4530: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 /* NOT USED. Tab
4540: 6c 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 le or record not
4550: 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e found */.#defin
4560: 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 e SQLITE_FULL
4570: 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 13 /* Ins
4580: 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 ertion failed be
4590: 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 cause database i
45a0: 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e s full */.#defin
45b0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 e SQLITE_CANTOPE
45c0: 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 N 14 /* Una
45d0: 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 ble to open the
45e0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f database file */
45f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4600: 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 PROTOCOL 15
4610: 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 /* NOT USED. Da
4620: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 tabase lock prot
4630: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 ocol error */.#d
4640: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 efine SQLITE_EMP
4650: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a TY 16 /*
4660: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 Database is emp
4670: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ty */.#define SQ
4680: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 LITE_SCHEMA
4690: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 17 /* The dat
46a0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 abase schema cha
46b0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nged */.#define
46c0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 SQLITE_TOOBIG
46d0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 18 /* Strin
46e0: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 g or BLOB exceed
46f0: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a s size limit */.
4700: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
4710: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 ONSTRAINT 19
4720: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 /* Abort due to
4730: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 constraint viola
4740: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 tion */.#define
4750: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 SQLITE_MISMATCH
4760: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 20 /* Data
4770: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f type mismatch */
4780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4790: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 MISUSE 21
47a0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 /* Library used
47b0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a incorrectly */.
47c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
47d0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 OLFS 22
47e0: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 /* Uses OS featu
47f0: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 res not supporte
4800: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 d on host */.#de
4810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 fine SQLITE_AUTH
4820: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 23 /*
4830: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 Authorization de
4840: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nied */.#define
4850: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 SQLITE_FORMAT
4860: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 24 /* Auxil
4870: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f iary database fo
4880: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 rmat error */.#d
4890: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e efine SQLITE_RAN
48a0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a GE 25 /*
48b0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 2nd parameter t
48c0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f o sqlite3_bind o
48d0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 ut of range */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
48f0: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f TADB 26 /
4900: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 * File opened th
4910: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 at is not a data
4920: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 base file */.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 fine SQLITE_ROW
4940: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 100 /*
4950: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 sqlite3_step() h
4960: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 as another row r
4970: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 eady */.#define
4980: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 SQLITE_DONE
4990: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 101 /* sqlit
49a0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 e3_step() has fi
49b0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 nished executing
49c0: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 */./* end-of-er
49d0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a ror-codes */../*
49e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 .** CAPI3REF: Ex
49f0: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f tended Result Co
4a00: 64 65 73 20 7b 48 31 30 32 32 30 7d 20 3c 53 31 des {H10220} <S1
4a10: 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0700>.** KEYWORD
4a20: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 S: {extended err
4a30: 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 or code} {extend
4a40: 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a ed error codes}.
4a50: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 ** KEYWORDS: {ex
4a60: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
4a70: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65 de} {extended re
4a80: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a sult codes}.**.*
4a90: 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 * In its default
4aa0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 configuration,
4ab0: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 SQLite API routi
4ac0: 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f nes return one o
4ad0: 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 f 26 integer.**
4ae0: 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 [SQLITE_OK | res
4af0: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 ult codes]. How
4b00: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 ever, experience
4b10: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 has shown that
4b20: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 many of.** these
4b30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 result codes ar
4b40: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 e too coarse-gra
4b50: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e ined. They do n
4b60: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a ot provide as.**
4b70: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f much informatio
4b80: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 n about problems
4b90: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 as programmers
4ba0: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 might like. In
4bb0: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 an effort to.**
4bc0: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 address this, ne
4bd0: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 wer versions of
4be0: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 SQLite (version
4bf0: 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 3.3.8 and later)
4c00: 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 include.** supp
4c10: 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ort for addition
4c20: 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 al result codes
4c30: 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 that provide mor
4c40: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 e detailed infor
4c50: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 mation.** about
4c60: 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 errors. The exte
4c70: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
4c80: 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 s are enabled or
4c90: 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 disabled.** on
4ca0: 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63 a per database c
4cb0: 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 onnection basis
4cc0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 using the.** [sq
4cd0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 lite3_extended_r
4ce0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 esult_codes()] A
4cf0: 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f PI..**.** Some o
4d00: 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 f the available
4d10: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
4d20: 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 codes are listed
4d30: 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 here..** One ma
4d40: 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d y expect the num
4d50: 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 ber of extended
4d60: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c result codes wil
4d70: 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f l be expand.** o
4d80: 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 ver time. Softw
4d90: 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65 78 are that uses ex
4da0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
4db0: 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 des should expec
4dc0: 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 t.** to see new
4dd0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 result codes in
4de0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
4df0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
4e00: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 The SQLITE_OK r
4e10: 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 esult code will
4e20: 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 never be extende
4e30: 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 d. It will alwa
4e40: 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 ys.** be exactly
4e50: 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 zero..**.** INV
4e60: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
4e70: 48 31 30 32 32 33 7d 20 54 68 65 20 73 79 6d 62 H10223} The symb
4e80: 6f 6c 69 63 20 6e 61 6d 65 20 66 6f 72 20 61 6e olic name for an
4e90: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
4ea0: 20 63 6f 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74 code shall cont
4eb0: 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 ains.**
4ec0: 20 61 20 72 65 6c 61 74 65 64 20 70 72 69 6d 61 a related prima
4ed0: 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 ry result code a
4ee0: 73 20 61 20 70 72 65 66 69 78 2e 0a 2a 2a 0a 2a s a prefix..**.*
4ef0: 2a 20 7b 48 31 30 32 32 34 7d 20 50 72 69 6d 61 * {H10224} Prima
4f00: 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6e ry result code n
4f10: 61 6d 65 73 20 73 68 61 6c 6c 20 63 6f 6e 74 61 ames shall conta
4f20: 69 6e 20 61 20 73 69 6e 67 6c 65 20 22 5f 22 20 in a single "_"
4f30: 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a character..**.**
4f40: 20 7b 48 31 30 32 32 35 7d 20 45 78 74 65 6e 64 {H10225} Extend
4f50: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6e ed result code n
4f60: 61 6d 65 73 20 73 68 61 6c 6c 20 63 6f 6e 74 61 ames shall conta
4f70: 69 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22 in two or more "
4f80: 5f 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a _" characters..*
4f90: 2a 0a 2a 2a 20 7b 48 31 30 32 32 36 7d 20 54 68 *.** {H10226} Th
4fa0: 65 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 e numeric value
4fb0: 6f 66 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72 of an extended r
4fc0: 65 73 75 6c 74 20 63 6f 64 65 20 73 68 61 6c 6c esult code shall
4fd0: 20 63 6f 6e 74 61 69 6e 20 74 68 65 0a 2a 2a 20 contain the.**
4fe0: 20 20 20 20 20 20 20 20 20 6e 75 6d 65 72 69 63 numeric
4ff0: 20 76 61 6c 75 65 20 6f 66 20 69 74 73 20 63 6f value of its co
5000: 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72 69 6d rresponding prim
5010: 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 ary result code
5020: 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 in.** i
5030: 74 73 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 ts least signifi
5040: 63 61 6e 74 20 38 20 62 69 74 73 2e 0a 2a 2f 0a cant 8 bits..*/.
5050: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5060: 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 OERR_READ
5070: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5080: 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 OERR | (1<<8)).#
5090: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
50a0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 ERR_SHORT_READ
50b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
50c0: 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 ERR | (2<<8)).#d
50d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
50e0: 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 RR_WRITE
50f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5100: 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 RR | (3<<8)).#de
5110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
5120: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 R_FSYNC
5130: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
5140: 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 R | (4<<8)).#def
5150: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5160: 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 _DIR_FSYNC
5170: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5180: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 | (5<<8)).#defi
5190: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
51a0: 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 TRUNCATE
51b0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
51c0: 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (6<<8)).#defin
51d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 e SQLITE_IOERR_F
51e0: 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 STAT
51f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5200: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (7<<8)).#define
5210: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e SQLITE_IOERR_UN
5220: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 LOCK
5230: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5240: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (8<<8)).#define
5250: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c SQLITE_IOERR_RDL
5260: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 OCK (
5270: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5280: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 9<<8)).#define S
5290: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 QLITE_IOERR_DELE
52a0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 TE (S
52b0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 QLITE_IOERR | (1
52c0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 0<<8)).#define S
52d0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 QLITE_IOERR_BLOC
52e0: 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 KED (S
52f0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 QLITE_IOERR | (1
5300: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
5310: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 QLITE_IOERR_NOME
5320: 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 M (S
5330: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 QLITE_IOERR | (1
5340: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
5350: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 QLITE_IOERR_ACCE
5360: 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 SS (S
5370: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 QLITE_IOERR | (1
5380: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 3<<8)).#define S
5390: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 QLITE_IOERR_CHEC
53a0: 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 KRESERVEDLOCK (S
53b0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 QLITE_IOERR | (1
53c0: 34 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 4<<8))../*.** CA
53d0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f PI3REF: Flags Fo
53e0: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 r File Open Oper
53f0: 61 74 69 6f 6e 73 20 7b 48 31 30 32 33 30 7d 20 ations {H10230}
5400: 3c 48 31 31 31 32 30 3e 20 3c 48 31 32 37 30 30 <H11120> <H12700
5410: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 >.**.** These bi
5420: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 t values are int
5430: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e ended for use in
5440: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 the.** 3rd para
5450: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 meter to the [sq
5460: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
5470: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a interface and.*
5480: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 * in the 4th par
5490: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 78 4f ameter to the xO
54a0: 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 pen method of th
54b0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 e.** [sqlite3_vf
54c0: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 s] object..*/.#d
54d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
54e0: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 N_READONLY
54f0: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 0x00000001.#d
5500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5510: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 N_READWRITE
5520: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 0x00000002.#d
5530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5540: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 N_CREATE
5550: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 0x00000004.#d
5560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5570: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 N_DELETEONCLOSE
5580: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 0x00000008.#d
5590: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
55a0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 N_EXCLUSIVE
55b0: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 0x00000010.#d
55c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
55d0: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 N_MAIN_DB
55e0: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 0x00000100.#d
55f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5600: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 N_TEMP_DB
5610: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 0x00000200.#d
5620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5630: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 N_TRANSIENT_DB
5640: 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 0x00000400.#d
5650: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5660: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 N_MAIN_JOURNAL
5670: 20 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 0x00000800.#d
5680: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5690: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 N_TEMP_JOURNAL
56a0: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 0x00001000.#d
56b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
56c0: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 N_SUBJOURNAL
56d0: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 23 64 0x00002000.#d
56e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
56f0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c N_MASTER_JOURNAL
5700: 20 20 20 30 78 30 30 30 30 34 30 30 30 0a 23 64 0x00004000.#d
5710: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5720: 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 N_NOMUTEX
5730: 20 20 20 30 78 30 30 30 30 38 30 30 30 0a 0a 2f 0x00008000../
5740: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
5750: 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 evice Characteri
5760: 73 74 69 63 73 20 7b 48 31 30 32 34 30 7d 20 3c stics {H10240} <
5770: 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 H11120>.**.** Th
5780: 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69 6c e xDeviceCapabil
5790: 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 ities method of
57a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f the [sqlite3_io_
57b0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 methods].** obje
57c0: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e ct returns an in
57d0: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 teger which is a
57e0: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74 vector of the t
57f0: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 hese.** bit valu
5800: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f es expressing I/
5810: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 O characteristic
5820: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 s of the mass st
5830: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 orage.** device
5840: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 that holds the f
5850: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 ile that the [sq
5860: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
5870: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a ].** refers to..
5880: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 **.** The SQLITE
5890: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 _IOCAP_ATOMIC pr
58a0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 operty means tha
58b0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a t all writes of.
58c0: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 ** any size are
58d0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c atomic. The SQL
58e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
58f0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 nnn values.** me
5900: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f an that writes o
5910: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 f blocks that ar
5920: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 e nnn bytes in s
5930: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 ize and.** are a
5940: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 ligned to an add
5950: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e ress which is an
5960: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c integer multipl
5970: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 e of.** nnn are
5980: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c atomic. The SQL
5990: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 ITE_IOCAP_SAFE_A
59a0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e PPEND value mean
59b0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 s.** that when d
59c0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 ata is appended
59d0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 to a file, the d
59e0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a ata is appended.
59f0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 ** first then th
5a00: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 e size of the fi
5a10: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 le is extended,
5a20: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a never the other.
5a30: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 ** way around.
5a40: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
5a50: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 _SEQUENTIAL prop
5a60: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a erty means that.
5a70: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 ** information i
5a80: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 s written to dis
5a90: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 k in the same or
5aa0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 der as calls.**
5ab0: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a to xWrite()..*/.
5ac0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5ad0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 OCAP_ATOMIC
5ae0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 0x00000001.
5af0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5b00: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 OCAP_ATOMIC512
5b10: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 0x00000002.
5b20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5b30: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 OCAP_ATOMIC1K
5b40: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 0x00000004.
5b50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5b60: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 OCAP_ATOMIC2K
5b70: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 0x00000008.
5b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5b90: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 OCAP_ATOMIC4K
5ba0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 0x00000010.
5bb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5bc0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 OCAP_ATOMIC8K
5bd0: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 0x00000020.
5be0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5bf0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 OCAP_ATOMIC16K
5c00: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 0x00000040.
5c10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5c20: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 OCAP_ATOMIC32K
5c30: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 0x00000080.
5c40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5c50: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 OCAP_ATOMIC64K
5c60: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 0x00000100.
5c70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5c80: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 OCAP_SAFE_APPEND
5c90: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 0x00000200.
5ca0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5cb0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
5cc0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0x00000400.
5cd0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
5ce0: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 File Locking Le
5cf0: 76 65 6c 73 20 7b 48 31 30 32 35 30 7d 20 3c 48 vels {H10250} <H
5d00: 31 31 31 32 30 3e 20 3c 48 31 31 33 31 30 3e 0a 11120> <H11310>.
5d10: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 **.** SQLite use
5d20: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 s one of these i
5d30: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 nteger values as
5d40: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 the second.** a
5d50: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 rgument to calls
5d60: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 it makes to the
5d70: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e xLock() and xUn
5d80: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a lock() methods.*
5d90: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 * of an [sqlite3
5da0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
5db0: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ect..*/.#define
5dc0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 SQLITE_LOCK_NONE
5dd0: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 0.#def
5de0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ine SQLITE_LOCK_
5df0: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a SHARED 1.
5e00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
5e10: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 OCK_RESERVED
5e20: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
5e30: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 TE_LOCK_PENDING
5e40: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 3.#define
5e50: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c SQLITE_LOCK_EXCL
5e60: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a USIVE 4../*.
5e70: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e ** CAPI3REF: Syn
5e80: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 chronization Typ
5e90: 65 20 46 6c 61 67 73 20 7b 48 31 30 32 36 30 7d e Flags {H10260}
5ea0: 20 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 <H11120>.**.**
5eb0: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f When SQLite invo
5ec0: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 kes the xSync()
5ed0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 method of an.**
5ee0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
5ef0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 ods] object it u
5f00: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f ses a combinatio
5f10: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e n of.** these in
5f20: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 teger values as
5f30: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
5f40: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 ent..**.** When
5f50: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f the SQLITE_SYNC_
5f60: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 DATAONLY flag is
5f70: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 used, it means
5f80: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 that the.** sync
5f90: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 operation only
5fa0: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 needs to flush d
5fb0: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 ata to mass stor
5fc0: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 age. Inode.** i
5fd0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 nformation need
5fe0: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 not be flushed.
5ff0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f The SQLITE_SYNC_
6000: 4e 4f 52 4d 41 4c 20 66 6c 61 67 20 6d 65 61 6e NORMAL flag mean
6010: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 6e 6f 72 6d s.** to use norm
6020: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e al fsync() seman
6030: 74 69 63 73 2e 20 54 68 65 20 53 51 4c 49 54 45 tics. The SQLITE
6040: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20 _SYNC_FULL flag
6050: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 means.** to use
6060: 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 Mac OS-X style f
6070: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 ullsync instead
6080: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 of fsync()..*/.#
6090: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 define SQLITE_SY
60a0: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 NC_NORMAL
60b0: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 0x00002.#define
60c0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c SQLITE_SYNC_FUL
60d0: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 L 0x000
60e0: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 03.#define SQLIT
60f0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 E_SYNC_DATAONLY
6100: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0x00010../*
6110: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 .** CAPI3REF: OS
6120: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 Interface Open
6130: 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 48 31 31 File Handle {H11
6140: 31 31 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 110} <S20110>.**
6150: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f .** An [sqlite3_
6160: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 file] object rep
6170: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 resents an open
6180: 66 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a file in the OS.*
6190: 2a 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 * interface laye
61a0: 72 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f r. Individual O
61b0: 53 20 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c S interface impl
61c0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c ementations will
61d0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 .** want to subc
61e0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 lass this object
61f0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 by appending ad
6200: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a ditional fields.
6210: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e ** for their own
6220: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 use. The pMeth
6230: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 ods entry is a p
6240: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
6250: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
6260: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 ods] object that
6270: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 defines methods
6280: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a for performing.
6290: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e ** I/O operation
62a0: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 s on the open fi
62b0: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 le..*/.typedef s
62c0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 truct sqlite3_fi
62d0: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b le sqlite3_file;
62e0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
62f0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 file {. const s
6300: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f truct sqlite3_io
6310: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f _methods *pMetho
6320: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 ds; /* Methods
6330: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 for an open file
6340: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
6350: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 PI3REF: OS Inter
6360: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 face File Virtua
6370: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 l Methods Object
6380: 20 7b 48 31 31 31 32 30 7d 20 3c 53 32 30 31 31 {H11120} <S2011
6390: 30 3e 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 0>.**.** Every f
63a0: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 ile opened by th
63b0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 e [sqlite3_vfs]
63c0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 xOpen method pop
63d0: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 ulates an.** [sq
63e0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
63f0: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d ct (or, more com
6400: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 monly, a subclas
6410: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c s of the.** [sql
6420: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
6430: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 t) with a pointe
6440: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 r to an instance
6450: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e of this object.
6460: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 .** This object
6470: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 defines the meth
6480: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 ods used to perf
6490: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 orm various oper
64a0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 ations.** agains
64b0: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 t the open file
64c0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 represented by t
64d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 he [sqlite3_file
64e0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 ] object..**.**
64f0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 The flags argume
6500: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 nt to xSync may
6510: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 be one of [SQLIT
6520: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f E_SYNC_NORMAL] o
6530: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e r.** [SQLITE_SYN
6540: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 C_FULL]. The fi
6550: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 rst choice is th
6560: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 e normal fsync()
6570: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 ..** The second
6580: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 choice is a Mac
6590: 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 OS-X style fulls
65a0: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 ync. The [SQLIT
65b0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d E_SYNC_DATAONLY]
65c0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 .** flag may be
65d0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 ORed in to indic
65e0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 ate that only th
65f0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 e data of the fi
6600: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 le.** and not it
6610: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f s inode needs to
6620: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a be synced..**.*
6630: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 * The integer va
6640: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 lues to xLock()
6650: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 and xUnlock() ar
6660: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e e one of.** <ul>
6670: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
6680: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 _LOCK_NONE],.**
6690: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
66a0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c K_SHARED],.** <l
66b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f i> [SQLITE_LOCK_
66c0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c RESERVED],.** <l
66d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f i> [SQLITE_LOCK_
66e0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 PENDING], or.**
66f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
6700: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a K_EXCLUSIVE]..**
6710: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 </ul>.** xLock(
6720: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 ) increases the
6730: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 lock. xUnlock()
6740: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f decreases the lo
6750: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 ck..** The xChec
6760: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 kReservedLock()
6770: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 method checks wh
6780: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 ether any databa
6790: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a se connection,.*
67a0: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 * either in this
67b0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 process or in s
67c0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 ome other proces
67d0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 s, is holding a
67e0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e RESERVED,.** PEN
67f0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 DING, or EXCLUSI
6800: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 VE lock on the f
6810: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 ile. It returns
6820: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 true.** if such
6830: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 a lock exists a
6840: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 nd false otherwi
6850: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 se..**.** The xF
6860: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 ileControl() met
6870: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 hod is a generic
6880: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 interface that
6890: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a allows custom.**
68a0: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
68b0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 ions to directly
68c0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e control an open
68d0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a file using the.
68e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ** [sqlite3_file
68f0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 _control()] inte
6900: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f rface. The seco
6910: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 nd "op" argument
6920: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 is an.** intege
6930: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 r opcode. The t
6940: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
6950: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 a generic point
6960: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a er intended to.*
6970: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 * point to a str
6980: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 ucture that may
6990: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 contain argument
69a0: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 s or space in wh
69b0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 ich to.** write
69c0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 return values.
69d0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 Potential uses f
69e0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 or xFileControl(
69f0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 ) might be.** fu
6a00: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c nctions to enabl
6a10: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 e blocking locks
6a20: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 with timeouts,
6a30: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a to change the.**
6a40: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 locking strateg
6a50: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 y (for example t
6a60: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c o use dot-file l
6a70: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 ocks), to inquir
6a80: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 e.** about the s
6a90: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c tatus of a lock,
6aa0: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 or to break sta
6ab0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 le locks. The S
6ac0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 QLite.** core re
6ad0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 serves all opcod
6ae0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 es less than 100
6af0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 for its own use
6b00: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 ..** A [SQLITE_F
6b10: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c CNTL_LOCKSTATE |
6b20: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 list of opcodes
6b30: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 ] less than 100
6b40: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a is available..**
6b50: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 Applications th
6b60: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 at define a cust
6b70: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 om xFileControl
6b80: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 method should us
6b90: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 e opcodes.** gre
6ba0: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f ater than 100 to
6bb0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 avoid conflicts
6bc0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 ..**.** The xSec
6bd0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 torSize() method
6be0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 returns the sec
6bf0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a tor size of the.
6c00: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 ** device that u
6c10: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c nderlies the fil
6c20: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 e. The sector s
6c30: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 ize is the.** mi
6c40: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 nimum write that
6c50: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 can be performe
6c60: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 d without distur
6c70: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 bing.** other by
6c80: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e tes in the file.
6c90: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 The xDeviceCha
6ca0: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a racteristics().*
6cb0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 * method returns
6cc0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 a bit vector de
6cd0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f scribing behavio
6ce0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 rs of the.** und
6cf0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a erlying device:.
6d00: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
6d10: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
6d20: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e _ATOMIC].** <li>
6d30: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
6d40: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 TOMIC512].** <li
6d50: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
6d60: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 ATOMIC1K].** <li
6d70: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
6d80: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 ATOMIC2K].** <li
6d90: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
6da0: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 ATOMIC4K].** <li
6db0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
6dc0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 ATOMIC8K].** <li
6dd0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
6de0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c ATOMIC16K].** <l
6df0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
6e00: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c _ATOMIC32K].** <
6e10: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
6e20: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 P_ATOMIC64K].**
6e30: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
6e40: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a AP_SAFE_APPEND].
6e50: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
6e60: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c IOCAP_SEQUENTIAL
6e70: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a ].** </ul>.**.**
6e80: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
6e90: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 P_ATOMIC propert
6ea0: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c y means that all
6eb0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e writes of.** an
6ec0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 y size are atomi
6ed0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 c. The SQLITE_I
6ee0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 OCAP_ATOMICnnn v
6ef0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 alues.** mean th
6f00: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f at writes of blo
6f10: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e cks that are nnn
6f20: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 bytes in size a
6f30: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 nd.** are aligne
6f40: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 d to an address
6f50: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 which is an inte
6f60: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a ger multiple of.
6f70: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 ** nnn are atomi
6f80: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 c. The SQLITE_I
6f90: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 OCAP_SAFE_APPEND
6fa0: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 value means.**
6fb0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 that when data i
6fc0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 s appended to a
6fd0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 file, the data i
6fe0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 s appended.** fi
6ff0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a rst then the siz
7000: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 e of the file is
7010: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 extended, never
7020: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 the other.** wa
7030: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 y around. The S
7040: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
7050: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 ENTIAL property
7060: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e means that.** in
7070: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 formation is wri
7080: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 tten to disk in
7090: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 the same order a
70a0: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 s calls.** to xW
70b0: 72 69 74 65 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 rite()..*/.typed
70c0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
70d0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 3_io_methods sql
70e0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b ite3_io_methods;
70f0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
7100: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 io_methods {. i
7110: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 nt iVersion;. i
7120: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c nt (*xClose)(sql
7130: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 ite3_file*);. i
7140: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 nt (*xRead)(sqli
7150: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a te3_file*, void*
7160: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 , int iAmt, sqli
7170: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 te3_int64 iOfst)
7180: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 ;. int (*xWrite
7190: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
71a0: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
71b0: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f t iAmt, sqlite3_
71c0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 int64 iOfst);.
71d0: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 int (*xTruncate)
71e0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
71f0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 sqlite3_int64 si
7200: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 ze);. int (*xSy
7210: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 nc)(sqlite3_file
7220: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 *, int flags);.
7230: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 int (*xFileSize
7240: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
7250: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
7260: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a pSize);. int (*
7270: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 xLock)(sqlite3_f
7280: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e ile*, int);. in
7290: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c t (*xUnlock)(sql
72a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 ite3_file*, int)
72b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b ;. int (*xCheck
72c0: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 ReservedLock)(sq
72d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
72e0: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e *pResOut);. in
72f0: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c t (*xFileControl
7300: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
7310: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 int op, void *p
7320: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 Arg);. int (*xS
7330: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 ectorSize)(sqlit
7340: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 e3_file*);. int
7350: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 (*xDeviceCharac
7360: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 teristics)(sqlit
7370: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 e3_file*);. /*
7380: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f Additional metho
7390: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ds may be added
73a0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
73b0: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 es */.};../*.**
73c0: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 CAPI3REF: Standa
73d0: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 rd File Control
73e0: 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30 7d Opcodes {H11310}
73f0: 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S30800>.**.**
7400: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f These integer co
7410: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f nstants are opco
7420: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c des for the xFil
7430: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a eControl method.
7440: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
7450: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
7460: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 bject and for th
7470: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f e [sqlite3_file_
7480: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e control()].** in
7490: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 terface..**.** T
74a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
74b0: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f _LOCKSTATE] opco
74c0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 de is used for d
74d0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a ebugging. This.
74e0: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 ** opcode causes
74f0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f the xFileContro
7500: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 l method to writ
7510: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 e the current st
7520: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f ate of.** the lo
7530: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 ck (one of [SQLI
7540: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b TE_LOCK_NONE], [
7550: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 SQLITE_LOCK_SHAR
7560: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ED],.** [SQLITE_
7570: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 LOCK_RESERVED],
7580: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e [SQLITE_LOCK_PEN
7590: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 DING], or [SQLIT
75a0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 E_LOCK_EXCLUSIVE
75b0: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e ]).** into an in
75c0: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 teger that the p
75d0: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 Arg argument poi
75e0: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 nts to. This cap
75f0: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 ability.** is us
7600: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e ed during testin
7610: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 g and only needs
7620: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
7630: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 when SQLITE_TES
7640: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e T.** is defined.
7650: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
7660: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
7670: 54 45 20 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a TE 1../*.
7680: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 ** CAPI3REF: Mut
7690: 65 78 20 48 61 6e 64 6c 65 20 7b 48 31 37 31 31 ex Handle {H1711
76a0: 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a 0} <S20130>.**.*
76b0: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 * The mutex modu
76c0: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 le within SQLite
76d0: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 defines [sqlite
76e0: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 3_mutex] to be a
76f0: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 n.** abstract ty
7700: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f pe for a mutex o
7710: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 bject. The SQLi
7720: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f te core never lo
7730: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e oks.** at the in
7740: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 ternal represent
7750: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c ation of an [sql
7760: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 ite3_mutex]. It
7770: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 only.** deals w
7780: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 ith pointers to
7790: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 the [sqlite3_mut
77a0: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a ex] object..**.*
77b0: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 * Mutexes are cr
77c0: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c eated using [sql
77d0: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 ite3_mutex_alloc
77e0: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ()]..*/.typedef
77f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
7800: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 utex sqlite3_mut
7810: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ex;../*.** CAPI3
7820: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
7830: 65 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 34 30 e Object {H11140
7840: 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a } <S20100>.**.**
7850: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
7860: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 the sqlite3_vfs
7870: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
7880: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 he interface bet
7890: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 ween.** the SQLi
78a0: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 te core and the
78b0: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 underlying opera
78c0: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 ting system. Th
78d0: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 e "vfs".** in th
78e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 e name of the ob
78f0: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 ject stands for
7900: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 "virtual file sy
7910: 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 stem"..**.** The
7920: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 value of the iV
7930: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 ersion field is
7940: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 initially 1 but
7950: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e may be larger in
7960: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 .** future versi
7970: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 ons of SQLite.
7980: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 Additional field
7990: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 s may be appende
79a0: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a d to this.** obj
79b0: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 ect when the iVe
79c0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 rsion value is i
79d0: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 ncreased. Note
79e0: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 that the structu
79f0: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c re.** of the sql
7a00: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 ite3_vfs object
7a10: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 changes in the t
7a20: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 ransaction betwe
7a30: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 en.** SQLite ver
7a40: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 sion 3.5.9 and 3
7a50: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 .6.0 and yet the
7a60: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 iVersion field
7a70: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 was not.** modif
7a80: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ied..**.** The s
7a90: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 zOsFile field is
7aa0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
7ab0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c subclassed [sql
7ac0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 ite3_file].** st
7ad0: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 ructure used by
7ae0: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 this VFS. mxPat
7af0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 hname is the max
7b00: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a imum length of.*
7b10: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 * a pathname in
7b20: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 this VFS..**.**
7b30: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 Registered sqlit
7b40: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 e3_vfs objects a
7b50: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e re kept on a lin
7b60: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 ked list formed
7b70: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 by.** the pNext
7b80: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 pointer. The [s
7b90: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 qlite3_vfs_regis
7ba0: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ter()].** and [s
7bb0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 qlite3_vfs_unreg
7bc0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 ister()] interfa
7bd0: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 ces manage this
7be0: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 list.** in a thr
7bf0: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 ead-safe way. T
7c00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f he [sqlite3_vfs_
7c10: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 find()] interfac
7c20: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 e.** searches th
7c30: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 e list. Neither
7c40: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
7c50: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 code nor the VF
7c60: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 S.** implementat
7c70: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 ion should use t
7c80: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 he pNext pointer
7c90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 ..**.** The pNex
7ca0: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f t field is the o
7cb0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 nly field in the
7cc0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 sqlite3_vfs.**
7cd0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 structure that S
7ce0: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 QLite will ever
7cf0: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 modify. SQLite
7d00: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 will only access
7d10: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 .** or modify th
7d20: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 is field while h
7d30: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 olding a particu
7d40: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 lar static mutex
7d50: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
7d60: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 tion should neve
7d70: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e r modify anythin
7d80: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c g within the sql
7d90: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 ite3_vfs.** obje
7da0: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 ct once the obje
7db0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 ct has been regi
7dc0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 stered..**.** Th
7dd0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f e zName field ho
7de0: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 lds the name of
7df0: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 the VFS module.
7e00: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a The name must.*
7e10: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f * be unique acro
7e20: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c ss all VFS modul
7e30: 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 es..**.** {H1114
7e40: 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 1} SQLite will g
7e50: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 uarantee that th
7e60: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 e zFilename para
7e70: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a meter to xOpen.*
7e80: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 * is either a NU
7e90: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 LL pointer or st
7ea0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a ring obtained.**
7eb0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e from xFullPathn
7ec0: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66 ame(). SQLite f
7ed0: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 urther guarantee
7ee0: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 s that.** the st
7ef0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c ring will be val
7f00: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 id and unchanged
7f10: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 until xClose()
7f20: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 7b 45 is.** called. {E
7f30: 4e 44 7d 20 20 42 65 63 61 75 73 65 20 6f 66 20 ND} Because of
7f40: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e the previous sen
7f50: 74 65 6e 73 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 tense,.** the [s
7f60: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e qlite3_file] can
7f70: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 safely store a
7f80: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a pointer to the.*
7f90: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 * filename if it
7fa0: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 needs to rememb
7fb0: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 er the filename
7fc0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e for some reason.
7fd0: 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 .** If the zFile
7fe0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 name parameter i
7ff0: 73 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c s xOpen is a NUL
8000: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 L pointer then x
8010: 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 Open.** must inv
8020: 69 74 65 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 ite its own temp
8030: 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 orary name for t
8040: 68 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 76 he file. Whenev
8050: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 er the .** xFile
8060: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 name parameter i
8070: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 s NULL it will a
8080: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 lso be the case
8090: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 that the.** flag
80a0: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c s parameter will
80b0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 include [SQLITE
80c0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
80d0: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 OSE]..**.** {H11
80e0: 31 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20 61 142} The flags a
80f0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e rgument to xOpen
8100: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 () includes all
8110: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 bits set in.** t
8120: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
8130: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 t to [sqlite3_op
8140: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 en_v2()]. Or if
8150: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
8160: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 ].** or [sqlite3
8170: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 _open16()] is us
8180: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 ed, then flags i
8190: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 ncludes at least
81a0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
81b0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 _READWRITE] | [S
81c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
81d0: 45 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 E]. {END}.** If
81e0: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 xOpen() opens a
81f0: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 file read-only t
8200: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 hen it sets *pOu
8210: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 tFlags to.** inc
8220: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 lude [SQLITE_OPE
8230: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 N_READONLY]. Ot
8240: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 her bits in *pOu
8250: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 tFlags may be se
8260: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 33 t..**.** {H11143
8270: 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c } SQLite will al
8280: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 so add one of th
8290: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 e following flag
82a0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 s to the xOpen()
82b0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 .** call, depend
82c0: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 ing on the objec
82d0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a t being opened:.
82e0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
82f0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
8300: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 _MAIN_DB].** <li
8310: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
8320: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a MAIN_JOURNAL].**
8330: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
8340: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 PEN_TEMP_DB].**
8350: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
8360: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d EN_TEMP_JOURNAL]
8370: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
8380: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 E_OPEN_TRANSIENT
8390: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
83a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f QLITE_OPEN_SUBJO
83b0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 URNAL].** <li>
83c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 [SQLITE_OPEN_MAS
83d0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 TER_JOURNAL].**
83e0: 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a </ul> {END}.**.*
83f0: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 * The file I/O i
8400: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 mplementation ca
8410: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 n use the object
8420: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a type flags to.*
8430: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 * change the way
8440: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 it deals with f
8450: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 iles. For examp
8460: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 le, an applicati
8470: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 on.** that does
8480: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 not care about c
8490: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 rash recovery or
84a0: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 rollback might
84b0: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e make.** the open
84c0: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 of a journal fi
84d0: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 le a no-op. Wri
84e0: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 tes to this jour
84f0: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 nal would.** als
8500: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 o be no-ops, and
8510: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 any attempt to
8520: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c read the journal
8530: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a would return.**
8540: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 SQLITE_IOERR.
8550: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 Or the implement
8560: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f ation might reco
8570: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 gnize that a dat
8580: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 abase.** file wi
8590: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 ll be doing page
85a0: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 -aligned sector
85b0: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 reads and writes
85c0: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 in a random.**
85d0: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 order and set up
85e0: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 its I/O subsyst
85f0: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a em accordingly..
8600: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 **.** SQLite mig
8610: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 ht also add one
8620: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
8630: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f flags to the xO
8640: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a pen method:.**.*
8650: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
8660: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
8670: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c TEONCLOSE].** <l
8680: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f i> [SQLITE_OPEN_
8690: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f EXCLUSIVE].** </
86a0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 ul>.**.** {H1114
86b0: 35 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 5} The [SQLITE_O
86c0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
86d0: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 E] flag means th
86e0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 e file should be
86f0: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e .** deleted when
8700: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 it is closed.
8710: 7b 48 31 31 31 34 36 7d 20 54 68 65 20 5b 53 51 {H11146} The [SQ
8720: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
8730: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c ONCLOSE].** will
8740: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 be set for TEMP
8750: 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 databases, jou
8760: 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 rnals and for su
8770: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a bjournals..**.**
8780: 20 7b 48 31 31 31 34 37 7d 20 54 68 65 20 5b 53 {H11147} The [S
8790: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
87a0: 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 SIVE] flag means
87b0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 the file should
87c0: 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f be opened.** fo
87d0: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 r exclusive acce
87e0: 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69 ss. This flag i
87f0: 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 s set for all fi
8800: 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f les except.** fo
8810: 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 r the main datab
8820: 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 ase file..**.**
8830: 7b 48 31 31 31 34 38 7d 20 41 74 20 6c 65 61 73 {H11148} At leas
8840: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 t szOsFile bytes
8850: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 of memory are a
8860: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 llocated by SQLi
8870: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 te.** to hold th
8880: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 e [sqlite3_file
8890: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 ] structure pass
88a0: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a ed as the third.
88b0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 ** argument to x
88c0: 4f 70 65 6e 2e 20 7b 45 4e 44 7d 20 20 54 68 65 Open. {END} The
88d0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f xOpen method do
88e0: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a es not have to.*
88f0: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 * allocate the s
8900: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f tructure; it sho
8910: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 uld just fill it
8920: 20 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 in..**.** {H111
8930: 34 39 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72 49} The flags ar
8940: 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 gument to xAcces
8950: 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 s() may be [SQLI
8960: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 TE_ACCESS_EXISTS
8970: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 ].** to test for
8980: 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f the existence o
8990: 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 f a file, or [SQ
89a0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
89b0: 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 WRITE] to.** tes
89c0: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 t whether a file
89d0: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 is readable and
89e0: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 writable, or [S
89f0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
8a00: 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 D].** to test wh
8a10: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 ether a file is
8a20: 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c at least readabl
8a30: 65 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 66 69 e. {END} The fi
8a40: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 le can be a.** d
8a50: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 irectory..**.**
8a60: 7b 48 31 31 31 35 30 7d 20 53 51 4c 69 74 65 20 {H11150} SQLite
8a70: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f will always allo
8a80: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 cate at least mx
8a90: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 Pathname+1 bytes
8aa0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 for the.** outp
8ab0: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 ut buffer xFullP
8ac0: 61 74 68 6e 61 6d 65 2e 20 7b 48 31 31 31 35 31 athname. {H11151
8ad0: 7d 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 } The exact size
8ae0: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 of the output b
8af0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f uffer.** is also
8b00: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 passed as a par
8b10: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 ameter to both
8b20: 6d 65 74 68 6f 64 73 2e 20 7b 45 4e 44 7d 20 20 methods. {END}
8b30: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 If the output bu
8b40: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c ffer.** is not l
8b50: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 arge enough, [SQ
8b60: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 LITE_CANTOPEN] s
8b70: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 hould be returne
8b80: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 d. Since this is
8b90: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 .** handled as a
8ba0: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 fatal error by
8bb0: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c SQLite, vfs impl
8bc0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 ementations shou
8bd0: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 ld endeavor.** t
8be0: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 o prevent this b
8bf0: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 y setting mxPath
8c00: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 name to a suffic
8c10: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c iently large val
8c20: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 ue..**.** The xR
8c30: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c andomness(), xSl
8c40: 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 eep(), and xCurr
8c50: 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 entTime() interf
8c60: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 aces.** are not
8c70: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 strictly a part
8c80: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 of the filesyste
8c90: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a m, but they are.
8ca0: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 ** included in t
8cb0: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 he VFS structure
8cc0: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 for completenes
8cd0: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f s..** The xRando
8ce0: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e mness() function
8cf0: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 attempts to ret
8d00: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 urn nBytes bytes
8d10: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c .** of good-qual
8d20: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 ity randomness i
8d30: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 nto zOut. The r
8d40: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a eturn value is.*
8d50: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d * the actual num
8d60: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 ber of bytes of
8d70: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 randomness obtai
8d80: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 ned..** The xSle
8d90: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 ep() method caus
8da0: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 es the calling t
8db0: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 hread to sleep f
8dc0: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 or at.** least t
8dd0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 he number of mic
8de0: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e roseconds given.
8df0: 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 The xCurrentTi
8e00: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 me().** method r
8e10: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 eturns a Julian
8e20: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 Day Number for t
8e30: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 he current date
8e40: 61 6e 64 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 and time..*/.typ
8e50: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
8e60: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f te3_vfs sqlite3_
8e70: 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 vfs;.struct sqli
8e80: 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 te3_vfs {. int
8e90: 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 iVersion;
8ea0: 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 /* Structur
8eb0: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 e version number
8ec0: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 */. int szOsFi
8ed0: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f le; /
8ee0: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 * Size of subcla
8ef0: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c ssed sqlite3_fil
8f00: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 e */. int mxPat
8f10: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 hname;
8f20: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 /* Maximum file
8f30: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 pathname length
8f40: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 */. sqlite3_vfs
8f50: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a *pNext; /*
8f60: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 Next registered
8f70: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 VFS */. const
8f80: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 char *zName;
8f90: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 /* Name of th
8fa0: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 is virtual file
8fb0: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 system */. void
8fc0: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 *pAppData;
8fd0: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 /* Pointer
8fe0: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 to application-s
8ff0: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a pecific data */.
9000: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 int (*xOpen)(s
9010: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
9020: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
9030: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 sqlite3_file*,.
9040: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e in
9050: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f t flags, int *pO
9060: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 utFlags);. int
9070: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 (*xDelete)(sqlit
9080: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
9090: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 har *zName, int
90a0: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 syncDir);. int
90b0: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 (*xAccess)(sqlit
90c0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
90d0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 har *zName, int
90e0: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 flags, int *pRes
90f0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 Out);. int (*xF
9100: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c ullPathname)(sql
9110: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
9120: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
9130: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f t nOut, char *zO
9140: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 ut);. void *(*x
9150: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f DlOpen)(sqlite3_
9160: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
9170: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 *zFilename);.
9180: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 void (*xDlError)
9190: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
91a0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a nt nByte, char *
91b0: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 zErrMsg);. void
91c0: 20 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 *(*xDlSym)(sqli
91d0: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 te3_vfs*,void*,
91e0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d const char *zSym
91f0: 62 6f 6c 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 bol);. void (*x
9200: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 DlClose)(sqlite3
9210: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 _vfs*, void*);.
9220: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 int (*xRandomne
9230: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ss)(sqlite3_vfs*
9240: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 , int nByte, cha
9250: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 r *zOut);. int
9260: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 (*xSleep)(sqlite
9270: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 3_vfs*, int micr
9280: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 oseconds);. int
9290: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 (*xCurrentTime)
92a0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 (sqlite3_vfs*, d
92b0: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 ouble*);. int (
92c0: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 *xGetLastError)(
92d0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
92e0: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a t, char *);. /*
92f0: 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 New fields may
9300: 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 be appended in f
9310: 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 igure versions.
9320: 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 The iVersion.
9330: 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e ** value will in
9340: 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 crement whenever
9350: 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 2a this happens. *
9360: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
9370: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 3REF: Flags for
9380: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 the xAccess VFS
9390: 6d 65 74 68 6f 64 20 7b 48 31 31 31 39 30 7d 20 method {H11190}
93a0: 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 7b <H11140>.**.** {
93b0: 48 31 31 31 39 31 7d 20 54 68 65 73 65 20 69 6e H11191} These in
93c0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 teger constants
93d0: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 can be used as t
93e0: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
93f0: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 er to.** the xAc
9400: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 cess method of a
9410: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 n [sqlite3_vfs]
9420: 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 object. {END} T
9430: 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a hey determine.**
9440: 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 what kind of pe
9450: 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 rmissions the xA
9460: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 ccess method is
9470: 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 looking for..**
9480: 7b 48 31 31 31 39 32 7d 20 57 69 74 68 20 53 51 {H11192} With SQ
9490: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 LITE_ACCESS_EXIS
94a0: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 TS, the xAccess
94b0: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 method.** simply
94c0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 checks whether
94d0: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e the file exists.
94e0: 0a 2a 2a 20 7b 48 31 31 31 39 33 7d 20 57 69 74 .** {H11193} Wit
94f0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
9500: 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 READWRITE, the x
9510: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a Access method.**
9520: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 checks whether
9530: 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68 the file is both
9540: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 readable and wr
9550: 69 74 61 62 6c 65 2e 0a 2a 2a 20 7b 48 31 31 31 itable..** {H111
9560: 39 34 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f 94} With SQLITE_
9570: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 ACCESS_READ, the
9580: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a xAccess method.
9590: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 ** checks whethe
95a0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 r the file is re
95b0: 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 adable..*/.#defi
95c0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 ne SQLITE_ACCESS
95d0: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 _EXISTS 0.#de
95e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 fine SQLITE_ACCE
95f0: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 SS_READWRITE 1.#
9600: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
9610: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 CESS_READ 2
9620: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
9630: 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 : Initialize The
9640: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 SQLite Library
9650: 7b 48 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30 {H10130} <S20000
9660: 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 ><S30100>.**.**
9670: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
9680: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 ialize() routine
9690: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 initializes the
96a0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 .** SQLite libra
96b0: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 ry. The sqlite3
96c0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 _shutdown() rout
96d0: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 ine.** deallocat
96e0: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 es any resources
96f0: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 that were alloc
9700: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ated by sqlite3_
9710: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a initialize()..**
9720: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 .** A call to sq
9730: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
9740: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 () is an "effect
9750: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 ive" call if it
9760: 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 is.** the first
9770: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 time sqlite3_ini
9780: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 tialize() is inv
9790: 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 oked during the
97a0: 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 lifetime of.** t
97b0: 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 he process, or i
97c0: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 f it is the firs
97d0: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 t time sqlite3_i
97e0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 nitialize() is i
97f0: 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 nvoked.** follow
9800: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 ing a call to sq
9810: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
9820: 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 . Only an effec
9830: 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 tive call.** of
9840: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9850: 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e ze() does any in
9860: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 itialization. A
9870: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a ll other calls.*
9880: 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e * are harmless n
9890: 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f o-ops..**.** Amo
98a0: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c ng other things,
98b0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
98c0: 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f ize() shall invo
98d0: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 ke.** sqlite3_os
98e0: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 _init(). Simila
98f0: 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 rly, sqlite3_shu
9900: 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c tdown().** shall
9910: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
9920: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 os_end()..**.**
9930: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
9940: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 ialize() routine
9950: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f returns SQLITE_
9960: 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a OK on success..*
9970: 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 * If for some re
9980: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e ason, sqlite3_in
9990: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e itialize() is un
99a0: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 able to initiali
99b0: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 ze.** the librar
99c0: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 y (perhaps it is
99d0: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
99e0: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 ate a needed res
99f0: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 ource such.** as
9a00: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 a mutex) it ret
9a10: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 urns an [error c
9a20: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 ode] other than
9a30: 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a SQLITE_OK..**.**
9a40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 The sqlite3_ini
9a50: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e tialize() routin
9a60: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 e is called inte
9a70: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f rnally by many o
9a80: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 ther.** SQLite i
9a90: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 nterfaces so tha
9aa0: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e t an application
9ab0: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f usually does no
9ac0: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 t need to.** inv
9ad0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 oke sqlite3_init
9ae0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c ialize() directl
9af0: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c y. For example,
9b00: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
9b10: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 ].** calls sqlit
9b20: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
9b30: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 so the SQLite li
9b40: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 brary will be au
9b50: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 tomatically.** i
9b60: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 nitialized when
9b70: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
9b80: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 is called if it
9b90: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 has not be init
9ba0: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 ialized.** alrea
9bb0: 64 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66 dy. However, if
9bc0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
9bd0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c led with the SQL
9be0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 ITE_OMIT_AUTOINI
9bf0: 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d T.** compile-tim
9c00: 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 e option, then t
9c10: 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c he automatic cal
9c20: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e ls to sqlite3_in
9c30: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 itialize().** ar
9c40: 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 e omitted and th
9c50: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
9c60: 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f st call sqlite3_
9c70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 initialize() dir
9c80: 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 ectly.** prior t
9c90: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 o using any othe
9ca0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
9cb0: 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d ce. For maximum
9cc0: 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a portability,.**
9cd0: 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 it is recommend
9ce0: 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 ed that applicat
9cf0: 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f ions always invo
9d00: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ke sqlite3_initi
9d10: 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 alize().** direc
9d20: 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 tly prior to usi
9d30: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c ng any other SQL
9d40: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ite interface.
9d50: 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a Future releases.
9d60: 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 ** of SQLite may
9d70: 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 require this.
9d80: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
9d90: 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 the behavior exh
9da0: 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 ibited.** when S
9db0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
9dc0: 64 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4f 4d d with SQLITE_OM
9dd0: 49 54 5f 41 55 54 4f 49 4e 49 54 20 6d 69 67 68 IT_AUTOINIT migh
9de0: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 t become the.**
9df0: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 default behavior
9e00: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 in some future
9e10: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
9e20: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c e..**.** The sql
9e30: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 ite3_os_init() r
9e40: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 outine does oper
9e50: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 ating-system spe
9e60: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c cific.** initial
9e70: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 ization of the S
9e80: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 QLite library.
9e90: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 The sqlite3_os_e
9ea0: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 nd().** routine
9eb0: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 undoes the effec
9ec0: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f t of sqlite3_os_
9ed0: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c init(). Typical
9ee0: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 tasks.** perfor
9ef0: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 med by these rou
9f00: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c tines include al
9f10: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c location or deal
9f20: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 location.** of s
9f30: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c tatic resources,
9f40: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
9f50: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 of global variab
9f60: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 les,.** setting
9f70: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 up a default [sq
9f80: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c lite3_vfs] modul
9f90: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 e, or setting up
9fa0: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f .** a default co
9fb0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e nfiguration usin
9fc0: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 g [sqlite3_confi
9fd0: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 g()]..**.** The
9fe0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
9ff0: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 ld never invoke
a000: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f either sqlite3_o
a010: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 s_init().** or s
a020: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 qlite3_os_end()
a030: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 directly. The a
a040: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
a050: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a d only invoke.**
a060: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
a070: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ize() and sqlite
a080: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 3_shutdown(). T
a090: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e he sqlite3_os_in
a0a0: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 it().** interfac
a0b0: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f e is called auto
a0c0: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c matically by sql
a0d0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
a0e0: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ) and.** sqlite3
a0f0: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c _os_end() is cal
a100: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 led by sqlite3_s
a110: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 hutdown(). Appr
a120: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 opriate.** imple
a130: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 mentations for s
a140: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
a150: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f and sqlite3_os_
a160: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 end().** are bui
a170: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 lt into SQLite w
a180: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c hen it is compil
a190: 65 64 20 66 6f 72 20 75 6e 69 78 2c 20 77 69 6e ed for unix, win
a1a0: 64 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a dows, or os/2..*
a1b0: 2a 20 57 68 65 6e 20 62 75 69 6c 74 20 66 6f 72 * When built for
a1c0: 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 other platforms
a1d0: 20 28 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 (using the SQLI
a1e0: 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 20 63 6f TE_OS_OTHER=1 co
a1f0: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 mpile-time.** op
a200: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 tion) the applic
a210: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c ation must suppl
a220: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 y a suitable imp
a230: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a lementation for.
a240: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e ** sqlite3_os_in
a250: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 it() and sqlite3
a260: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 _os_end(). An a
a270: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c pplication-suppl
a280: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 ied.** implement
a290: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 ation of sqlite3
a2a0: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 _os_init() or sq
a2b0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
a2c0: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 53 51 * must return SQ
a2d0: 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 LITE_OK on succe
a2e0: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 ss and some othe
a2f0: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 r [error code] u
a300: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a pon.** failure..
a310: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 */.int sqlite3_i
a320: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b nitialize(void);
a330: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 .int sqlite3_shu
a340: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 tdown(void);.int
a350: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
a360: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 (void);.int sqli
a370: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 te3_os_end(void)
a380: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
a390: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 F: Configuring T
a3a0: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 he SQLite Librar
a3b0: 79 20 7b 48 31 30 31 34 35 7d 20 3c 53 32 30 30 y {H10145} <S200
a3c0: 30 30 3e 3c 53 33 30 32 30 30 3e 0a 2a 2a 0a 2a 00><S30200>.**.*
a3d0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
a3e0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 nfig() interface
a3f0: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 is used to make
a400: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 global configur
a410: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 ation.** changes
a420: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 to SQLite in or
a430: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 der to tune SQLi
a440: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 te to the specif
a450: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 ic needs of.** t
a460: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 he application.
a470: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e The default con
a480: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 figuration is re
a490: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f commended for mo
a4a0: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f st.** applicatio
a4b0: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 ns and so this r
a4c0: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c outine is usuall
a4d0: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e y not necessary.
a4e0: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 It is.** provi
a4f0: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 ded to support r
a500: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 are applications
a510: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 with unusual ne
a520: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 eds..**.** The s
a530: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
a540: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 interface is not
a550: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 threadsafe. Th
a560: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a e application.**
a570: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 must insure tha
a580: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 t no other SQLit
a590: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 e interfaces are
a5a0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 invoked by othe
a5b0: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 r.** threads whi
a5c0: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 le sqlite3_confi
a5d0: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 g() is running.
a5e0: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 Furthermore, sq
a5f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a lite3_config().*
a600: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e * may only be in
a610: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c voked prior to l
a620: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a ibrary initializ
a630: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b ation using.** [
a640: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
a650: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 ze()] or after s
a660: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 hutdown by [sqli
a670: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e te3_shutdown()].
a680: 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 .** Note, howeve
a690: 72 2c 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f r, that sqlite3_
a6a0: 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 config() can be
a6b0: 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f called as part o
a6c0: 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 f the.** impleme
a6d0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 ntation of an ap
a6e0: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
a6f0: 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e d [sqlite3_os_in
a700: 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 it()]..**.** The
a710: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
a720: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 to sqlite3_confi
a730: 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 g() is an intege
a740: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e r.** [SQLITE_CON
a750: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
a760: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e | configuration
a770: 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 option] that de
a780: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 termines.** what
a790: 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c property of SQL
a7a0: 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e ite is to be con
a7b0: 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 figured. Subseq
a7c0: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a uent arguments.*
a7d0: 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 * vary depending
a7e0: 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f on the [SQLITE_
a7f0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
a800: 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 EAD | configurat
a810: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 ion option].** i
a820: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
a830: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e ment..**.** When
a840: 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e a configuration
a850: 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 option is set,
a860: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
a870: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f returns SQLITE_
a880: 4f 4b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 OK..** If the op
a890: 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 tion is unknown
a8a0: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 or SQLite is una
a8b0: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f ble to set the o
a8c0: 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 ption.** then th
a8d0: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
a8e0: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 ns a non-zero [e
a8f0: 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a rror code]..**.*
a900: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
a910: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 nfig() interface
a920: 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 is considered e
a930: 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 20 74 xperimental in t
a940: 68 61 74 0a 2a 2a 20 6e 65 77 20 63 6f 6e 66 69 hat.** new confi
a950: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
a960: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
a970: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
a980: 20 61 6e 64 20 65 78 69 73 74 69 6e 67 0a 2a 2a and existing.**
a990: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
a9a0: 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 64 69 ptions may be di
a9b0: 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 6d 6f scontinued or mo
a9c0: 64 69 66 69 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 dified..*/.int s
a9d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e qlite3_config(in
a9e0: 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t, ...);../*.**
a9f0: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 CAPI3REF: Memory
aa00: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 Allocation Rout
aa10: 69 6e 65 73 20 7b 48 31 30 31 35 35 7d 20 3c 53 ines {H10155} <S
aa20: 32 30 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 20120>.**.** An
aa30: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
aa40: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 object defines
aa50: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 the interface be
aa60: 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 tween SQLite.**
aa70: 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 and low-level me
aa80: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
aa90: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
aaa0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 This object is u
aab0: 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 sed in only one
aac0: 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c place in the SQL
aad0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ite interface..*
aae0: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * A pointer to a
aaf0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
ab00: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 is object is the
ab10: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
ab20: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
ab30: 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 )] when the conf
ab40: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
ab50: 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 is.** [SQLITE_C
ab60: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 ONFIG_MALLOC].
ab70: 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 By creating an i
ab80: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
ab90: 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 object.** and pa
aba0: 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c ssing it to [sql
abb0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 64 ite3_config()] d
abc0: 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 uring configurat
abd0: 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 ion, an.** appli
abe0: 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 cation can speci
abf0: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 fy an alternativ
ac00: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
ac10: 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a ion subsystem.**
ac20: 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 for SQLite to u
ac30: 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 se for all of it
ac40: 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 s dynamic memory
ac50: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f needs..**.** No
ac60: 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 te that SQLite c
ac70: 6f 6d 65 73 20 77 69 74 68 20 61 20 62 75 69 6c omes with a buil
ac80: 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f t-in memory allo
ac90: 63 61 74 6f 72 20 74 68 61 74 20 69 73 0a 2a 2a cator that is.**
aca0: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 perfectly adequ
acb0: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 ate for the over
acc0: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 whelming majorit
acd0: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e y of application
ace0: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 s.** and that th
acf0: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c is object is onl
ad00: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 y useful to a ti
ad10: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 ny minority of a
ad20: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 pplications.** w
ad30: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 ith specialized
ad40: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
ad50: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 n requirements.
ad60: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a This object is.
ad70: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 ** also used dur
ad80: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 ing testing of S
ad90: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 QLite in order t
ada0: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 o specify an alt
adb0: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f ernative.** memo
adc0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 ry allocator tha
add0: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f t simulates memo
ade0: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 ry out-of-memory
adf0: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a conditions in.*
ae00: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 * order to verif
ae10: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 y that SQLite re
ae20: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c covers gracefull
ae30: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 y from such.** c
ae40: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a onditions..**.**
ae50: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 46 The xMalloc, xF
ae60: 72 65 65 2c 20 61 6e 64 20 78 52 65 61 6c 6c 6f ree, and xReallo
ae70: 63 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 c methods must w
ae80: 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 ork like the.**
ae90: 6d 61 6c 6c 6f 63 28 29 2c 20 66 72 65 65 28 29 malloc(), free()
aea0: 2c 20 61 6e 64 20 72 65 61 6c 6c 6f 63 28 29 20 , and realloc()
aeb0: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 functions from t
aec0: 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72 he standard libr
aed0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 ary..**.** xSize
aee0: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 should return t
aef0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a he allocated siz
af00: 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c e of a memory al
af10: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 location.** prev
af20: 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 iously obtained
af30: 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 from xMalloc or
af40: 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 xRealloc. The a
af50: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a llocated size.**
af60: 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 is always at le
af70: 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 ast as big as th
af80: 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 e requested size
af90: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 but may be larg
afa0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 er..**.** The xR
afb0: 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 oundup method re
afc0: 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 turns what would
afd0: 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 be the allocate
afe0: 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d d size of.** a m
aff0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
b000: 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 given a particu
b010: 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 lar requested si
b020: 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 ze. Most memory
b030: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 .** allocators r
b040: 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 ound up memory a
b050: 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 llocations at le
b060: 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 ast to the next
b070: 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 multiple.** of 8
b080: 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f . Some allocato
b090: 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 rs round up to a
b0a0: 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 larger multiple
b0b0: 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f or to a power o
b0c0: 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 f 2..**.** The x
b0d0: 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 Init method init
b0e0: 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f ializes the memo
b0f0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 ry allocator. (
b100: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 For example,.**
b110: 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 it might allocat
b120: 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 e any require mu
b130: 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c texes or initial
b140: 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 ize internal dat
b150: 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e a.** structures.
b160: 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 The xShutdown
b170: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 method is invoke
b180: 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 d (indirectly) b
b190: 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 y.** [sqlite3_sh
b1a0: 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 utdown()] and sh
b1b0: 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 ould deallocate
b1c0: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 any resources ac
b1d0: 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e quired.** by xIn
b1e0: 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 it. The pAppDat
b1f0: 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 a pointer is use
b200: 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 d as the only pa
b210: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 rameter to.** xI
b220: 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 nit and xShutdow
b230: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 n..*/.typedef st
b240: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d ruct sqlite3_mem
b250: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 _methods sqlite3
b260: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 _mem_methods;.st
b270: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d ruct sqlite3_mem
b280: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 _methods {. voi
b290: 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e d *(*xMalloc)(in
b2a0: 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d t); /* M
b2b0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
b2c0: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 function */. v
b2d0: 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 oid (*xFree)(voi
b2e0: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a d*); /*
b2f0: 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c Free a prior al
b300: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f location */. vo
b310: 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 id *(*xRealloc)(
b320: 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 void*,int); /*
b330: 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 Resize an alloca
b340: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a tion */. int (*
b350: 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 xSize)(void*);
b360: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 /* Retu
b370: 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 rn the size of a
b380: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a n allocation */.
b390: 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 int (*xRoundup
b3a0: 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 )(int);
b3b0: 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 /* Round up req
b3c0: 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c uest size to all
b3d0: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a ocation size */.
b3e0: 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 int (*xInit)(v
b3f0: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 oid*);
b400: 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 /* Initialize t
b410: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
b420: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a tor */. void (*
b430: 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a xShutdown)(void*
b440: 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 ); /* Deini
b450: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f tialize the memo
b460: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a ry allocator */.
b470: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 void *pAppData
b480: 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ;
b490: 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 /* Argument to
b4a0: 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 xInit() and xShu
b4b0: 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f tdown() */.};../
b4c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
b4d0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 onfiguration Opt
b4e0: 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d 20 3c 53 ions {H10160} <S
b4f0: 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20000>.**.** The
b500: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 se constants are
b510: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 the available i
b520: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 nteger configura
b530: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 tion options tha
b540: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 t.** can be pass
b550: 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ed as the first
b560: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
b570: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
b580: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a )] interface..**
b590: 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 .** New configur
b5a0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 ation options ma
b5b0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
b5c0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
b5d0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 SQLite..** Exis
b5e0: 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 ting configurati
b5f0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 on options might
b600: 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 be discontinued
b610: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a . Applications.
b620: 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 ** should check
b630: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 the return code
b640: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f from [sqlite3_co
b650: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 nfig()] to make
b660: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 sure that.** the
b670: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 call worked. T
b680: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 he [sqlite3_conf
b690: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 ig()] interface
b6a0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a will return a.**
b6b0: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 non-zero [error
b6c0: 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 code] if a disc
b6d0: 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 ontinued or unsu
b6e0: 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 pported configur
b6f0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 ation option.**
b700: 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a is invoked..**.*
b710: 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 * <dl>.** <dt>SQ
b720: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
b730: 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a LETHREAD</dt>.**
b740: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
b750: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
b760: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 his option. Thi
b770: 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 s option disable
b780: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e s.** all mutexin
b790: 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 g and puts SQLit
b7a0: 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 e into a mode wh
b7b0: 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 ere it can only
b7c0: 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 be used.** by a
b7d0: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f single thread.</
b7e0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
b7f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
b800: 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 ITHREAD</dt>.**
b810: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f <dd>There are no
b820: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
b830: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 is option. This
b840: 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 option disables
b850: 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 .** mutexing on
b860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
b870: 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 tion] and [prepa
b880: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f red statement] o
b890: 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 bjects..** The a
b8a0: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 pplication is re
b8b0: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 sponsible for se
b8c0: 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 rializing access
b8d0: 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 to.** [database
b8e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e connections] an
b8f0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
b900: 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 ements]. But ot
b910: 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 her mutexes.** a
b920: 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 re enabled so th
b930: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 at SQLite will b
b940: 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e e safe to use in
b950: 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 a multi-threade
b960: 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 d.** environment
b970: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
b980: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
b990: 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a ERIALIZED</dt>.*
b9a0: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 * <dd>There are
b9b0: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 no arguments to
b9c0: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 this option. Th
b9d0: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 is option enable
b9e0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 s.** all mutexes
b9f0: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 including the r
ba00: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 ecursive.** mute
ba10: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 xes on [database
ba20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 connection] and
ba30: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
ba40: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a ment] objects..*
ba50: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 * In this mode (
ba60: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 which is the def
ba70: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 ault when SQLite
ba80: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
ba90: 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 h.** [SQLITE_THR
baa0: 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 EADSAFE=1]) the
bab0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 SQLite library w
bac0: 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 ill itself seria
bad0: 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 lize access.** t
bae0: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e o [database conn
baf0: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 ections] and [pr
bb00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
bb10: 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a s] so that the.*
bb20: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 * application is
bb30: 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 free to use the
bb40: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 same [database
bb50: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 connection] or t
bb60: 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 he.** same [prep
bb70: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
bb80: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 in different thr
bb90: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 eads at the same
bba0: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 70 3e time..**.** <p>
bbb0: 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 This configurati
bbc0: 6f 6e 20 6f 70 74 69 6f 6e 20 6d 65 72 65 6c 79 on option merely
bbd0: 20 73 65 74 73 20 74 68 65 20 64 65 66 61 75 6c sets the defaul
bbe0: 74 20 6d 75 74 65 78 20 0a 2a 2a 20 62 65 68 61 t mutex .** beha
bbf0: 76 69 6f 72 20 74 6f 20 73 65 72 69 61 6c 69 7a vior to serializ
bc00: 65 20 61 63 63 65 73 73 20 74 6f 20 5b 64 61 74 e access to [dat
bc10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
bc20: 73 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 0a s]. Individual.
bc30: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
bc40: 6e 65 63 74 69 6f 6e 73 5d 20 63 61 6e 20 6f 76 nections] can ov
bc50: 65 72 72 69 64 65 20 74 68 69 73 20 73 65 74 74 erride this sett
bc60: 69 6e 67 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 ing.** using the
bc70: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f [SQLITE_OPEN_NO
bc80: 4d 55 54 45 58 5d 20 66 6c 61 67 20 74 6f 20 5b MUTEX] flag to [
bc90: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
bca0: 29 5d 2e 3c 2f 70 3e 3c 2f 64 64 3e 0a 2a 2a 0a )].</p></dd>.**.
bcb0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
bcc0: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e NFIG_MALLOC</dt>
bcd0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
bce0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
bcf0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
bd00: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 h is a pointer t
bd10: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 o an.** instance
bd20: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
bd30: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 _mem_methods] st
bd40: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 ructure. The ar
bd50: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 gument specifies
bd60: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 .** alternative
bd70: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 low-level memory
bd80: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
bd90: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 ines to be used
bda0: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 in place of.** t
bdb0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
bdc0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 tion routines bu
bdd0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e ilt into SQLite.
bde0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
bdf0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
be00: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 TMALLOC</dt>.**
be10: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
be20: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
be30: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
be40: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
be50: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 .** instance of
be60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d the [sqlite3_mem
be70: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
be80: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ure. The [sqlit
be90: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a e3_mem_methods].
bea0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 ** structure is
beb0: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 filled with the
bec0: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 currently define
bed0: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 d memory allocat
bee0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a ion routines..**
bef0: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e This option can
bf00: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 be used to over
bf10: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 load the default
bf20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
bf30: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 on.** routines w
bf40: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 ith a wrapper th
bf50: 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d at simulations m
bf60: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
bf70: 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 failure or.** t
bf80: 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 racks memory usa
bf90: 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e ge, for example.
bfa0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
bfb0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
bfc0: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 MSTATUS</dt>.**
bfd0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
bfe0: 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 62 6f 6f takes single boo
bff0: 6c 65 61 6e 20 61 72 67 75 6d 65 6e 74 20 77 68 lean argument wh
c000: 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 ich enables or d
c010: 69 73 61 62 6c 65 73 0a 2a 2a 20 74 68 65 20 63 isables.** the c
c020: 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d ollection of mem
c030: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 ory allocation s
c040: 74 61 74 69 73 74 69 63 73 2e 20 20 57 68 65 6e tatistics. When
c050: 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 0a 2a disabled, the.*
c060: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 * following SQLi
c070: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 te interfaces be
c080: 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 come non-operati
c090: 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a onal:.** <ul>.
c0a0: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
c0b0: 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
c0c0: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c ].** <li> [sql
c0d0: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
c0e0: 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c water()].** <l
c0f0: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 i> [sqlite3_soft
c100: 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a _heap_limit()].*
c110: 2a 20 20 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 * <li> sqlite3
c120: 5f 6d 65 6d 6f 72 79 5f 73 74 61 74 75 73 28 29 _memory_status()
c130: 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c .** </ul>.** <
c140: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
c150: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
c160: 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ATCH</dt>.** <dd
c170: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 >This option spe
c180: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 cifies a static
c190: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 memory buffer th
c1a0: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 at SQLite can us
c1b0: 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 e for.** scratch
c1c0: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 memory. There
c1d0: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 are three argume
c1e0: 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 nts: A pointer
c1f0: 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 to the memory, t
c200: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 he.** size of ea
c210: 63 68 20 73 63 72 61 74 63 68 20 62 75 66 66 65 ch scratch buffe
c220: 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 r (sz), and the
c230: 6e 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72 number of buffer
c240: 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a s (N). The sz.*
c250: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 * argument must
c260: 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 be a multiple of
c270: 20 31 36 2e 20 54 68 65 20 66 69 72 73 74 0a 2a 16. The first.*
c280: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c * argument shoul
c290: 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c d point to an al
c2a0: 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c location of at l
c2b0: 65 61 73 74 20 28 73 7a 2b 34 29 2a 4e 20 62 79 east (sz+4)*N by
c2c0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a tes of memory..*
c2d0: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 * SQLite will us
c2e0: 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f e no more than o
c2f0: 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65 ne scratch buffe
c300: 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68 r at once per th
c310: 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 read, so.** N sh
c320: 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 ould be set to t
c330: 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 he expected maxi
c340: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 mum number of th
c350: 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a reads. The sz.*
c360: 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 * parameter shou
c370: 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20 74 68 ld be 6 times th
c380: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 e size of the la
c390: 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 rgest database p
c3a0: 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 age size..** Scr
c3b0: 61 74 63 68 20 62 75 66 66 65 72 73 20 61 72 65 atch buffers are
c3c0: 20 75 73 65 64 20 61 73 20 70 61 72 74 20 6f 66 used as part of
c3d0: 20 74 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e the btree balan
c3e0: 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 ce operation. I
c3f0: 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62 f.** The btree b
c400: 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64 alancer needs ad
c410: 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 ditional memory
c420: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 beyond what is p
c430: 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 rovided by.** sc
c440: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 6f 72 ratch buffers or
c450: 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62 if no scratch b
c460: 75 66 66 65 72 20 73 70 61 63 65 20 69 73 20 73 uffer space is s
c470: 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53 pecified, then S
c480: 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f QLite.** goes to
c490: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
c4a0: 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 ()] to obtain th
c4b0: 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 e memory it need
c4c0: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 s.</dd>.**.** <d
c4d0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
c4e0: 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a PAGECACHE</dt>.*
c4f0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f * <dd>This optio
c500: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 n specifies a st
c510: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 atic memory buff
c520: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 er that SQLite c
c530: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 an use for.** th
c540: 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 e database page
c550: 63 61 63 68 65 2e 20 20 54 68 65 72 65 20 61 72 cache. There ar
c560: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 e three argument
c570: 73 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 s: A pointer to
c580: 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 the.** memory, t
c590: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 he size of each
c5a0: 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 page buffer (sz)
c5b0: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 , and the number
c5c0: 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a of pages (N)..*
c5d0: 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e * The sz argumen
c5e0: 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 77 65 t must be a powe
c5f0: 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e r of two between
c600: 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 2e 20 512 and 32768.
c610: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 The first.** ar
c620: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f gument should po
c630: 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 int to an alloca
c640: 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 tion of at least
c650: 20 28 73 7a 2b 34 29 2a 4e 20 62 79 74 65 73 20 (sz+4)*N bytes
c660: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 of memory..** SQ
c670: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 Lite will use th
c680: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 e memory provide
c690: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 d by the first a
c6a0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 rgument to satis
c6b0: 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 fy its.** memory
c6c0: 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 needs for the f
c6d0: 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 irst N pages tha
c6e0: 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 t it adds to cac
c6f0: 68 65 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e he. If addition
c700: 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 al.** page cache
c710: 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 memory is neede
c720: 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 d beyond what is
c730: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 provided by thi
c740: 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a s option, then.*
c750: 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f * SQLite goes to
c760: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
c770: 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 ()] for the addi
c780: 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 tional storage s
c790: 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a pace.</dd>.**.**
c7a0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
c7b0: 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 IG_HEAP</dt>.**
c7c0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
c7d0: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 specifies a stat
c7e0: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 ic memory buffer
c7f0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
c800: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c l use.** for all
c810: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 of its dynamic
c820: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
c830: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 n needs beyond t
c840: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a hose provided.**
c850: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f for by [SQLITE_
c860: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 CONFIG_SCRATCH]
c870: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 and [SQLITE_CONF
c880: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a IG_PAGECACHE]..*
c890: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 * There are thre
c8a0: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 e arguments: A p
c8b0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 ointer to the me
c8c0: 6d 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72 mory, the number
c8d0: 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 of.** bytes in
c8e0: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 the memory buffe
c8f0: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d r, and the minim
c900: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 um allocation si
c910: 7a 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 66 ze. If.** the f
c920: 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 irst pointer (th
c930: 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 e memory pointer
c940: 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 ) is NULL, then
c950: 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a SQLite reverts.*
c960: 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 * to using its d
c970: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c efault memory al
c980: 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 locator (the sys
c990: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 tem malloc() imp
c9a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a lementation),.**
c9b0: 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 undoing any pri
c9c0: 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 or invocation of
c9d0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
c9e0: 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65 MALLOC]. If the
c9f0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 .** memory point
ca00: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 er is not NULL a
ca10: 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 nd either [SQLIT
ca20: 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 E_ENABLE_MEMSYS3
ca30: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ] or.** [SQLITE_
ca40: 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 ENABLE_MEMSYS5]
ca50: 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 are defined, the
ca60: 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 n the alternativ
ca70: 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f e memory.** allo
ca80: 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 cator is engaged
ca90: 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f to handle all o
caa0: 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 f SQLites memory
cab0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 allocation need
cac0: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 s.</dd>.**.** <d
cad0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
cae0: 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 MUTEX</dt>.** <d
caf0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 d>This option ta
cb00: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
cb10: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
cb20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a pointer to an.*
cb30: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 * instance of th
cb40: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
cb50: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
cb60: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 ure. The argume
cb70: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 nt specifies.**
cb80: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d alternative low-
cb90: 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 level mutex rout
cba0: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 ines to be used
cbb0: 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 in place.** the
cbc0: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 mutex routines b
cbd0: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 uilt into SQLite
cbe0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
cbf0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
cc00: 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 ETMUTEX</dt>.**
cc10: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
cc20: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
cc30: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
cc40: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
cc50: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 .** instance of
cc60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 the [sqlite3_mut
cc70: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 ex_methods] stru
cc80: 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b cture. The.** [
cc90: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
cca0: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 thods].** struct
ccb0: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 ure is filled wi
ccc0: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 th the currently
ccd0: 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 defined mutex r
cce0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 outines..** This
ccf0: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 option can be u
cd00: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 sed to overload
cd10: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 the default mute
cd20: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 x allocation.**
cd30: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 routines with a
cd40: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 wrapper used to
cd50: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 track mutex usag
cd60: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 e for performanc
cd70: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f e.** profiling o
cd80: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 r testing, for e
cd90: 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2f 0a xample.</dd>.*/.
cda0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
cdb0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
cdc0: 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f AD 1 /* nil */
cdd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
cde0: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
cdf0: 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a AD 2 /* nil *
ce00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
ce10: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a _CONFIG_SERIALIZ
ce20: 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 ED 3 /* nil
ce30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
ce40: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 E_CONFIG_MALLOC
ce50: 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 4 /* sql
ce60: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
ce70: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
ce80: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 ITE_CONFIG_GETMA
ce90: 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 LLOC 5 /* s
cea0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
ceb0: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
cec0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
ced0: 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a ATCH 6 /*
cee0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 void*, int sz,
cef0: 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 int N */.#define
cf00: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
cf10: 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 AGECACHE 7
cf20: 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a /* void*, int sz
cf30: 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 , int N */.#defi
cf40: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
cf50: 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 _HEAP 8
cf60: 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 /* void*, int
cf70: 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a nByte, int min *
cf80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
cf90: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
cfa0: 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c S 9 /* bool
cfb0: 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ean */.#define S
cfc0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
cfd0: 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a EX 10 /*
cfe0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d sqlite3_mutex_m
cff0: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 ethods* */.#defi
d000: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
d010: 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 _GETMUTEX 11
d020: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 /* sqlite3_mut
d030: 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 ex_methods* */.#
d040: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
d050: 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 NFIG_CHUNKALLOC
d060: 20 20 31 32 20 20 2f 2a 20 69 6e 74 20 74 68 72 12 /* int thr
d070: 65 73 68 6f 6c 64 20 2a 2f 0a 0a 0a 2f 2a 0a 2a eshold */.../*.*
d080: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 * CAPI3REF: Enab
d090: 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 le Or Disable Ex
d0a0: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f tended Result Co
d0b0: 64 65 73 20 7b 48 31 32 32 30 30 7d 20 3c 53 31 des {H12200} <S1
d0c0: 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0700>.**.** The
d0d0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
d0e0: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 _result_codes()
d0f0: 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 routine enables
d100: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a or disables the.
d110: 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
d120: 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 ult codes] featu
d130: 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54 68 re of SQLite. Th
d140: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c e extended resul
d150: 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 t.** codes are d
d160: 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
d170: 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 lt for historica
d180: 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 l compatibility
d190: 63 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e 0a considerations..
d1a0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
d1b0: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 31 7d :.**.** {H12201}
d1c0: 20 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62 Each new [datab
d1d0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
d1e0: 73 68 61 6c 6c 20 68 61 76 65 20 74 68 65 0a 2a shall have the.*
d1f0: 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 * [exte
d200: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
d210: 73 5d 20 66 65 61 74 75 72 65 20 64 69 73 61 62 s] feature disab
d220: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a led by default..
d230: 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 32 7d 20 54 **.** {H12202} T
d240: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 he [sqlite3_exte
d250: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
d260: 73 28 44 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 s(D,F)] interfac
d270: 65 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a e shall enable.*
d280: 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 * [exte
d290: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
d2a0: 73 5d 20 66 6f 72 20 74 68 65 20 20 5b 64 61 74 s] for the [dat
d2b0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
d2c0: 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ] D.**
d2d0: 69 66 20 74 68 65 20 46 20 70 61 72 61 6d 65 74 if the F paramet
d2e0: 65 72 20 69 73 20 74 72 75 65 2c 20 6f 72 20 64 er is true, or d
d2f0: 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20 46 isable them if F
d300: 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e is false..*/.in
d310: 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 t sqlite3_extend
d320: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 ed_result_codes(
d330: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e sqlite3*, int on
d340: 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 off);../*.** CAP
d350: 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 I3REF: Last Inse
d360: 72 74 20 52 6f 77 69 64 20 7b 48 31 32 32 32 30 rt Rowid {H12220
d370: 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a } <S10700>.**.**
d380: 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 Each entry in a
d390: 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 n SQLite table h
d3a0: 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 as a unique 64-b
d3b0: 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 it signed.** int
d3c0: 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 eger key called
d3d0: 74 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68 65 the "rowid". The
d3e0: 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 rowid is always
d3f0: 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 available.** as
d400: 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 an undeclared c
d410: 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 olumn named ROWI
d420: 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 D, OID, or _ROWI
d430: 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 D_ as long as th
d440: 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 ose.** names are
d450: 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 not also used b
d460: 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 y explicitly dec
d470: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 lared columns. I
d480: 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 f.** the table h
d490: 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 as a column of t
d4a0: 79 70 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d ype INTEGER PRIM
d4b0: 41 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68 61 ARY KEY then tha
d4c0: 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 t column.** is a
d4d0: 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 nother alias for
d4e0: 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a the rowid..**.*
d4f0: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 * This routine r
d500: 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 eturns the rowid
d510: 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 of the most rec
d520: 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 ent.** successfu
d530: 6c 20 49 4e 53 45 52 54 20 69 6e 74 6f 20 74 68 l INSERT into th
d540: 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 e database from
d550: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
d560: 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 nnection].** in
d570: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
d580: 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 nt. If no succe
d590: 73 73 66 75 6c 20 49 4e 53 45 52 54 73 0a 2a 2a ssful INSERTs.**
d5a0: 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 have ever occur
d5b0: 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 red on that data
d5c0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c base connection,
d5d0: 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 zero is returne
d5e0: 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 d..**.** If an I
d5f0: 4e 53 45 52 54 20 6f 63 63 75 72 73 20 77 69 74 NSERT occurs wit
d600: 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 hin a trigger, t
d610: 68 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f 66 hen the rowid of
d620: 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a the inserted.**
d630: 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 row is returned
d640: 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 by this routine
d650: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 as long as the
d660: 74 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 trigger is runni
d670: 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 ng..** But once
d680: 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d the trigger term
d690: 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 inates, the valu
d6a0: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 e returned by th
d6b0: 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 is routine.** re
d6c0: 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 verts to the las
d6d0: 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 t value inserted
d6e0: 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 before the trig
d6f0: 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a ger fired..**.**
d700: 20 41 6e 20 49 4e 53 45 52 54 20 74 68 61 74 20 An INSERT that
d710: 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 fails due to a c
d720: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 onstraint violat
d730: 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 ion is not a.**
d740: 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 successful INSER
d750: 54 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 T and does not c
d760: 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 hange the value
d770: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 returned by this
d780: 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 .** routine. Th
d790: 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 us INSERT OR FAI
d7a0: 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e L, INSERT OR IGN
d7b0: 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 ORE, INSERT OR R
d7c0: 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 OLLBACK,.** and
d7d0: 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 INSERT OR ABORT
d7e0: 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 make no changes
d7f0: 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 to the return va
d800: 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 lue of this.** r
d810: 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 outine when thei
d820: 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c r insertion fail
d830: 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20 s. When INSERT
d840: 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e OR REPLACE.** en
d850: 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 counters a const
d860: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c raint violation,
d870: 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 it does not fai
d880: 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 l. The.** INSER
d890: 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 T continues to c
d8a0: 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 ompletion after
d8b0: 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 deleting rows th
d8c0: 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 at caused.** the
d8d0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 constraint prob
d8e0: 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 lem so INSERT OR
d8f0: 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c REPLACE will al
d900: 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 ways change.** t
d910: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
d920: 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 of this interfac
d930: 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 e..**.** For the
d940: 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 purposes of thi
d950: 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 49 4e s routine, an IN
d960: 53 45 52 54 20 69 73 20 63 6f 6e 73 69 64 65 72 SERT is consider
d970: 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 ed to.** be succ
d980: 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 essful even if i
d990: 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c t is subsequentl
d9a0: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a y rolled back..*
d9b0: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
d9c0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 31 7d 20 .**.** {H12221}
d9d0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 The [sqlite3_las
d9e0: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 t_insert_rowid()
d9f0: 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 ] function retur
da00: 6e 73 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 ns the rowid.**
da10: 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 of the
da20: 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 most recent succ
da30: 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20 70 65 essful INSERT pe
da40: 72 66 6f 72 6d 65 64 20 6f 6e 20 74 68 65 20 73 rformed on the s
da50: 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ame.**
da60: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
da70: 74 69 6f 6e 5d 20 61 6e 64 20 77 69 74 68 69 6e tion] and within
da80: 20 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69 67 the same or hig
da90: 68 65 72 20 6c 65 76 65 6c 0a 2a 2a 20 20 20 20 her level.**
daa0: 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f trigger co
dab0: 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 ntext, or zero i
dac0: 66 20 74 68 65 72 65 20 68 61 76 65 20 62 65 65 f there have bee
dad0: 6e 20 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67 20 n no qualifying
dae0: 69 6e 73 65 72 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b inserts..**.** {
daf0: 48 31 32 32 32 33 7d 20 54 68 65 20 5b 73 71 6c H12223} The [sql
db00: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
db10: 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69 _rowid()] functi
db20: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a on returns the.*
db30: 2a 20 20 20 20 20 20 20 20 20 20 73 61 6d 65 20 * same
db40: 76 61 6c 75 65 20 77 68 65 6e 20 63 61 6c 6c 65 value when calle
db50: 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
db60: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 0a trigger context.
db70: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d 6d 65 ** imme
db80: 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 61 diately before a
db90: 6e 64 20 61 66 74 65 72 20 61 20 52 4f 4c 4c 42 nd after a ROLLB
dba0: 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d ACK..**.** ASSUM
dbb0: 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 PTIONS:.**.** {A
dbc0: 31 32 32 33 32 7d 20 49 66 20 61 20 73 65 70 61 12232} If a sepa
dbd0: 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 rate thread perf
dbe0: 6f 72 6d 73 20 61 20 6e 65 77 20 49 4e 53 45 52 orms a new INSER
dbf0: 54 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a T on the same.**
dc00: 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 databa
dc10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 se connection wh
dc20: 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ile the [sqlite3
dc30: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
dc40: 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 id()].**
dc50: 20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 function is ru
dc60: 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 nning and thus c
dc70: 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 hanges the last
dc80: 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a insert rowid,.**
dc90: 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 then t
dca0: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
dcb0: 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 d by [sqlite3_la
dcc0: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
dcd0: 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 )] is.**
dce0: 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 unpredictable
dcf0: 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 and might not eq
dd00: 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f ual either the o
dd10: 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a ld or the new.**
dd20: 20 20 20 20 20 20 20 20 20 20 6c 61 73 74 20 69 last i
dd30: 6e 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f 0a nsert rowid..*/.
dd40: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
dd50: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
dd60: 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a t_rowid(sqlite3*
dd70: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
dd80: 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 EF: Count The Nu
dd90: 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 mber Of Rows Mod
dda0: 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d 20 3c ified {H12240} <
ddb0: 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S10600>.**.** Th
ddc0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
ddd0: 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
dde0: 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 f database rows
ddf0: 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 that were change
de00: 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 d.** or inserted
de10: 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 or deleted by t
de20: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 he most recently
de30: 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 completed SQL s
de40: 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 tatement.** on t
de50: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
de60: 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 nection] specifi
de70: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
de80: 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e parameter..** On
de90: 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 ly changes that
dea0: 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 are directly spe
deb0: 63 69 66 69 65 64 20 62 79 20 74 68 65 20 49 4e cified by the IN
dec0: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a SERT, UPDATE,.**
ded0: 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 or DELETE state
dee0: 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 ment are counted
def0: 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 . Auxiliary cha
df00: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a nges caused by.*
df10: 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20 6e * triggers are n
df20: 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65 20 ot counted. Use
df30: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 the [sqlite3_tot
df40: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 al_changes()] fu
df50: 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e nction.** to fin
df60: 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 d the total numb
df70: 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e er of changes in
df80: 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 cluding changes
df90: 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 caused by trigge
dfa0: 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 rs..**.** A "row
dfb0: 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 change" is a ch
dfc0: 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 ange to a single
dfd0: 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 row of a single
dfe0: 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 table.** caused
dff0: 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 by an INSERT, D
e000: 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 ELETE, or UPDATE
e010: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 statement. Row
e020: 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 s that.** are ch
e030: 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66 anged as side ef
e040: 66 65 63 74 73 20 6f 66 20 52 45 50 4c 41 43 45 fects of REPLACE
e050: 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f constraint reso
e060: 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 lution,.** rollb
e070: 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 ack, ABORT proce
e080: 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 41 42 4c ssing, DROP TABL
e090: 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 E, or by any oth
e0a0: 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 er.** mechanisms
e0b0: 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 do not count as
e0c0: 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e direct row chan
e0d0: 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 ges..**.** A "tr
e0e0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 igger context" i
e0f0: 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 s a scope of exe
e100: 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 cution that begi
e110: 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 ns and.** ends w
e120: 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f ith the script o
e130: 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 4d 6f f a trigger. Mo
e140: 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 st SQL statement
e150: 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 s are.** evaluat
e160: 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e ed outside of an
e170: 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 y trigger. This
e180: 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 is the "top lev
e190: 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 el".** trigger c
e1a0: 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 ontext. If a tr
e1b0: 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d igger fires from
e1c0: 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 the top level,
e1d0: 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 a.** new trigger
e1e0: 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 context is ente
e1f0: 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 red for the dura
e200: 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 tion of that one
e210: 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 .** trigger. Su
e220: 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65 btriggers create
e230: 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 subcontexts for
e240: 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e their duration.
e250: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b .**.** Calling [
e260: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
e270: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 or [sqlite3_step
e280: 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 ()] recursively
e290: 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 does.** not crea
e2a0: 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 te a new trigger
e2b0: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 context..**.**
e2c0: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
e2d0: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
e2e0: 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 of direct row c
e2f0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a hanges in the.**
e300: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 most recent INS
e310: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 ERT, UPDATE, or
e320: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 DELETE statement
e330: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 within the same
e340: 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 .** trigger cont
e350: 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73 2c ext..**.** Thus,
e360: 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f when called fro
e370: 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c m the top level,
e380: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 this function r
e390: 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 eturns the.** nu
e3a0: 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 mber of changes
e3b0: 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 in the most rece
e3c0: 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 nt INSERT, UPDAT
e3d0: 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 E, or DELETE.**
e3e0: 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 that also occurr
e3f0: 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 ed at the top le
e400: 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74 68 65 vel. Within the
e410: 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 body of a trigg
e420: 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 er,.** the sqlit
e430: 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 e3_changes() int
e440: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 erface can be ca
e450: 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 lled to find the
e460: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 number of.** ch
e470: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 anges in the mos
e480: 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c t recently compl
e490: 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 eted INSERT, UPD
e4a0: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a ATE, or DELETE.*
e4b0: 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 * statement with
e4c0: 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 in the body of t
e4d0: 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e he same trigger.
e4e0: 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 .** However, the
e4f0: 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 number returned
e500: 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 does not includ
e510: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 e changes.** cau
e520: 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 sed by subtrigge
e530: 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 rs since those h
e540: 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f ave their own co
e550: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c ntext..**.** SQL
e560: 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 ite implements t
e570: 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 he command "DELE
e580: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 TE FROM table" w
e590: 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 ithout a WHERE c
e5a0: 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 lause.** by drop
e5b0: 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 ping and recreat
e5c0: 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 ing the table.
e5d0: 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 (This is much fa
e5e0: 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a ster than going.
e5f0: 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 ** through and d
e600: 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 eleting individu
e610: 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d al elements from
e620: 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 the table.) Be
e630: 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a cause of this.**
e640: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 optimization, t
e650: 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 he deletions in
e660: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 "DELETE FROM tab
e670: 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 le" are not row
e680: 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 changes and.** w
e690: 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 ill not be count
e6a0: 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 ed by the sqlite
e6b0: 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 3_changes() or [
e6c0: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
e6d0: 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 anges()].** func
e6e0: 74 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 tions, regardles
e6f0: 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 s of the number
e700: 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 of elements that
e710: 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 were originally
e720: 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c 65 .** in the table
e730: 2e 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 . To get an acc
e740: 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 urate count of t
e750: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 he number of row
e760: 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a s deleted, use.*
e770: 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 * "DELETE FROM t
e780: 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e able WHERE 1" in
e790: 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 stead..**.** INV
e7a0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
e7b0: 48 31 32 32 34 31 7d 20 54 68 65 20 5b 73 71 6c H12241} The [sql
e7c0: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 ite3_changes()]
e7d0: 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 function shall r
e7e0: 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 eturn the number
e7f0: 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 of.**
e800: 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 row changes caus
e810: 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 ed by the most r
e820: 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 ecent INSERT, UP
e830: 44 41 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20 20 DATE,.**
e840: 20 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 or DELETE stat
e850: 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d ement on the sam
e860: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
e870: 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 ction and.**
e880: 20 20 20 20 20 20 77 69 74 68 69 6e 20 74 68 65 within the
e890: 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20 same or higher
e8a0: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c trigger context,
e8b0: 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 or zero if ther
e8c0: 65 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 e have.**
e8d0: 20 20 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20 not been any
e8e0: 71 75 61 6c 69 66 79 69 6e 67 20 72 6f 77 20 63 qualifying row c
e8f0: 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 hanges..**.** {H
e900: 31 32 32 34 33 7d 20 53 74 61 74 65 6d 65 6e 74 12243} Statement
e910: 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 s of the form "D
e920: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 ELETE FROM table
e930: 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a name" with no.**
e940: 20 20 20 20 20 20 20 20 20 20 57 48 45 52 45 20 WHERE
e950: 63 6c 61 75 73 65 20 73 68 61 6c 6c 20 63 61 75 clause shall cau
e960: 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 se subsequent ca
e970: 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 lls to.**
e980: 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e [sqlite3_chan
e990: 67 65 73 28 29 5d 20 74 6f 20 72 65 74 75 72 6e ges()] to return
e9a0: 20 7a 65 72 6f 2c 20 72 65 67 61 72 64 6c 65 73 zero, regardles
e9b0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 s of the.**
e9c0: 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 72 number of r
e9d0: 6f 77 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 ows originally i
e9e0: 6e 20 74 68 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a n the table..**.
e9f0: 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a ** ASSUMPTIONS:.
ea00: 2a 2a 0a 2a 2a 20 7b 41 31 32 32 35 32 7d 20 49 **.** {A12252} I
ea10: 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 f a separate thr
ea20: 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 ead makes change
ea30: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 s on the same da
ea40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
ea50: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 n.** wh
ea60: 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 ile [sqlite3_cha
ea70: 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 nges()] is runni
ea80: 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 ng then the valu
ea90: 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 e returned.**
eaa0: 20 20 20 20 20 20 20 69 73 20 75 6e 70 72 65 64 is unpred
eab0: 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 ictable and not
eac0: 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 meaningful..*/.i
ead0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 nt sqlite3_chang
eae0: 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f es(sqlite3*);../
eaf0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
eb00: 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 otal Number Of R
eb10: 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 ows Modified {H1
eb20: 32 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2260} <S10600>.*
eb30: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
eb40: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e on returns the n
eb50: 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 umber of row cha
eb60: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49 nges caused by I
eb70: 4e 53 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54 45 NSERT,.** UPDATE
eb80: 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 or DELETE state
eb90: 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 ments since the
eba0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
ebb0: 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 tion] was opened
ebc0: 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 69 ..** The count i
ebd0: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e ncludes all chan
ebe0: 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69 ges from all tri
ebf0: 67 67 65 72 20 63 6f 6e 74 65 78 74 73 2e 20 20 gger contexts.
ec00: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 However,.** the
ec10: 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 count does not i
ec20: 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 nclude changes u
ec30: 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 sed to implement
ec40: 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 REPLACE constra
ec50: 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c ints,.** do roll
ec60: 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 backs or ABORT p
ec70: 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 44 52 rocessing, or DR
ec80: 4f 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73 73 OP table process
ec90: 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e ing..** The chan
eca0: 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 ges are counted
ecb0: 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 as soon as the s
ecc0: 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 tatement that ma
ecd0: 6b 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 kes them is.** c
ece0: 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 ompleted (when t
ecf0: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e he statement han
ed00: 64 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 6f dle is passed to
ed10: 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
ed20: 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
ed30: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 3_finalize()])..
ed40: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 **.** SQLite imp
ed50: 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d lements the comm
ed60: 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d and "DELETE FROM
ed70: 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 table" without
ed80: 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a a WHERE clause.*
ed90: 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e * by dropping an
eda0: 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 d recreating the
edb0: 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 table. (This i
edc0: 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 s much faster th
edd0: 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f an going.** thro
ede0: 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 ugh and deleting
edf0: 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d individual elem
ee00: 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 ents from the ta
ee10: 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f ble.) Because o
ee20: 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 f this.** optimi
ee30: 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 zation, the dele
ee40: 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 tions in "DELETE
ee50: 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 FROM table" are
ee60: 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 not row changes
ee70: 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 and.** will not
ee80: 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 be counted by t
ee90: 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 he sqlite3_chang
eea0: 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 es() or [sqlite3
eeb0: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
eec0: 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 ].** functions,
eed0: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 regardless of th
eee0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d e number of elem
eef0: 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f ents that were o
ef00: 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 riginally.** in
ef10: 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 the table. To g
ef20: 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 et an accurate c
ef30: 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 ount of the numb
ef40: 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 er of rows delet
ef50: 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 ed, use.** "DELE
ef60: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 TE FROM table WH
ef70: 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a ERE 1" instead..
ef80: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 **.** See also t
ef90: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e he [sqlite3_chan
efa0: 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ges()] interface
efb0: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
efc0: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 TS:.**.** {H1226
efd0: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 1} The [sqlite3_
efe0: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d total_changes()]
eff0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 returns the tot
f000: 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 al number.**
f010: 20 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68 61 of row cha
f020: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49 nges caused by I
f030: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 61 NSERT, UPDATE, a
f040: 6e 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 nd/or DELETE.**
f050: 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 stateme
f060: 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 nts on the same
f070: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
f080: 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a tion], in any.**
f090: 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67 65 trigge
f0a0: 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63 65 r context, since
f0b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
f0c0: 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 63 72 65 nnection was cre
f0d0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ated..**.** {H12
f0e0: 32 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 263} Statements
f0f0: 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c of the form "DEL
f100: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 ETE FROM tablena
f110: 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 me" with no.**
f120: 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63 6c WHERE cl
f130: 61 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20 63 ause shall not c
f140: 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 hange the value
f150: 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 returned.**
f160: 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 by [sqlite3
f170: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
f180: 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 ]..**.** ASSUMPT
f190: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 IONS:.**.** {A12
f1a0: 32 36 34 7d 20 49 66 20 61 20 73 65 70 61 72 61 264} If a separa
f1b0: 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 te thread makes
f1c0: 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 changes on the s
f1d0: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
f1e0: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 nection.**
f1f0: 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 while [sqlit
f200: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
f210: 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 ()] is running t
f220: 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a hen the value.**
f230: 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e return
f240: 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 ed is unpredicta
f250: 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e ble and not mean
f260: 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 ingful..*/.int s
f270: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
f280: 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a nges(sqlite3*);.
f290: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
f2a0: 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e Interrupt A Lon
f2b0: 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 g-Running Query
f2c0: 7b 48 31 32 32 37 30 7d 20 3c 53 33 30 35 30 30 {H12270} <S30500
f2d0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e >.**.** This fun
f2e0: 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 ction causes any
f2f0: 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 pending databas
f300: 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 e operation to a
f310: 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 bort and.** retu
f320: 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 rn at its earlie
f330: 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 st opportunity.
f340: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 This routine is
f350: 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c typically.** cal
f360: 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 led in response
f370: 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e to a user action
f380: 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e such as pressin
f390: 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 g "Cancel".** or
f3a0: 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 Ctrl-C where th
f3b0: 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c e user wants a l
f3c0: 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 ong query operat
f3d0: 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 ion to halt.** i
f3e0: 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a mmediately..**.*
f3f0: 2a 20 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 * It is safe to
f400: 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e call this routin
f410: 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 e from a thread
f420: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 different from t
f430: 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 he.** thread tha
f440: 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 t is currently r
f450: 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 unning the datab
f460: 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 ase operation.
f470: 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 But it.** is not
f480: 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 safe to call th
f490: 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 is routine with
f4a0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
f4b0: 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 ection] that.**
f4c0: 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 is closed or mig
f4d0: 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 ht close before
f4e0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
f4f0: 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a t() returns..**.
f500: 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 ** If an SQL ope
f510: 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e ration is very n
f520: 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 early finished a
f530: 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a t the time when.
f540: 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 ** sqlite3_inter
f550: 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 rupt() is called
f560: 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 , then it might
f570: 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f not have an oppo
f580: 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 rtunity.** to be
f590: 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 interrupted and
f5a0: 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 might continue
f5b0: 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a to completion..*
f5c0: 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 *.** An SQL oper
f5d0: 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e ation that is in
f5e0: 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 terrupted will r
f5f0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e eturn [SQLITE_IN
f600: 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 TERRUPT]..** If
f610: 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 the interrupted
f620: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 SQL operation is
f630: 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 an INSERT, UPDA
f640: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a TE, or DELETE.**
f650: 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 that is inside
f660: 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e an explicit tran
f670: 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 saction, then th
f680: 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 e entire transac
f690: 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 tion.** will be
f6a0: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f rolled back auto
f6b0: 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a matically..**.**
f6c0: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 A call to sqlit
f6d0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 68 e3_interrupt() h
f6e0: 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 as no effect on
f6f0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
f700: 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 * that are start
f710: 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 ed after sqlite3
f720: 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 _interrupt() ret
f730: 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 urns..**.** INVA
f740: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
f750: 31 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 12271} The [sqli
f760: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d te3_interrupt()]
f770: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 interface will
f780: 66 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69 6e force all runnin
f790: 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 g.** SQ
f7a0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 L statements ass
f7b0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
f7c0: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
f7d0: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 onnection.**
f7e0: 20 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61 66 to halt af
f7f0: 74 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20 61 ter processing a
f800: 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69 74 t most one addit
f810: 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64 61 74 ional row of dat
f820: 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 32 a..**.** {H12272
f830: 7d 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d } Any SQL statem
f840: 65 6e 74 20 74 68 61 74 20 69 73 20 69 6e 74 65 ent that is inte
f850: 72 72 75 70 74 65 64 20 62 79 20 5b 73 71 6c 69 rrupted by [sqli
f860: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d te3_interrupt()]
f870: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c .** wil
f880: 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
f890: 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a _INTERRUPT]..**.
f8a0: 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a ** ASSUMPTIONS:.
f8b0: 2a 2a 0a 2a 2a 20 7b 41 31 32 32 37 39 7d 20 49 **.** {A12279} I
f8c0: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 f the database c
f8d0: 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 onnection closes
f8e0: 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f while [sqlite3_
f8f0: 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 interrupt()].**
f900: 20 20 20 20 20 20 20 20 20 69 73 20 72 75 6e 6e is runn
f910: 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 ing then bad thi
f920: 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 ngs will likely
f930: 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 happen..*/.void
f940: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
f950: 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a t(sqlite3*);../*
f960: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
f970: 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 termine If An SQ
f980: 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 L Statement Is C
f990: 6f 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30 7d omplete {H10510}
f9a0: 20 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S70200>.**.**
f9b0: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
f9c0: 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f re useful for co
f9d0: 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 mmand-line input
f9e0: 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 to determine if
f9f0: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c the.** currentl
fa00: 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 y entered text s
fa10: 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d eems to form com
fa20: 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 74 plete a SQL stat
fa30: 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 ement or.** if a
fa40: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 dditional input
fa50: 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 is needed before
fa60: 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 sending the tex
fa70: 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 t into.** SQLite
fa80: 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54 for parsing. T
fa90: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
faa0: 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 turn true if the
fab0: 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a input string.**
fac0: 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 appears to be a
fad0: 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 complete SQL st
fae0: 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 atement. A stat
faf0: 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 ement is judged
fb00: 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 to be.** complet
fb10: 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 e if it ends wit
fb20: 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f h a semicolon to
fb30: 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 ken and is not a
fb40: 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a fragment of a.*
fb50: 2a 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 * CREATE TRIGGER
fb60: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d statement. Sem
fb70: 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 icolons that are
fb80: 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e embedded within
fb90: 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 .** string liter
fba0: 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 als or quoted id
fbb0: 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f entifier names o
fbc0: 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e r comments are n
fbd0: 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e ot.** independen
fbe0: 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 t tokens (they a
fbf0: 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 re part of the t
fc00: 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 oken in which th
fc10: 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 ey are.** embedd
fc20: 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 ed) and thus do
fc30: 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 not count as a s
fc40: 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 tatement termina
fc50: 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 tor..**.** These
fc60: 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 routines do not
fc70: 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 parse the SQL s
fc80: 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a tatements thus.*
fc90: 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 * will not detec
fca0: 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 t syntactically
fcb0: 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a incorrect SQL..*
fcc0: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
fcd0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 31 7d 20 .**.** {H10511}
fce0: 41 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 61 A successful eva
fcf0: 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 luation of [sqli
fd00: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 te3_complete()]
fd10: 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b or.** [
fd20: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
fd30: 31 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73 20 16()] functions
fd40: 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 shall.**
fd50: 20 20 72 65 74 75 72 6e 20 61 20 6e 75 6d 65 72 return a numer
fd60: 69 63 20 31 20 69 66 20 61 6e 64 20 6f 6e 6c 79 ic 1 if and only
fd70: 20 69 66 20 74 68 65 20 6c 61 73 74 20 6e 6f 6e if the last non
fd80: 2d 77 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 20 -whitespace.**
fd90: 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 20 69 6e token in
fda0: 20 74 68 65 69 72 20 69 6e 70 75 74 20 69 73 20 their input is
fdb0: 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 a semicolon that
fdc0: 20 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77 65 is not in betwe
fdd0: 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 en.** t
fde0: 68 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e 44 he BEGIN and END
fdf0: 20 6f 66 20 61 20 43 52 45 41 54 45 20 54 52 49 of a CREATE TRI
fe00: 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 0a GGER statement..
fe10: 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 32 7d 20 49 **.** {H10512} I
fe20: 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
fe30: 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 ation error occu
fe40: 72 73 20 64 75 72 69 6e 67 20 61 6e 20 69 6e 76 rs during an inv
fe50: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 ocation.**
fe60: 20 20 20 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f of [sqlite3_
fe70: 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 20 5b complete()] or [
fe80: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
fe90: 31 36 28 29 5d 20 74 68 65 6e 20 74 68 65 0a 2a 16()] then the.*
fea0: 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 * routi
feb0: 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 ne shall return
fec0: 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a [SQLITE_NOMEM]..
fed0: 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e **.** ASSUMPTION
fee0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 32 S:.**.** {A10512
fef0: 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b } The input to [
ff00: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
ff10: 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 ()] must be a ze
ff20: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
ff30: 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 UTF-8
ff40: 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 string..**.** {A
ff50: 31 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75 74 10513} The input
ff60: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d to [sqlite3_com
ff70: 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 plete16()] must
ff80: 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e be a zero-termin
ff90: 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 ated.**
ffa0: 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 UTF-16 string i
ffb0: 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 n native byte or
ffc0: 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 der..*/.int sqli
ffd0: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e te3_complete(con
ffe0: 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 st char *sql);.i
fff0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c nt sqlite3_compl
10000 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 ete16(const void
10010 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 *sql);../*.** C
10020 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 API3REF: Registe
10030 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 r A Callback To
10040 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 Handle SQLITE_BU
10050 53 59 20 45 72 72 6f 72 73 20 7b 48 31 32 33 31 SY Errors {H1231
10060 30 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 0} <S40400>.**.*
10070 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 * This routine s
10080 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ets a callback f
10090 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 unction that mig
100a0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 ht be invoked wh
100b0 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 enever.** an att
100c0 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 empt is made to
100d0 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 open a database
100e0 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 table that anoth
100f0 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 er thread.** or
10100 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b process has lock
10110 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ed..**.** If the
10120 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 busy callback i
10130 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 s NULL, then [SQ
10140 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 LITE_BUSY] or [S
10150 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 QLITE_IOERR_BLOC
10160 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 KED].** is retur
10170 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 ned immediately
10180 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e upon encounterin
10190 67 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20 74 g the lock. If t
101a0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b he busy callback
101b0 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c .** is not NULL,
101c0 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 then the callba
101d0 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b ck will be invok
101e0 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 ed with two argu
101f0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ments..**.** The
10200 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
10210 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 to the handler i
10220 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
10230 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 void* pointer wh
10240 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 ich.** is the th
10250 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ird argument to
10260 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
10270 64 6c 65 72 28 29 2e 20 20 54 68 65 20 73 65 63 dler(). The sec
10280 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ond argument to.
10290 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 63 ** the handler c
102a0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e allback is the n
102b0 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 umber of times t
102c0 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e hat the busy han
102d0 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e dler has.** been
102e0 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 invoked for thi
102f0 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e s locking event.
10300 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 If the.** busy
10310 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
10320 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 s 0, then no add
10330 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 itional attempts
10340 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 are made to.**
10350 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 access the datab
10360 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f ase and [SQLITE_
10370 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 BUSY] or [SQLITE
10380 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 _IOERR_BLOCKED]
10390 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 is returned..**
103a0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
103b0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
103c0 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 , then another a
103d0 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 ttempt.** is mad
103e0 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 e to open the da
103f0 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 tabase for readi
10400 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 ng and the cycle
10410 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 repeats..**.**
10420 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 The presence of
10430 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 a busy handler d
10440 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 oes not guarante
10450 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 e that it will b
10460 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 e invoked.** whe
10470 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 n there is lock
10480 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20 53 contention. If S
10490 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 QLite determines
104a0 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 that invoking t
104b0 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c he busy.** handl
104c0 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 er could result
104d0 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 in a deadlock, i
104e0 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 t will go ahead
104f0 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 and return [SQLI
10500 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b TE_BUSY].** or [
10510 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
10520 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 CKED] instead of
10530 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 invoking the bu
10540 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 sy handler..** C
10550 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 onsider a scenar
10560 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f io where one pro
10570 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 cess is holding
10580 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 a read lock that
10590 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 .** it is trying
105a0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 to promote to a
105b0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 reserved lock a
105c0 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 nd.** a second p
105d0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e rocess is holdin
105e0 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 g a reserved loc
105f0 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 k that it is try
10600 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 ing.** to promot
10610 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 e to an exclusiv
10620 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 e lock. The fir
10630 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f st process canno
10640 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 t proceed.** bec
10650 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b ause it is block
10660 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 ed by the second
10670 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 and the second
10680 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a process cannot.*
10690 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 * proceed becaus
106a0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 e it is blocked
106b0 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 by the first. I
106c0 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 f both processes
106d0 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 .** invoke the b
106e0 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 usy handlers, ne
106f0 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 ither will make
10700 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 any progress. T
10710 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c herefore,.** SQL
10720 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ite returns [SQL
10730 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 ITE_BUSY] for th
10740 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c e first process,
10750 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 hoping that thi
10760 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 s.** will induce
10770 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 the first proce
10780 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 ss to release it
10790 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 s read lock and
107a0 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 allow.** the sec
107b0 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 ond process to p
107c0 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 roceed..**.** Th
107d0 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 e default busy c
107e0 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e allback is NULL.
107f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
10800 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 TE_BUSY] error i
10810 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b s converted to [
10820 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
10830 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 CKED].** when SQ
10840 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d Lite is in the m
10850 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 iddle of a large
10860 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 transaction whe
10870 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 re all the.** ch
10880 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 anges will not f
10890 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d it into the in-m
108a0 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 emory cache. SQ
108b0 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 Lite will.** alr
108c0 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 eady hold a RESE
108d0 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 RVED lock on the
108e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 database file,
108f0 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 but it needs.**
10900 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 to promote this
10910 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 lock to EXCLUSIV
10920 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e E so that it can
10930 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 spill cache.**
10940 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 pages into the d
10950 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 atabase file wit
10960 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e hout harm to con
10970 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 current.** reade
10980 72 73 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e rs. If it is un
10990 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 able to promote
109a0 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 the lock, then t
109b0 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 he in-memory.**
109c0 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 cache will be le
109d0 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 ft in an inconsi
109e0 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 stent state and
109f0 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 so the error.**
10a00 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 code is promoted
10a10 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 from the relati
10a20 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c vely benign [SQL
10a30 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 ITE_BUSY] to.**
10a40 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 the more severe
10a50 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
10a60 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 OCKED]. This er
10a70 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 ror code promoti
10a80 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 on.** forces an
10a90 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 automatic rollba
10aa0 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 ck of the change
10ab0 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c s. See the.** <
10ac0 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 a href="/cvstrac
10ad0 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 /wiki?p=Corrupti
10ae0 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 onFollowingBusyE
10af0 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 rror">.** Corrup
10b00 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 tionFollowingBus
10b10 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 yError</a> wiki
10b20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 page for a discu
10b30 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 ssion of why.**
10b40 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e this is importan
10b50 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 t..**.** There c
10b60 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e an only be a sin
10b70 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 gle busy handler
10b80 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 defined for eac
10b90 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 h.** [database c
10ba0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 onnection]. Set
10bb0 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 ting a new busy
10bc0 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 handler clears a
10bd0 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 ny.** previously
10be0 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 20 20 4e set handler. N
10bf0 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 ote that calling
10c00 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 [sqlite3_busy_t
10c10 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c imeout()].** wil
10c20 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c l also set or cl
10c30 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e ear the busy han
10c40 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 dler..**.** INVA
10c50 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
10c60 31 32 33 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 12311} The [sqli
10c70 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
10c80 28 44 2c 43 2c 41 29 5d 20 66 75 6e 63 74 69 6f (D,C,A)] functio
10c90 6e 20 73 68 61 6c 6c 20 72 65 70 6c 61 63 65 0a n shall replace.
10ca0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 73 79 ** busy
10cb0 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65 callback in the
10cc0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
10cd0 63 74 69 6f 6e 5d 20 44 20 77 69 74 68 20 61 20 ction] D with a
10ce0 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 new.**
10cf0 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c a new busy handl
10d00 65 72 20 43 20 61 6e 64 20 61 70 70 6c 69 63 61 er C and applica
10d10 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 tion data pointe
10d20 72 20 41 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 r A..**.** {H123
10d30 31 32 7d 20 4e 65 77 6c 79 20 63 72 65 61 74 65 12} Newly create
10d40 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e d [database conn
10d50 65 63 74 69 6f 6e 73 5d 20 73 68 61 6c 6c 20 68 ections] shall h
10d60 61 76 65 20 61 20 62 75 73 79 0a 2a 2a 20 20 20 ave a busy.**
10d70 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 6f handler o
10d80 66 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 f NULL..**.** {H
10d90 31 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f 20 12314} When two
10da0 6f 72 20 6d 6f 72 65 20 5b 64 61 74 61 62 61 73 or more [databas
10db0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73 e connections] s
10dc0 68 61 72 65 20 61 0a 2a 2a 20 20 20 20 20 20 20 hare a.**
10dd0 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 [sqlite3_enab
10de0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20 le_shared_cache
10df0 7c 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c | common cache],
10e00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
10e10 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f busy handler fo
10e20 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 r the database c
10e30 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e onnection curren
10e40 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 tly using.**
10e50 20 20 20 20 20 20 74 68 65 20 63 61 63 68 65 20 the cache
10e60 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 shall be invoked
10e70 20 77 68 65 6e 20 74 68 65 20 63 61 63 68 65 20 when the cache
10e80 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63 encounters a loc
10e90 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 36 k..**.** {H12316
10ea0 7d 20 49 66 20 61 20 62 75 73 79 20 68 61 6e 64 } If a busy hand
10eb0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 ler callback ret
10ec0 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 urns zero, then
10ed0 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 the SQLite inter
10ee0 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 face.**
10ef0 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 that provoked t
10f00 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 he locking event
10f10 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 shall return [S
10f20 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a QLITE_BUSY]..**.
10f30 2a 2a 20 7b 48 31 32 33 31 38 7d 20 53 51 4c 69 ** {H12318} SQLi
10f40 74 65 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 73 te shall invokes
10f50 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
10f60 72 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d r with two argum
10f70 65 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20 20 20 ents which.**
10f80 20 20 20 20 20 20 20 61 72 65 20 61 20 63 6f 70 are a cop
10f90 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72 y of the pointer
10fa0 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 supplied by the
10fb0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
10fc0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 o.** [s
10fd0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
10fe0 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75 ler()] and a cou
10ff0 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 nt of the number
11000 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 of prior.**
11010 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e invocation
11020 73 20 6f 66 20 74 68 65 20 62 75 73 79 20 68 61 s of the busy ha
11030 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73 61 ndler for the sa
11040 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 me locking event
11050 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 ..**.** ASSUMPTI
11060 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 33 ONS:.**.** {A123
11070 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64 6c 19} A busy handl
11080 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 er must not clos
11090 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 e the database c
110a0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 onnection.**
110b0 20 20 20 20 20 20 6f 72 20 5b 70 72 65 70 61 72 or [prepar
110c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
110d0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 at invoked the b
110e0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a usy handler..*/.
110f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 int sqlite3_busy
11100 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 _handler(sqlite3
11110 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c *, int(*)(void*,
11120 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f int), void*);../
11130 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
11140 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 et A Busy Timeou
11150 74 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34 t {H12340} <S404
11160 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 10>.**.** This r
11170 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 outine sets a [s
11180 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
11190 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c ler | busy handl
111a0 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a er] that sleeps.
111b0 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 ** for a specifi
111c0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d ed amount of tim
111d0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 e when a table i
111e0 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 s locked. The h
111f0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 andler.** will s
11200 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 leep multiple ti
11210 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 mes until at lea
11220 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 st "ms" millisec
11230 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 onds of sleeping
11240 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c .** have accumul
11250 61 74 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41 ated. {H12343} A
11260 66 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 fter "ms" millis
11270 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 econds of sleepi
11280 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c ng,.** the handl
11290 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 er returns 0 whi
112a0 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 ch causes [sqlit
112b0 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 e3_step()] to re
112c0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f turn.** [SQLITE_
112d0 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 BUSY] or [SQLITE
112e0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e _IOERR_BLOCKED].
112f0 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 .**.** Calling t
11300 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 his routine with
11310 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 an argument les
11320 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 s than or equal
11330 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 to zero.** turns
11340 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 off all busy ha
11350 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ndlers..**.** Th
11360 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ere can only be
11370 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 a single busy ha
11380 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 ndler for a part
11390 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
113a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
113b0 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f any any given mo
113c0 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 ment. If anothe
113d0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a r busy handler.*
113e0 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 * was defined (
113f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 using [sqlite3_b
11400 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 usy_handler()])
11410 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 prior to calling
11420 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
11430 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 , that other bus
11440 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 y handler is cle
11450 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 ared..**.** INVA
11460 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
11470 31 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 12341} The [sqli
11480 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
11490 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 ()] function sha
114a0 6c 6c 20 6f 76 65 72 72 69 64 65 20 61 6e 79 20 ll override any
114b0 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 prior.**
114c0 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f [sqlite3_busy_
114d0 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73 timeout()] or [s
114e0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
114f0 6c 65 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a ler()] setting.*
11500 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 * on th
11510 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 e same [database
11520 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
11530 0a 2a 2a 20 7b 48 31 32 33 34 33 7d 20 49 66 20 .** {H12343} If
11540 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
11550 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 r to [sqlite3_bu
11560 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 sy_timeout()] is
11570 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 less than.**
11580 20 20 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20 or equal
11590 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 to zero, then th
115a0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73 e busy handler s
115b0 68 61 6c 6c 20 62 65 20 63 6c 65 61 72 65 64 20 hall be cleared
115c0 73 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 so that.**
115d0 20 20 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65 all subseque
115e0 6e 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 nt locking event
115f0 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 s immediately re
11600 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 turn [SQLITE_BUS
11610 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 Y]..**.** {H1234
11620 34 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 4} If the 2nd pa
11630 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
11640 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
11650 28 29 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76 ()] is a positiv
11660 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 e.** nu
11670 6d 62 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 mber N, then a b
11680 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c usy handler shal
11690 6c 20 62 65 20 73 65 74 20 74 68 61 74 20 72 65 l be set that re
116a0 70 65 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a peatedly calls.*
116b0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 78 * the x
116c0 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69 Sleep() method i
116d0 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 n the [sqlite3_v
116e0 66 73 20 7c 20 56 46 53 20 69 6e 74 65 72 66 61 fs | VFS interfa
116f0 63 65 5d 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 ce] until.**
11700 20 20 20 20 20 20 65 69 74 68 65 72 20 74 68 65 either the
11710 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20 lock clears or
11720 75 6e 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61 until the cumula
11730 74 69 76 65 20 73 6c 65 65 70 20 74 69 6d 65 0a tive sleep time.
11740 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 70 6f ** repo
11750 72 74 65 64 20 62 61 63 6b 20 62 79 20 78 53 6c rted back by xSl
11760 65 65 70 28 29 20 65 78 63 65 65 64 73 20 4e 20 eep() exceeds N
11770 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f milliseconds..*/
11780 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 .int sqlite3_bus
11790 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 y_timeout(sqlite
117a0 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 3*, int ms);../*
117b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
117c0 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e nvenience Routin
117d0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 es For Running Q
117e0 75 65 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20 ueries {H12370}
117f0 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 <S10000>.**.** D
11800 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e efinition: A <b>
11810 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e result table</b>
11820 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 is memory data
11830 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 structure create
11840 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c d by the.** [sql
11850 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
11860 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 ] interface. A
11870 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 result table rec
11880 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 ords the.** comp
11890 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c lete query resul
118a0 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d ts from one or m
118b0 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a ore queries..**.
118c0 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e ** The table con
118d0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 ceptually has a
118e0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 number of rows a
118f0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 nd columns. But
11900 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 .** these number
11910 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f s are not part o
11920 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 f the result tab
11930 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 le itself. Thes
11940 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 e.** numbers are
11950 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 obtained separa
11960 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 tely. Let N be
11970 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f the number of ro
11980 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 ws.** and M be t
11990 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
119a0 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 umns..**.** A re
119b0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e sult table is an
119c0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
119d0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 rs to zero-termi
119e0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 nated UTF-8 stri
119f0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 ngs..** There ar
11a00 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e e (N+1)*M elemen
11a10 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e ts in the array.
11a20 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f The first M po
11a30 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 inters point.**
11a40 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 to zero-terminat
11a50 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 ed strings that
11a60 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d contain the nam
11a70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e es of the column
11a80 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e s..** The remain
11a90 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 ing entries all
11aa0 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 point to query r
11ab0 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 esults. NULL va
11ac0 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 lues result.** i
11ad0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e n NULL pointers.
11ae0 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 All other valu
11af0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 es are in their
11b00 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 UTF-8 zero-termi
11b10 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 nated.** string
11b20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 representation a
11b30 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 s returned by [s
11b40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
11b50 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 xt()]..**.** A r
11b60 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 esult table migh
11b70 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 t consist of one
11b80 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 or more memory
11b90 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 allocations..**
11ba0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 It is not safe t
11bb0 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 o pass a result
11bc0 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 table directly t
11bd0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
11be0 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 )]..** A result
11bf0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 table should be
11c00 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e deallocated usin
11c10 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f g [sqlite3_free_
11c20 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 table()]..**.**
11c30 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 As an example of
11c40 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
11c50 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 e format, suppos
11c60 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 e a query result
11c70 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 .** is as follow
11c80 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
11c90 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 uote><pre>.**
11ca0 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 Name
11cb0 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 | Age.**
11cc0 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ---------------
11cd0 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 --------.**
11ce0 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c Alice |
11cf0 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 43.** Bo
11d00 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a b | 28.*
11d10 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 * Cindy
11d20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 | 21.** </p
11d30 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
11d40 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 .**.** There are
11d50 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d two column (M==
11d60 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 2) and three row
11d70 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 s (N==3). Thus
11d80 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 the.** result ta
11d90 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 ble has 8 entrie
11da0 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 s. Suppose the
11db0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 result table is
11dc0 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 stored.** in an
11dd0 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 array names azRe
11de0 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 sult. Then azRe
11df0 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 sult holds this
11e00 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c content:.**.** <
11e10 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
11e20 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
11e30 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 ult[0] = "Na
11e40 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 me";.** a
11e50 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d zResult[1] =
11e60 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 "Age";.**
11e70 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 azResult[2
11e80 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 ] = "Alice";.**
11e90 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
11ea0 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a #91;3] = "43";.*
11eb0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
11ec0 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 t[4] = "Bob"
11ed0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
11ee0 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 sult[5] = "2
11ef0 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 8";.** az
11f00 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 Result[6] =
11f10 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 "Cindy";.**
11f20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
11f30 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 7] = "21";.** </
11f40 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
11f50 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
11f60 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 te3_get_table()
11f70 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 function evaluat
11f80 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a es one or more.*
11f90 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 * semicolon-sepa
11fa0 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d rated SQL statem
11fb0 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f ents in the zero
11fc0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
11fd0 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 8.** string of i
11fe0 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 ts 2nd parameter
11ff0 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20 . It returns a
12000 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 result table to
12010 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 the.** pointer g
12020 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 iven in its 3rd
12030 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
12040 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 After the calli
12050 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 ng function has
12060 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 finished using t
12070 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 he result, it sh
12080 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 ould.** pass the
12090 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
120a0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 result table to
120b0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
120c0 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f le() in order to
120d0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 .** release the
120e0 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 memory that was
120f0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 malloced. Becau
12100 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 se of the way th
12110 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 e.** [sqlite3_ma
12120 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 lloc()] happens
12130 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 within sqlite3_g
12140 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 et_table(), the
12150 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 calling.** funct
12160 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 ion must not try
12170 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 to call [sqlite
12180 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 3_free()] direct
12190 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 ly. Only.** [sq
121a0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
121b0 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 ()] is able to r
121c0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 elease the memor
121d0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 y properly and s
121e0 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 afely..**.** The
121f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
12200 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 le() interface i
12210 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 s implemented as
12220 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e a wrapper aroun
12230 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 d.** [sqlite3_ex
12240 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 ec()]. The sqli
12250 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 te3_get_table()
12260 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 routine does not
12270 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 have access.**
12280 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 to any internal
12290 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 data structures
122a0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 of SQLite. It u
122b0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 ses only the pub
122c0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 lic.** interface
122d0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 defined here.
122e0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 As a consequence
122f0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 , errors that oc
12300 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 cur in the.** wr
12310 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 apper layer outs
12320 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 ide of the inter
12330 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 nal [sqlite3_exe
12340 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f c()] call are no
12350 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 t.** reflected i
12360 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c n subsequent cal
12370 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 ls to [sqlite3_e
12380 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 rrcode()] or [sq
12390 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e lite3_errmsg()].
123a0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
123b0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 31 S:.**.** {H12371
123c0 7d 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f } If a [sqlite3_
123d0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69 get_table()] fai
123e0 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ls a memory allo
123f0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 cation, then.**
12400 20 20 20 20 20 20 20 20 20 69 74 20 73 68 61 6c it shal
12410 6c 20 66 72 65 65 20 74 68 65 20 72 65 73 75 6c l free the resul
12420 74 20 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f t table under co
12430 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72 nstruction, abor
12440 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 t the.**
12450 20 20 71 75 65 72 79 20 69 6e 20 70 72 6f 63 65 query in proce
12460 73 73 2c 20 73 6b 69 70 20 61 6e 79 20 73 75 62 ss, skip any sub
12470 73 65 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c sequent queries,
12480 20 73 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 set the.**
12490 20 20 20 20 20 2a 70 61 7a 52 65 73 75 6c 74 20 *pazResult
124a0 6f 75 74 70 75 74 20 70 6f 69 6e 74 65 72 20 74 output pointer t
124b0 6f 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75 72 o NULL and retur
124c0 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d n [SQLITE_NOMEM]
124d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 33 7d ..**.** {H12373}
124e0 20 49 66 20 74 68 65 20 70 6e 43 6f 6c 75 6d 6e If the pnColumn
124f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
12500 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
12510 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a ()] is not NULL.
12520 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e ** then
12530 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e a successful in
12540 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c vocation of [sql
12550 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
12560 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 ] shall.**
12570 20 20 20 20 77 72 69 74 65 20 74 68 65 20 6e 75 write the nu
12580 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
12590 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 in the.**
125a0 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 result set of
125b0 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 the query into
125c0 2a 70 6e 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a *pnColumn..**.**
125d0 20 7b 48 31 32 33 37 34 7d 20 49 66 20 74 68 65 {H12374} If the
125e0 20 70 6e 52 6f 77 20 70 61 72 61 6d 65 74 65 72 pnRow parameter
125f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 to [sqlite3_get
12600 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 _table()] is not
12610 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 NULL.**
12620 20 20 74 68 65 6e 20 61 20 73 75 63 63 65 73 73 then a success
12630 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f ful invocation o
12640 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 f [sqlite3_get_t
12650 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a able()] shall.**
12660 20 20 20 20 20 20 20 20 20 20 77 72 69 74 65 73 writes
12670 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 the number of r
12680 6f 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 ows in the.**
12690 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 result se
126a0 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 t of the query i
126b0 6e 74 6f 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a nto *pnRow..**.*
126c0 2a 20 7b 48 31 32 33 37 36 7d 20 41 20 73 75 63 * {H12376} A suc
126d0 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 cessful invocati
126e0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 on of [sqlite3_g
126f0 65 74 5f 74 61 62 6c 65 28 29 5d 20 74 68 61 74 et_table()] that
12700 20 63 6f 6d 70 75 74 65 73 0a 2a 2a 20 20 20 20 computes.**
12710 20 20 20 20 20 20 4e 20 72 6f 77 73 20 6f 66 20 N rows of
12720 72 65 73 75 6c 74 20 77 69 74 68 20 43 20 63 6f result with C co
12730 6c 75 6d 6e 73 20 70 65 72 20 72 6f 77 20 73 68 lumns per row sh
12740 61 6c 6c 20 6d 61 6b 65 20 2a 70 61 7a 52 65 73 all make *pazRes
12750 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ult.**
12760 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 72 72 61 point to an arra
12770 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
12780 20 28 4e 2b 31 29 2a 43 20 73 74 72 69 6e 67 73 (N+1)*C strings
12790 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 where the first
127a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 20 73 .** C s
127b0 74 72 69 6e 67 73 20 61 72 65 20 63 6f 6c 75 6d trings are colum
127c0 6e 20 6e 61 6d 65 73 20 61 73 20 6f 62 74 61 69 n names as obtai
127d0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 ned from.**
127e0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f [sqlite3_co
127f0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 lumn_name()] and
12800 20 74 68 65 20 72 65 73 74 20 61 72 65 20 63 6f the rest are co
12810 6c 75 6d 6e 20 72 65 73 75 6c 74 20 76 61 6c 75 lumn result valu
12820 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f es.** o
12830 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
12840 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
12850 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 t()]..**.** {H12
12860 33 37 39 7d 20 54 68 65 20 76 61 6c 75 65 73 20 379} The values
12870 69 6e 20 74 68 65 20 70 61 7a 52 65 73 75 6c 74 in the pazResult
12880 20 61 72 72 61 79 20 72 65 74 75 72 6e 65 64 20 array returned
12890 62 79 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f by [sqlite3_get_
128a0 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 table()].**
128b0 20 20 20 20 20 73 68 61 6c 6c 20 72 65 6d 61 69 shall remai
128c0 6e 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 63 6c n valid until cl
128d0 65 61 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 eared by [sqlite
128e0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 3_free_table()].
128f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 38 32 7d 20 .**.** {H12382}
12900 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 When an error oc
12910 63 75 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c curs during eval
12920 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 uation of [sqlit
12930 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a e3_get_table()].
12940 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
12950 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 function shall s
12960 65 74 20 2a 70 61 7a 52 65 73 75 6c 74 20 74 6f et *pazResult to
12970 20 4e 55 4c 4c 2c 20 77 72 69 74 65 20 61 6e 20 NULL, write an
12980 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a error message.**
12990 20 20 20 20 20 20 20 20 20 20 69 6e 74 6f 20 6d into m
129a0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 emory obtained f
129b0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
129c0 6c 6f 63 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a 20 loc()], make.**
129d0 20 20 20 20 20 20 20 20 20 2a 2a 70 7a 45 72 72 **pzErr
129e0 6d 73 67 20 70 6f 69 6e 74 20 74 6f 20 74 68 61 msg point to tha
129f0 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2c t error message,
12a00 20 61 6e 64 20 72 65 74 75 72 6e 20 61 0a 2a 2a and return a.**
12a10 20 20 20 20 20 20 20 20 20 20 61 70 70 72 6f 70 approp
12a20 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 riate [error cod
12a30 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 e]..*/.int sqlit
12a40 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 e3_get_table(.
12a50 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
12a60 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e /* An open
12a70 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 database */. c
12a80 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
12a90 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 /* SQL to b
12aa0 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 e evaluated */.
12ab0 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 char ***pazResu
12ac0 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 lt, /* Result
12ad0 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a s of the query *
12ae0 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 /. int *pnRow,
12af0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d /* Num
12b00 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f ber of result ro
12b10 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 ws written here
12b20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 */. int *pnColu
12b30 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 mn, /* Nu
12b40 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 mber of result c
12b50 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 olumns written h
12b60 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a ere */. char **
12b70 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f pzErrmsg /
12b80 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
12b90 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 ten here */.);.v
12ba0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 oid sqlite3_free
12bb0 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 _table(char **re
12bc0 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 sult);../*.** CA
12bd0 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 PI3REF: Formatte
12be0 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e d String Printin
12bf0 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 g Functions {H17
12c00 34 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 400} <S70000><S2
12c10 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 0000>.**.** Thes
12c20 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 e routines are w
12c30 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 orkalikes of the
12c40 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 "printf()" fami
12c50 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a ly of functions.
12c60 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e ** from the stan
12c70 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a dard C library..
12c80 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
12c90 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 3_mprintf() and
12ca0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
12cb0 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 () routines writ
12cc0 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c e their.** resul
12cd0 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f ts into memory o
12ce0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
12cf0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
12d00 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 .** The strings
12d10 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 returned by thes
12d20 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 e two routines s
12d30 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 hould be.** rele
12d40 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ased by [sqlite3
12d50 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 _free()]. Both
12d60 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
12d70 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
12d80 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 r if [sqlite3_ma
12d90 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c lloc()] is unabl
12da0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e e to allocate en
12db0 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 ough.** memory t
12dc0 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c o hold the resul
12dd0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a ting string..**.
12de0 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e ** In sqlite3_sn
12df0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 printf() routine
12e00 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 is similar to "
12e10 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d snprintf()" from
12e20 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 .** the standard
12e30 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 C library. The
12e40 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 result is writt
12e50 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 en into the.** b
12e60 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 uffer supplied a
12e70 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
12e80 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a ameter whose siz
12e90 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a e is given by.**
12ea0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
12eb0 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 eter. Note that
12ec0 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 the order of the
12ed0 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 .** first two pa
12ee0 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 rameters is reve
12ef0 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e rsed from snprin
12f00 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 tf(). This is a
12f10 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 n.** historical
12f20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 accident that ca
12f30 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 nnot be fixed wi
12f40 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a thout breaking.*
12f50 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 * backwards comp
12f60 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 atibility. Note
12f70 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 also that sqlit
12f80 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
12f90 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
12fa0 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 er to its buffer
12fb0 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 instead of the
12fc0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 number of.** cha
12fd0 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 racters actually
12fe0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
12ff0 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 e buffer. We ad
13000 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 mit that.** the
13010 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
13020 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 ters written wou
13030 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 ld be a more use
13040 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 ful return.** va
13050 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f lue but we canno
13060 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 t change the imp
13070 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 lementation of s
13080 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
13090 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 ).** now without
130a0 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 breaking compat
130b0 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 ibility..**.** A
130c0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 s long as the bu
130d0 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 ffer size is gre
130e0 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 ater than zero,
130f0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
13100 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 ().** guarantees
13110 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 that the buffer
13120 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d is always zero-
13130 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 terminated. The
13140 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 first.** parame
13150 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 ter "n" is the t
13160 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 otal size of the
13170 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 buffer, includi
13180 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 ng space for.**
13190 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 the zero termina
131a0 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e tor. So the lon
131b0 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 gest string that
131c0 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 can be complete
131d0 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 ly.** written wi
131e0 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 ll be n-1 charac
131f0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ters..**.** Thes
13200 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 e routines all i
13210 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 mplement some ad
13220 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 ditional formatt
13230 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 ing.** options t
13240 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 hat are useful f
13250 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 or constructing
13260 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a SQL statements..
13270 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 ** All of the us
13280 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 ual printf() for
13290 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 matting options
132a0 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 apply. In addit
132b0 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 ion, there.** is
132c0 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c are "%q", "%Q",
132d0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e and "%z" option
132e0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 s..**.** The %q
132f0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b option works lik
13300 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 e %s in that it
13310 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 substitutes a nu
13320 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ll-terminated.**
13330 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 string from the
13340 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 argument list.
13350 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 But %q also dou
13360 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 bles every '\''
13370 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 character..** %q
13380 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 is designed for
13390 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 use inside a st
133a0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 ring literal. B
133b0 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 y doubling each
133c0 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 '\''.** characte
133d0 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 r it escapes tha
133e0 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 t character and
133f0 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 allows it to be
13400 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a inserted into.**
13410 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a the string..**.
13420 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ** For example,
13430 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e assume the strin
13440 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 g variable zText
13450 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 contains text a
13460 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
13470 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
13480 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 e>.** char *zTe
13490 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 xt = "It's a hap
134a0 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 py day!";.** </p
134b0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
134c0 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 .**.** One can u
134d0 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 se this text in
134e0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
134f0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
13500 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
13510 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
13520 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 SQL = sqlite3_mp
13530 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e rintf("INSERT IN
13540 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 TO table VALUES(
13550 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a '%q')", zText);.
13560 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 ** sqlite3_exec
13570 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c (db, zSQL, 0, 0,
13580 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 0);.** sqlite3
13590 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 _free(zSQL);.**
135a0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
135b0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 te>.**.** Becaus
135c0 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 e the %q format
135d0 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 string is used,
135e0 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 the '\'' charact
135f0 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 er in zText.** i
13600 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 s escaped and th
13610 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 e SQL generated
13620 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a is as follows:.*
13630 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
13640 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 ><pre>.** INSER
13650 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 T INTO table1 VA
13660 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 LUES('It''s a ha
13670 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f ppy day!').** </
13680 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
13690 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 >.**.** This is
136a0 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 correct. Had we
136b0 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 used %s instead
136c0 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 of %q, the gene
136d0 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 rated SQL.** wou
136e0 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c ld have looked l
136f0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 ike this:.**.**
13700 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
13710 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 >.** INSERT INT
13720 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 O table1 VALUES(
13730 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 'It's a happy da
13740 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c y!');.** </pre><
13750 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
13760 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 ** This second e
13770 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c xample is an SQL
13780 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 syntax error.
13790 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c As a general rul
137a0 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 e you should.**
137b0 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e always use %q in
137c0 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e stead of %s when
137d0 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 inserting text
137e0 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 into a string li
137f0 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 teral..**.** The
13800 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 %Q option works
13810 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 like %q except
13820 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e it also adds sin
13830 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e gle quotes aroun
13840 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 d.** the outside
13850 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 of the total st
13860 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 ring. Additiona
13870 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 lly, if the para
13880 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 meter in the.**
13890 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 argument list is
138a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
138b0 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 %Q substitutes
138c0 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 the text "NULL"
138d0 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 (without.** sing
138e0 6c 65 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c le quotes) in pl
138f0 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 ace of the %Q op
13900 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 tion. So, for e
13910 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c xample, one coul
13920 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c d say:.**.** <bl
13930 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
13940 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 * char *zSQL =
13950 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
13960 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 "INSERT INTO tab
13970 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 le VALUES(%Q)",
13980 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 zText);.** sqli
13990 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 te3_exec(db, zSQ
139a0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 L, 0, 0, 0);.**
139b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 sqlite3_free(zS
139c0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f QL);.** </pre></
139d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
139e0 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 * The code above
139f0 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 will render a c
13a00 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 orrect SQL state
13a10 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c ment in the zSQL
13a20 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 .** variable eve
13a30 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 n if the zText v
13a40 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c ariable is a NUL
13a50 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
13a60 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 The "%z" format
13a70 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b ting option work
13a80 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 s exactly like "
13a90 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 %s" with the.**
13aa0 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 addition that af
13ab0 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 ter the string h
13ac0 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 as been read and
13ad0 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 copied into.**
13ae0 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c the result, [sql
13af0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 ite3_free()] is
13b00 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e called on the in
13b10 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 put string. {END
13b20 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e }.**.** INVARIAN
13b30 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 TS:.**.** {H1740
13b40 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 3} The [sqlite3
13b50 5f 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 _mprintf()] and
13b60 5b 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 [sqlite3_vmprint
13b70 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a f()] interfaces.
13b80 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 ** ret
13b90 75 72 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74 urn either point
13ba0 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d ers to zero-term
13bb0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
13bc0 69 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 ings held in.**
13bd0 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 memory
13be0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
13bf0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
13c00 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ] or NULL pointe
13c10 72 73 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 rs if.**
13c20 20 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 a call to [sq
13c30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
13c40 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 fails..**.** {H1
13c50 37 34 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 7406} The [sqli
13c60 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 te3_snprintf()]
13c70 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 73 interface writes
13c80 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
13c90 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 ed.**
13ca0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 UTF-8 string int
13cb0 6f 20 74 68 65 20 62 75 66 66 65 72 20 70 6f 69 o the buffer poi
13cc0 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 73 nted to by the s
13cd0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a econd parameter.
13ce0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 70 72 6f ** pro
13cf0 76 69 64 65 64 20 74 68 61 74 20 74 68 65 20 66 vided that the f
13d00 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
13d10 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a s greater than z
13d20 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 ero..**.** {H174
13d30 30 37 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 07} The [sqlite
13d40 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 3_snprintf()] in
13d50 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 terface does not
13d60 20 77 72 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a write slots of.
13d70 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 73 ** its
13d80 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 28 output buffer (
13d90 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
13da0 65 74 65 72 29 20 6f 75 74 73 69 64 65 20 74 68 eter) outside th
13db0 65 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 e range.**
13dc0 20 20 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67 of 0 throug
13dd0 68 20 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69 h N-1 (where N i
13de0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 s the first para
13df0 6d 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 meter).**
13e00 20 20 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f regardless o
13e10 66 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 f the length of
13e20 74 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 the string.**
13e30 20 20 20 20 20 20 20 20 72 65 71 75 65 73 74 65 requeste
13e40 64 20 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20 d by the format
13e50 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a specification..*
13e60 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f /.char *sqlite3_
13e70 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 mprintf(const ch
13e80 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a ar*,...);.char *
13e90 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
13ea0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 (const char*, va
13eb0 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 _list);.char *sq
13ec0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 lite3_snprintf(i
13ed0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 nt,char*,const c
13ee0 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a har*, ...);../*.
13ef0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d ** CAPI3REF: Mem
13f00 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 ory Allocation S
13f10 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33 30 30 ubsystem {H17300
13f20 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a } <S20000>.**.**
13f30 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
13f40 20 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 uses these thr
13f50 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 ee routines for
13f60 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a all of its own.*
13f70 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 * internal memor
13f80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 y allocation nee
13f90 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 ds. "Core" in th
13fa0 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 e previous sente
13fb0 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 nce.** does not
13fc0 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e include operatin
13fd0 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 g-system specifi
13fe0 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 c VFS implementa
13ff0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 tion. The.** Wi
14000 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e ndows VFS uses n
14010 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 ative malloc() a
14020 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f nd free() for so
14030 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a me operations..*
14040 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
14050 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e _malloc() routin
14060 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
14070 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a ter to a block.*
14080 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c * of memory at l
14090 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 east N bytes in
140a0 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 length, where N
140b0 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 is the parameter
140c0 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f ..** If sqlite3_
140d0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 malloc() is unab
140e0 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 le to obtain suf
140f0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 ficient free.**
14100 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 memory, it retur
14110 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
14120 72 2e 20 20 49 66 20 74 68 65 20 70 61 72 61 6d r. If the param
14130 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c eter N to.** sql
14140 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 ite3_malloc() is
14150 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 zero or negativ
14160 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d e then sqlite3_m
14170 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a alloc() returns.
14180 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ** a NULL pointe
14190 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 r..**.** Calling
141a0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
141b0 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 with a pointer p
141c0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e reviously return
141d0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 ed.** by sqlite3
141e0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c _malloc() or sql
141f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 ite3_realloc() r
14200 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d eleases that mem
14210 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 ory so.** that i
14220 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 t might be reuse
14230 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f d. The sqlite3_
14240 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 free() routine i
14250 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 s.** a no-op if
14260 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 is called with a
14270 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 NULL pointer.
14280 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 Passing a NULL p
14290 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c ointer.** to sql
142a0 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 ite3_free() is h
142b0 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 armless. After
142c0 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d being freed, mem
142d0 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 ory.** should ne
142e0 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f ither be read no
142f0 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e r written. Even
14300 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 reading previou
14310 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d sly freed.** mem
14320 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 ory might result
14330 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 in a segmentati
14340 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 on fault or othe
14350 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a r severe error..
14360 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 ** Memory corrup
14370 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 tion, a segmenta
14380 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f tion fault, or o
14390 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f ther severe erro
143a0 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c r.** might resul
143b0 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 t if sqlite3_fre
143c0 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 e() is called wi
143d0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f th a non-NULL po
143e0 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 inter that.** wa
143f0 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 s not obtained f
14400 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c rom sqlite3_mall
14410 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f oc() or sqlite3_
14420 66 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 free()..**.** Th
14430 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f e sqlite3_reallo
14440 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 c() interface at
14450 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 tempts to resize
14460 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f a.** prior memo
14470 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f ry allocation to
14480 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 be at least N b
14490 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 ytes, where N is
144a0 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 the.** second p
144b0 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d arameter. The m
144c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
144d0 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 to be resized i
144e0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 s the first.** p
144f0 61 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74 68 arameter. If th
14500 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
14510 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 r to sqlite3_rea
14520 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e lloc().** is a N
14530 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
14540 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 its behavior is
14550 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 identical to ca
14560 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 lling.** sqlite3
14570 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 _malloc(N) where
14580 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 N is the second
14590 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
145a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e lite3_realloc().
145b0 0a 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e .** If the secon
145c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
145d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
145e0 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e is zero or.** n
145f0 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 egative then the
14600 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 behavior is exa
14610 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 ctly the same as
14620 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 calling.** sqli
14630 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 te3_free(P) wher
14640 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74 e P is the first
14650 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
14660 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e lite3_realloc().
14670 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c .** sqlite3_real
14680 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 loc() returns a
14690 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d pointer to a mem
146a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ory allocation.*
146b0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 * of at least N
146c0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 bytes in size or
146d0 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 NULL if suffici
146e0 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e ent memory is un
146f0 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 available..** If
14700 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f M is the size o
14710 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f f the prior allo
14720 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e cation, then min
14730 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f (N,M) bytes.** o
14740 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f f the prior allo
14750 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 cation are copie
14760 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e d into the begin
14770 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 ning of buffer r
14780 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 eturned.** by sq
14790 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
147a0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c and the prior al
147b0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 location is free
147c0 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 d..** If sqlite3
147d0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 _realloc() retur
147e0 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 ns NULL, then th
147f0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
14800 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 on.** is not fre
14810 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 ed..**.** The me
14820 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 mory returned by
14830 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
14840 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 ) and sqlite3_re
14850 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c alloc().** is al
14860 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 ways aligned to
14870 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 at least an 8 by
14880 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e te boundary. {EN
14890 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 D}.**.** The def
148a0 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ault implementat
148b0 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 ion of the memor
148c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 y allocation sub
148d0 73 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20 74 system uses.** t
148e0 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 he malloc(), rea
148f0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 lloc() and free(
14900 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 ) provided by th
14910 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 e standard C lib
14920 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38 32 rary..** {H17382
14930 7d 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 } However, if SQ
14940 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
14950 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c with the.** SQL
14960 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d ITE_MEMORY_SIZE=
14970 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 65 <i>NNN</i> C pre
14980 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 processor macro
14990 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 (where <i>NNN</i
149a0 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 >.** is an integ
149b0 65 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 er), then SQLite
149c0 20 63 72 65 61 74 65 20 61 20 73 74 61 74 69 63 create a static
149d0 20 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61 array of at lea
149e0 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e st.** <i>NNN</i>
149f0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 bytes in size a
14a00 6e 64 20 75 73 65 73 20 74 68 61 74 20 61 72 72 nd uses that arr
14a10 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 ay for all of it
14a20 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d s dynamic.** mem
14a30 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e ory allocation n
14a40 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64 eeds. {END} Add
14a50 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 itional memory a
14a60 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 llocator options
14a70 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65 64 .** may be added
14a80 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
14a90 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 ses..**.** In SQ
14aa0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
14ab0 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 .0 and 3.5.1, it
14ac0 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f was possible to
14ad0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 define.** the S
14ae0 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 QLITE_OMIT_MEMOR
14af0 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 Y_ALLOCATION whi
14b00 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 ch would cause t
14b10 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 he built-in.** i
14b20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
14b30 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
14b40 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 to be omitted.
14b50 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a That capability.
14b60 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 ** is no longer
14b70 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 provided. Only
14b80 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 built-in memory
14b90 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 allocators can b
14ba0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 e used..**.** Th
14bb0 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 e Windows OS int
14bc0 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c erface layer cal
14bd0 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d ls.** the system
14be0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 malloc() and fr
14bf0 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 ee() directly wh
14c00 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a en converting.**
14c10 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 filenames betwe
14c20 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 en the UTF-8 enc
14c30 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 oding used by SQ
14c40 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 Lite.** and what
14c50 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e ever filename en
14c60 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 coding is used b
14c70 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 y the particular
14c80 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 Windows.** inst
14c90 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 allation. Memor
14ca0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 y allocation err
14cb0 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 ors are detected
14cc0 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 , but.** they ar
14cd0 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 e reported back
14ce0 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f as [SQLITE_CANTO
14cf0 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 PEN] or.** [SQLI
14d00 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 TE_IOERR] rather
14d10 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f than [SQLITE_NO
14d20 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 MEM]..**.** INVA
14d30 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
14d40 31 37 33 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 17303} The [sql
14d50 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 ite3_malloc(N)]
14d60 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
14d70 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 s either a point
14d80 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 er to.**
14d90 20 20 20 61 20 6e 65 77 6c 79 20 63 68 65 63 6b a newly check
14da0 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f 66 20 ed-out block of
14db0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 at least N bytes
14dc0 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 of memory.**
14dd0 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20 that is
14de0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 8-byte aligned,
14df0 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 or it returns NU
14e00 4c 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61 62 LL if it is unab
14e10 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 le.**
14e20 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68 65 20 72 to fulfill the r
14e30 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 equest..**.** {H
14e40 31 37 33 30 34 7d 20 20 54 68 65 20 5b 73 71 6c 17304} The [sql
14e50 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 ite3_malloc(N)]
14e60 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
14e70 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
14e80 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 if.**
14e90 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 N is less than
14ea0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f or equal to zero
14eb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 35 7d ..**.** {H17305}
14ec0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 The [sqlite3_f
14ed0 72 65 65 28 50 29 5d 20 69 6e 74 65 72 66 61 63 ree(P)] interfac
14ee0 65 20 72 65 6c 65 61 73 65 73 20 6d 65 6d 6f 72 e releases memor
14ef0 79 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 y previously.**
14f00 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e return
14f10 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
14f20 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 _malloc()] or [s
14f30 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
14f40 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 ],.**
14f50 6d 61 6b 69 6e 67 20 69 74 20 61 76 61 69 6c 61 making it availa
14f60 62 6c 65 20 66 6f 72 20 72 65 75 73 65 2e 0a 2a ble for reuse..*
14f70 2a 0a 2a 2a 20 7b 48 31 37 33 30 36 7d 20 20 41 *.** {H17306} A
14f80 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
14f90 33 5f 66 72 65 65 28 4e 55 4c 4c 29 5d 20 69 73 3_free(NULL)] is
14fa0 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f a harmless no-o
14fb0 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 30 p..**.** {H17310
14fc0 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 } A call to [sq
14fd0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 30 2c lite3_realloc(0,
14fe0 4e 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e N)] is equivalen
14ff0 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 t to a call.**
15000 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c to [sql
15010 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 2e ite3_malloc(N)].
15020 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 32 7d 20 .**.** {H17312}
15030 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 A call to [sqli
15040 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 30 29 te3_realloc(P,0)
15050 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 ] is equivalent
15060 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 to a call.**
15070 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 to [sqlit
15080 65 33 5f 66 72 65 65 28 50 29 5d 2e 0a 2a 2a 0a e3_free(P)]..**.
15090 2a 2a 20 7b 48 31 37 33 31 35 7d 20 20 54 68 65 ** {H17315} The
150a0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 SQLite core use
150b0 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f s [sqlite3_mallo
150c0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 c()], [sqlite3_r
150d0 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 ealloc()],.**
150e0 20 20 20 20 20 20 20 20 61 6e 64 20 5b 73 71 6c and [sql
150f0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 66 6f 72 ite3_free()] for
15100 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d 65 6d 6f all of its memo
15110 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e ry allocation an
15120 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 64 d.** d
15130 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 eallocation need
15140 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 38 s..**.** {H17318
15150 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f } The [sqlite3_
15160 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69 6e realloc(P,N)] in
15170 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
15180 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72 either a pointer
15190 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f .** to
151a0 20 61 20 62 6c 6f 63 6b 20 6f 66 20 63 68 65 63 a block of chec
151b0 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 79 20 6f ked-out memory o
151c0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 f at least N byt
151d0 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 20 es in size.**
151e0 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20 that is
151f0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 8-byte aligned,
15200 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 or a NULL pointe
15210 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 31 r..**.** {H17321
15220 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 } When [sqlite3
15230 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 _realloc(P,N)] r
15240 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c eturns a non-NUL
15250 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 L pointer, it fi
15260 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 rst.**
15270 20 63 6f 70 69 65 73 20 74 68 65 20 66 69 72 73 copies the firs
15280 74 20 4b 20 62 79 74 65 73 20 6f 66 20 63 6f 6e t K bytes of con
15290 74 65 6e 74 20 66 72 6f 6d 20 50 20 69 6e 74 6f tent from P into
152a0 20 74 68 65 20 6e 65 77 6c 79 0a 2a 2a 20 20 20 the newly.**
152b0 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 allocate
152c0 64 20 62 6c 6f 63 6b 2c 20 77 68 65 72 65 20 4b d block, where K
152d0 20 69 73 20 74 68 65 20 6c 65 73 73 65 72 20 6f is the lesser o
152e0 66 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a 65 f N and the size
152f0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 of.**
15300 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a the buffer P..*
15310 2a 0a 2a 2a 20 7b 48 31 37 33 32 32 7d 20 20 57 *.** {H17322} W
15320 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 hen [sqlite3_rea
15330 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 lloc(P,N)] retur
15340 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f ns a non-NULL po
15350 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a inter, it first.
15360 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 6c ** rel
15370 65 61 73 65 73 20 74 68 65 20 62 75 66 66 65 72 eases the buffer
15380 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 P..**.** {H1732
15390 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 3} When [sqlite
153a0 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 3_realloc(P,N)]
153b0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 returns NULL, th
153c0 65 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a 2a e buffer P is.**
153d0 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 6d not m
153e0 6f 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65 61 odified or relea
153f0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d sed..**.** ASSUM
15400 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 PTIONS:.**.** {A
15410 31 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69 6e 17350} The poin
15420 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f ter arguments to
15430 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
15440 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 ] and [sqlite3_r
15450 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20 20 ealloc()].**
15460 20 20 20 20 20 20 20 6d 75 73 74 20 62 65 20 65 must be e
15470 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c ither NULL or el
15480 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 se pointers obta
15490 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f ined from a prio
154a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 r.** i
154b0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 nvocation of [sq
154c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
154d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c or [sqlite3_real
154e0 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 loc()] that have
154f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f .** no
15500 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 t yet been relea
15510 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 sed..**.** {A173
15520 35 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 51} The applica
15530 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 tion must not re
15540 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 ad or write any
15550 70 61 72 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 part of.**
15560 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66 20 a block of
15570 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 memory after it
15580 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 has been release
15590 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 d using.**
155a0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66 72 [sqlite3_fr
155b0 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ee()] or [sqlite
155c0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 3_realloc()]..*/
155d0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d .void *sqlite3_m
155e0 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 alloc(int);.void
155f0 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f *sqlite3_reallo
15600 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 c(void*, int);.v
15610 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 oid sqlite3_free
15620 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 (void*);../*.**
15630 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 CAPI3REF: Memory
15640 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 Allocator Stati
15650 73 74 69 63 73 20 7b 48 31 37 33 37 30 7d 20 3c stics {H17370} <
15660 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 S30210>.**.** SQ
15670 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 Lite provides th
15680 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 ese two interfac
15690 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 es for reporting
156a0 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a on the status.*
156b0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * of the [sqlite
156c0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 3_malloc()], [sq
156d0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 lite3_free()], a
156e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c nd [sqlite3_real
156f0 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e loc()].** routin
15700 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 es, which form t
15710 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f he built-in memo
15720 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 ry allocation su
15730 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49 bsystem..**.** I
15740 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
15750 20 7b 48 31 37 33 37 31 7d 20 54 68 65 20 5b 73 {H17371} The [s
15760 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
15770 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 ed()] routine re
15780 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
15790 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 of bytes.**
157a0 20 20 20 20 20 20 6f 66 20 6d 65 6d 6f 72 79 20 of memory
157b0 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 currently outsta
157c0 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 nding (malloced
157d0 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a but not freed)..
157e0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 33 7d 20 54 **.** {H17373} T
157f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f he [sqlite3_memo
15800 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 ry_highwater()]
15810 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
15820 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20 the maximum.**
15830 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 value of
15840 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
15850 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 _used()] since t
15860 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 he high-water ma
15870 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 rk.** w
15880 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a 2a as last reset..*
15890 2a 0a 2a 2a 20 7b 48 31 37 33 37 34 7d 20 54 68 *.** {H17374} Th
158a0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 e values returne
158b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 d by [sqlite3_me
158c0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 mory_used()] and
158d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
158e0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
158f0 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 hwater()] includ
15900 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a e any overhead.*
15910 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 65 64 * added
15920 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 by SQLite in it
15930 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e s implementation
15940 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c of [sqlite3_mal
15950 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 loc()],.**
15960 20 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 but not over
15970 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 head added by th
15980 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 e any underlying
15990 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a system library.
159a0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 ** rout
159b0 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 ines that [sqlit
159c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 e3_malloc()] may
159d0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 call..**.** {H1
159e0 37 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72 79 7375} The memory
159f0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b high-water mark
15a00 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 is reset to the
15a10 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f current value o
15a20 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 f.** [s
15a30 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
15a40 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c ed()] if and onl
15a50 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 y if the paramet
15a60 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 er to.**
15a70 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 [sqlite3_memor
15a80 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 y_highwater()] i
15a90 73 20 74 72 75 65 2e 20 20 54 68 65 20 76 61 6c s true. The val
15aa0 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 ue returned.**
15ab0 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 by [sqli
15ac0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
15ad0 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 ater(1)] is the
15ae0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a high-water mark.
15af0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 6f ** prio
15b00 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a r to the reset..
15b10 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 */.sqlite3_int64
15b20 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f sqlite3_memory_
15b30 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 used(void);.sqli
15b40 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
15b50 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
15b60 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 er(int resetFlag
15b70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
15b80 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f EF: Pseudo-Rando
15b90 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 m Number Generat
15ba0 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 30 or {H17390} <S20
15bb0 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 000>.**.** SQLit
15bc0 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 e contains a hig
15bd0 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f h-quality pseudo
15be0 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 -random number g
15bf0 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 enerator (PRNG)
15c00 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 used to.** selec
15c10 74 20 72 61 6e 64 6f 6d 20 52 4f 57 49 44 73 20 t random ROWIDs
15c20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e when inserting n
15c30 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 ew records into
15c40 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 a table that.**
15c50 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 already uses the
15c60 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c largest possibl
15c70 65 20 52 4f 57 49 44 2e 20 20 54 68 65 20 50 52 e ROWID. The PR
15c80 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 NG is also used
15c90 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 for.** the build
15ca0 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 -in random() and
15cb0 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 randomblob() SQ
15cc0 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 L functions. Th
15cd0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c is interface all
15ce0 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 ows.** applicati
15cf0 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 ons to access th
15d00 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 e same PRNG for
15d10 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a other purposes..
15d20 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 **.** A call to
15d30 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f this routine sto
15d40 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 res N bytes of r
15d50 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 andomness into b
15d60 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 uffer P..**.** T
15d70 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 he first time th
15d80 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e is routine is in
15d90 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e voked (either in
15da0 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a ternally or by.*
15db0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f * the applicatio
15dc0 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 n) the PRNG is s
15dd0 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 eeded using rand
15de0 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a omness obtained.
15df0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e ** from the xRan
15e00 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f domness method o
15e10 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 f the default [s
15e20 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
15e30 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 ct..** On all su
15e40 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 bsequent invocat
15e50 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f ions, the pseudo
15e60 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 -randomness is g
15e70 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 enerated.** inte
15e80 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f rnally and witho
15e90 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 ut recourse to t
15ea0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d he [sqlite3_vfs]
15eb0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 xRandomness.**
15ec0 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e method..**.** IN
15ed0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
15ee0 7b 48 31 37 33 39 32 7d 20 54 68 65 20 5b 73 71 {H17392} The [sq
15ef0 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 lite3_randomness
15f00 28 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 (N,P)] interface
15f10 20 77 72 69 74 65 73 20 4e 20 62 79 74 65 73 20 writes N bytes
15f20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 of.** h
15f30 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 igh-quality pseu
15f40 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e do-randomness in
15f50 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a to buffer P..*/.
15f60 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e void sqlite3_ran
15f70 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 domness(int N, v
15f80 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 oid *P);../*.**
15f90 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c CAPI3REF: Compil
15fa0 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 e-Time Authoriza
15fb0 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b tion Callbacks {
15fc0 48 31 32 35 30 30 7d 20 3c 53 37 30 31 30 30 3e H12500} <S70100>
15fd0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
15fe0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20 ine registers a
15ff0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
16000 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 ack with a parti
16010 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 cular.** [databa
16020 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 se connection],
16030 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 supplied in the
16040 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a first argument..
16050 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 ** The authorize
16060 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
16070 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 voked as SQL sta
16080 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e tements are bein
16090 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 g compiled.** by
160a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
160b0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 e()] or its vari
160c0 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 ants [sqlite3_pr
160d0 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 epare_v2()],.**
160e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
160f0 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 16()] and [sqlit
16100 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
16110 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a )]. At various.
16120 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 ** points during
16130 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e the compilation
16140 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 process, as log
16150 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 ic is being crea
16160 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 ted.** to perfor
16170 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e m various action
16180 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 s, the authorize
16190 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
161a0 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 voked to.** see
161b0 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 if those actions
161c0 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 are allowed. T
161d0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
161e0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a llback should.**
161f0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
16200 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 OK] to allow the
16210 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 action, [SQLITE
16220 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 _IGNORE] to disa
16230 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 llow the.** spec
16240 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 ific action but
16250 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 allow the SQL st
16260 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 atement to conti
16270 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d nue to be.** com
16280 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 piled, or [SQLIT
16290 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 E_DENY] to cause
162a0 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 the entire SQL
162b0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a statement to be.
162c0 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 ** rejected with
162d0 20 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 20 74 an error. If t
162e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
162f0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a llback returns.*
16300 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 * any value othe
16310 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 r than [SQLITE_I
16320 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f GNORE], [SQLITE_
16330 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OK], or [SQLITE_
16340 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 DENY].** then th
16350 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 e [sqlite3_prepa
16360 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 re_v2()] or equi
16370 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 valent call that
16380 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 triggered.** th
16390 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c e authorizer wil
163a0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 l fail with an e
163b0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a rror message..**
163c0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c .** When the cal
163d0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 lback returns [S
163e0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 QLITE_OK], that
163f0 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 means the operat
16400 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 ion.** requested
16410 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 is ok. When th
16420 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
16430 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d ns [SQLITE_DENY]
16440 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 , the.** [sqlite
16450 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
16460 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 or equivalent ca
16470 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 ll that triggere
16480 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 d the.** authori
16490 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 zer will fail wi
164a0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 th an error mess
164b0 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 age explaining t
164c0 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 hat.** access is
164d0 20 64 65 6e 69 65 64 2e 20 20 49 66 20 74 68 65 denied. If the
164e0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 authorizer code
164f0 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 is [SQLITE_READ
16500 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c ].** and the cal
16510 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 lback returns [S
16520 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 QLITE_IGNORE] th
16530 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 en the.** [prepa
16540 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 red statement] s
16550 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 tatement is cons
16560 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 tructed to subst
16570 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 itute.** a NULL
16580 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f value in place o
16590 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 f the table colu
165a0 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 mn that would ha
165b0 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 ve.** been read
165c0 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 if [SQLITE_OK] h
165d0 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 ad been returned
165e0 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 . The [SQLITE_I
165f0 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e GNORE].** return
16600 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
16610 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 deny an untruste
16620 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f d user access to
16630 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 individual.** c
16640 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c olumns of a tabl
16650 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 e..**.** The fir
16660 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
16670 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
16680 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 allback is a cop
16690 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a y of the third.*
166a0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 * parameter to t
166b0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 he sqlite3_set_a
166c0 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 uthorizer() inte
166d0 72 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f 6e rface. The secon
166e0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 d parameter.** t
166f0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 o the callback i
16700 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 s an integer [SQ
16710 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 LITE_COPY | acti
16720 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 on code] that sp
16730 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 ecifies.** the p
16740 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e articular action
16750 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 to be authorize
16760 64 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 72 d. The third thr
16770 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d ough sixth param
16780 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 eters.** to the
16790 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 callback are zer
167a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 o-terminated str
167b0 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 ings that contai
167c0 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 n additional.**
167d0 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 details about th
167e0 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 e action to be a
167f0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a uthorized..**.**
16800 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 An authorizer i
16810 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c s used when [sql
16820 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 ite3_prepare | p
16830 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c reparing].** SQL
16840 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d statements from
16850 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f an untrusted so
16860 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 urce, to ensure
16870 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 that the SQL sta
16880 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f tements.** do no
16890 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 t try to access
168a0 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f data they are no
168b0 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 t allowed to see
168c0 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 , or that they d
168d0 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 o not.** try to
168e0 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 execute maliciou
168f0 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 s statements tha
16900 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 t damage the dat
16910 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 abase. For.** e
16920 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 xample, an appli
16930 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 cation may allow
16940 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 a user to enter
16950 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 arbitrary.** SQ
16960 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 L queries for ev
16970 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 aluation by a da
16980 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 tabase. But the
16990 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 application doe
169a0 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 s.** not want th
169b0 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c e user to be abl
169c0 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 e to make arbitr
169d0 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 ary changes to t
169e0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 he.** database.
169f0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 An authorizer c
16a00 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 ould then be put
16a10 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 in place while
16a20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 the.** user-ente
16a30 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 red SQL is being
16a40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
16a50 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 e | prepared] th
16a60 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 at.** disallows
16a70 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 everything excep
16a80 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 t [SELECT] state
16a90 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 ments..**.** App
16aa0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e lications that n
16ab0 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 eed to process S
16ac0 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 QL from untruste
16ad0 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 d sources.** mig
16ae0 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 ht also consider
16af0 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 lowering resour
16b00 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 ce limits using
16b10 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 [sqlite3_limit()
16b20 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e ].** and limitin
16b30 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 g database size
16b40 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 using the [max_p
16b50 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 age_count] [PRAG
16b60 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 MA].** in additi
16b70 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 on to using an a
16b80 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a uthorizer..**.**
16b90 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 Only a single a
16ba0 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 uthorizer can be
16bb0 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 in place on a d
16bc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
16bd0 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e on.** at a time.
16be0 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 Each call to s
16bf0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
16c00 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 rizer overrides
16c10 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 the.** previous
16c20 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 call. Disable t
16c30 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 he authorizer by
16c40 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 installing a NU
16c50 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 LL callback..**
16c60 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 The authorizer i
16c70 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 s disabled by de
16c80 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 fault..**.** Not
16c90 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f e that the autho
16ca0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
16cb0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 s invoked only d
16cc0 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 uring.** [sqlite
16cd0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
16ce0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 its variants. A
16cf0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 uthorization is
16d00 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 not.** performed
16d10 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e during statemen
16d20 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 t evaluation in
16d30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
16d40 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
16d50 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 TS:.**.** {H1250
16d60 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 1} The [sqlite3_
16d70 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 44 set_authorizer(D
16d80 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 ,...)] interface
16d90 20 72 65 67 69 73 74 65 72 73 20 61 0a 2a 2a 20 registers a.**
16da0 20 20 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 authori
16db0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 zer callback wit
16dc0 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 h database conne
16dd0 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b ction D..**.** {
16de0 48 31 32 35 30 32 7d 20 54 68 65 20 61 75 74 68 H12502} The auth
16df0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
16e00 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 is invoked as SQ
16e10 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 L statements are
16e20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 69 .** bei
16e30 6e 67 20 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a ng compiled..**.
16e40 2a 2a 20 7b 48 31 32 35 30 33 7d 20 49 66 20 74 ** {H12503} If t
16e50 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
16e60 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 llback returns a
16e70 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 ny value other t
16e80 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 han.**
16e90 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c [SQLITE_IGNORE],
16ea0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 [SQLITE_OK], or
16eb0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 [SQLITE_DENY],
16ec0 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 then.**
16ed0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 the [sqlite3_pr
16ee0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 epare_v2()] or e
16ef0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 quivalent call t
16f00 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 20 20 hat caused.**
16f10 20 20 20 20 20 20 20 74 68 65 20 61 75 74 68 6f the autho
16f20 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 rizer callback t
16f30 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c o run shall fail
16f40 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 with an.**
16f50 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 [SQLITE_ERR
16f60 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 OR] error code a
16f70 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 nd an appropriat
16f80 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e e error message.
16f90 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 34 7d 20 .**.** {H12504}
16fa0 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 When the authori
16fb0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 zer callback ret
16fc0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
16fd0 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a , the operation.
16fe0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 73 63 ** desc
16ff0 72 69 62 65 64 20 69 73 20 70 72 6f 63 65 73 73 ribed is process
17000 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a ed normally..**.
17010 2a 2a 20 7b 48 31 32 35 30 35 7d 20 57 68 65 6e ** {H12505} When
17020 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
17030 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
17040 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 [SQLITE_DENY],
17050 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
17060 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
17070 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 _v2()] or equiva
17080 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 63 lent call that c
17090 61 75 73 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 aused the.**
170a0 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 authorizer
170b0 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e callback to run
170c0 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 shall fail.**
170d0 20 20 20 20 20 20 20 20 77 69 74 68 20 61 6e 20 with an
170e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 [SQLITE_ERROR] e
170f0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e rror code and an
17100 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a error message.*
17110 2a 20 20 20 20 20 20 20 20 20 20 65 78 70 6c 61 * expla
17120 69 6e 69 6e 67 20 74 68 61 74 20 61 63 63 65 73 ining that acces
17130 73 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a s is denied..**.
17140 2a 2a 20 7b 48 31 32 35 30 36 7d 20 49 66 20 74 ** {H12506} If t
17150 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f he authorizer co
17160 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61 de (the 2nd para
17170 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 meter to the aut
17180 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 horizer.**
17190 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 callback) is
171a0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 [SQLITE_READ] a
171b0 6e 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 nd the authorize
171c0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 r callback retur
171d0 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ns.** [
171e0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 SQLITE_IGNORE],
171f0 74 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 then the prepare
17200 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 d statement is c
17210 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 0a 2a 2a onstructed to.**
17220 20 20 20 20 20 20 20 20 20 20 69 6e 73 65 72 74 insert
17230 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e a NULL value in
17240 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 place of the ta
17250 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 ble column that
17260 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 20 20 would have.**
17270 20 20 20 20 20 20 20 62 65 65 6e 20 72 65 61 64 been read
17280 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 if [SQLITE_OK]
17290 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 had been returne
172a0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 37 d..**.** {H12507
172b0 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 } If the authori
172c0 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e zer code (the 2n
172d0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
172e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a he authorizer.**
172f0 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 callba
17300 63 6b 29 20 69 73 20 61 6e 79 74 68 69 6e 67 20 ck) is anything
17310 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
17320 54 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a 2a TE_READ], then.*
17330 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74 * a ret
17340 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 urn of [SQLITE_I
17350 47 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20 73 GNORE] has the s
17360 61 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b 53 ame effect as [S
17370 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a QLITE_DENY]..**.
17380 2a 2a 20 7b 48 31 32 35 31 30 7d 20 54 68 65 20 ** {H12510} The
17390 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
173a0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 to the authorize
173b0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 r callback is a
173c0 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 copy of.**
173d0 20 20 20 20 74 68 65 20 74 68 69 72 64 20 70 61 the third pa
173e0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b rameter to the [
173f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
17400 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 orizer()] interf
17410 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 ace..**.** {H125
17420 31 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 11} The second p
17430 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
17440 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 callback is an i
17450 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 nteger.**
17460 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 [SQLITE_COPY
17470 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 | action code] t
17480 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 hat specifies th
17490 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 e particular act
174a0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ion.**
174b0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 to be authorized
174c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 32 7d ..**.** {H12512}
174d0 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 The third throu
174e0 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 gh sixth paramet
174f0 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 ers to the callb
17500 61 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 ack are.**
17510 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 zero-termina
17520 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 ted strings that
17530 20 63 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20 20 20 contain.**
17540 20 20 20 20 20 61 64 64 69 74 69 6f 6e 61 6c 20 additional
17550 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 details about th
17560 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 e action to be a
17570 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a uthorized..**.**
17580 20 7b 48 31 32 35 32 30 7d 20 45 61 63 68 20 63 {H12520} Each c
17590 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
175a0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 set_authorizer()
175b0 5d 20 6f 76 65 72 72 69 64 65 73 0a 2a 2a 20 20 ] overrides.**
175c0 20 20 20 20 20 20 20 20 61 6e 79 20 70 72 65 76 any prev
175d0 69 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65 64 iously installed
175e0 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a authorizer..**.
175f0 2a 2a 20 7b 48 31 32 35 32 31 7d 20 41 20 4e 55 ** {H12521} A NU
17600 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d 65 LL authorizer me
17610 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74 68 ans that no auth
17620 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 orization.**
17630 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 69 callback i
17640 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a s invoked..**.**
17650 20 7b 48 31 32 35 32 32 7d 20 54 68 65 20 64 65 {H12522} The de
17660 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 fault authorizer
17670 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 is NULL..*/.int
17680 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 sqlite3_set_aut
17690 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 horizer(. sqlit
176a0 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 e3*,. int (*xAu
176b0 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f th)(void*,int,co
176c0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 nst char*,const
176d0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
176e0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a *,const char*),.
176f0 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 void *pUserDat
17700 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 a.);../*.** CAPI
17710 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 3REF: Authorizer
17720 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b 48 Return Codes {H
17730 31 32 35 39 30 7d 20 3c 48 31 32 35 30 30 3e 0a 12590} <H12500>.
17740 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 **.** The [sqlit
17750 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
17760 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 r | authorizer c
17770 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
17780 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e ] must.** return
17790 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f either [SQLITE_
177a0 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 OK] or one of th
177b0 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 ese two constant
177c0 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f s in order.** to
177d0 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 signal SQLite w
177e0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
177f0 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d e action is perm
17800 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a itted. See the.
17810 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f ** [sqlite3_set_
17820 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 authorizer | aut
17830 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 horizer document
17840 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 ation] for addit
17850 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 ional.** informa
17860 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 tion..*/.#define
17870 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 SQLITE_DENY 1
17880 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 /* Abort the
17890 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 SQL statement wi
178a0 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 th an error */.#
178b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 define SQLITE_IG
178c0 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 NORE 2 /* Don'
178d0 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 t allow access,
178e0 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 but don't genera
178f0 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a te an error */..
17900 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
17910 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f Authorizer Actio
17920 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 35 30 7d n Codes {H12550}
17930 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 <H12500>.**.**
17940 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 The [sqlite3_set
17950 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 _authorizer()] i
17960 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
17970 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 rs a callback fu
17980 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 nction.** that i
17990 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 s invoked to aut
179a0 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 horize certain S
179b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 QL statement act
179c0 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 ions. The.** se
179d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
179e0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 o the callback i
179f0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 s an integer cod
17a00 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 e that specifies
17a10 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 .** what action
17a20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 is being authori
17a30 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 zed. These are
17a40 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 the integer acti
17a50 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a on codes that.**
17a60 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
17a70 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 callback may be
17a80 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 passed..**.** Th
17a90 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 ese action code
17aa0 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 values signify w
17ab0 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 hat kind of oper
17ac0 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a ation is to be.*
17ad0 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 * authorized. T
17ae0 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 he 3rd and 4th p
17af0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 arameters to the
17b00 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a authorization.*
17b10 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 * callback funct
17b20 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 ion will be para
17b30 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 meters or NULL d
17b40 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 epending on whic
17b50 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f h of these.** co
17b60 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 des is used as t
17b70 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
17b80 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 61 ter. The 5th pa
17b90 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a rameter to the.*
17ba0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c * authorizer cal
17bb0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d lback is the nam
17bc0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
17bd0 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 e ("main", "temp
17be0 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 ",.** etc.) if a
17bf0 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 20 pplicable. The
17c00 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 6th parameter to
17c10 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
17c20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 callback.** is t
17c30 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 he name of the i
17c40 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 nner-most trigge
17c50 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 r or view that i
17c60 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
17c70 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 r.** the access
17c80 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 attempt or NULL
17c90 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 if this access a
17ca0 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 ttempt is direct
17cb0 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c ly from.** top-l
17cc0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a evel SQL code..*
17cd0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
17ce0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 31 7d 20 .**.** {H12551}
17cf0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
17d00 65 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 20 20 eter to an.**
17d10 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
17d20 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
17d30 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
17d40 62 61 63 6b 5d 20 69 73 20 61 6c 77 61 79 73 20 back] is always
17d50 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 an integer.**
17d60 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 [SQLITE_C
17d70 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 OPY | authorizer
17d80 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 code] that spec
17d90 69 66 69 65 73 20 77 68 61 74 20 61 63 74 69 6f ifies what actio
17da0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 n.** is
17db0 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 being authorize
17dc0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 32 d..**.** {H12552
17dd0 7d 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 } The 3rd and 4t
17de0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 h parameters to
17df0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
17e00 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
17e10 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 horizer | author
17e20 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b ization callback
17e30 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 ].** wi
17e40 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 ll be parameters
17e50 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 or NULL dependi
17e60 6e 67 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 20 ng on which.**
17e70 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
17e80 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 COPY | authorize
17e90 72 20 63 6f 64 65 5d 20 69 73 20 75 73 65 64 20 r code] is used
17ea0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
17eb0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b rameter..**.** {
17ec0 48 31 32 35 35 33 7d 20 54 68 65 20 35 74 68 20 H12553} The 5th
17ed0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
17ee0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
17ef0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
17f00 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 izer | authorize
17f10 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 r callback] is t
17f20 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 he name.**
17f30 20 20 20 20 6f 66 20 74 68 65 20 64 61 74 61 62 of the datab
17f40 61 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d ase (example: "m
17f50 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 74 ain", "temp", et
17f60 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c c.) if applicabl
17f70 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 34 e..**.** {H12554
17f80 7d 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 } The 6th parame
17f90 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 ter to the.**
17fa0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
17fb0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
17fc0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
17fd0 62 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d back] is the nam
17fe0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 e.** of
17ff0 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 the inner-most
18000 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 trigger or view
18010 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 that is responsi
18020 62 6c 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 ble for.**
18030 20 20 20 20 74 68 65 20 61 63 63 65 73 73 20 61 the access a
18040 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 ttempt or NULL i
18050 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 f this access at
18060 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c tempt is directl
18070 79 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 y from.**
18080 20 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c top-level SQL
18090 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a code..*/./*****
180a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
180b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
180c0 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a ****** 3rd *****
180d0 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a ******* 4th ****
180e0 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 *******/.#define
180f0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 SQLITE_CREATE_I
18100 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 NDEX 1
18110 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
18120 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
18130 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
18140 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 SQLITE_CREATE_TA
18150 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 BLE 2
18160 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
18170 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
18180 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
18190 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
181a0 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 P_INDEX 3
181b0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
181c0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
181d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
181e0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
181f0 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f _TABLE 4 /
18200 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
18210 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
18220 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
18230 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
18240 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a TRIGGER 5 /*
18250 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
18260 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
18270 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18280 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 TE_CREATE_TEMP_V
18290 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 IEW 6 /*
182a0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
182b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
182c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
182d0 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 E_CREATE_TRIGGER
182e0 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 7 /* T
182f0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
18300 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
18310 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
18320 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 _CREATE_VIEW
18330 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 8 /* Vi
18340 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
18350 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
18360 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18370 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 DELETE
18380 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 9 /* Tab
18390 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
183a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
183b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
183c0 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 ROP_INDEX
183d0 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 10 /* Inde
183e0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
183f0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
18400 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
18410 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 OP_TABLE
18420 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 11 /* Table
18430 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
18440 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
18450 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
18460 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 P_TEMP_INDEX
18470 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 12 /* Index
18480 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
18490 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
184a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
184b0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 _TEMP_TABLE
184c0 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 13 /* Table N
184d0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
184e0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
184f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
18500 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 TEMP_TRIGGER
18510 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 14 /* Trigger
18520 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
18530 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
18540 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
18550 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 EMP_VIEW 1
18560 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 5 /* View Name
18570 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
18580 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
18590 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 e SQLITE_DROP_TR
185a0 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 IGGER 16
185b0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
185c0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
185d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
185e0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 SQLITE_DROP_VIE
185f0 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 W 17
18600 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
18610 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
18620 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
18630 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 SQLITE_INSERT
18640 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 18
18650 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
18660 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
18670 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
18680 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 QLITE_PRAGMA
18690 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 19
186a0 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 /* Pragma Name
186b0 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 1st arg or NU
186c0 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 LL */.#define SQ
186d0 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 LITE_READ
186e0 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 20 /
186f0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
18700 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 Column Name
18710 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
18720 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 ITE_SELECT
18730 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 21 /*
18740 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
18750 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
18760 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18770 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 TE_TRANSACTION
18780 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 22 /*
18790 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
187a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
187b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
187c0 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 E_UPDATE
187d0 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 23 /* T
187e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 able Name C
187f0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a olumn Name *
18800 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
18810 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 _ATTACH
18820 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 24 /* Fi
18830 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 lename NU
18840 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
18850 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18860 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 DETACH
18870 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 25 /* Dat
18880 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c abase Name NUL
18890 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
188a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
188b0 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 LTER_TABLE
188c0 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 26 /* Data
188d0 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c base Name Tabl
188e0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
188f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
18900 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 INDEX
18910 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 27 /* Index
18920 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
18930 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
18940 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 efine SQLITE_ANA
18950 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 LYZE
18960 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 28 /* Table
18970 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
18980 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
18990 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
189a0 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 TE_VTABLE
189b0 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 29 /* Table N
189c0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 ame Module
189d0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
189e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
189f0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 VTABLE
18a00 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 30 /* Table Na
18a10 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e me Module N
18a20 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
18a30 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 ne SQLITE_FUNCTI
18a40 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 ON 3
18a50 31 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 1 /* Function
18a60 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 Name NULL
18a70 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
18a80 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 e SQLITE_COPY
18a90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
18aa0 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 /* No longer
18ab0 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 used */../*.** C
18ac0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 API3REF: Tracing
18ad0 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 And Profiling F
18ae0 75 6e 63 74 69 6f 6e 73 20 7b 48 31 32 32 38 30 unctions {H12280
18af0 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a } <S60400>.**.**
18b00 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
18b10 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 register callbac
18b20 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 k functions that
18b30 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 can be used for
18b40 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 .** tracing and
18b50 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 profiling the ex
18b60 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 ecution of SQL s
18b70 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a tatements..**.**
18b80 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 The callback fu
18b90 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 nction registere
18ba0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 d by sqlite3_tra
18bb0 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 ce() is invoked
18bc0 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 at.** various ti
18bd0 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 mes when an SQL
18be0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 statement is bei
18bf0 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 ng run by [sqlit
18c00 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 e3_step()]..** T
18c10 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
18c20 72 6e 73 20 61 20 55 54 46 2d 38 20 72 65 6e 64 rns a UTF-8 rend
18c30 65 72 69 6e 67 20 6f 66 20 74 68 65 20 53 51 4c ering of the SQL
18c40 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 0a statement text.
18c50 2a 2a 20 61 73 20 74 68 65 20 73 74 61 74 65 6d ** as the statem
18c60 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 ent first begins
18c70 20 65 78 65 63 75 74 69 6e 67 2e 20 20 41 64 64 executing. Add
18c80 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b itional callback
18c90 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 s occur.** as ea
18ca0 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 ch triggered sub
18cb0 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 program is enter
18cc0 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 ed. The callbac
18cd0 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a ks for triggers.
18ce0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 ** contain a UTF
18cf0 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 -8 SQL comment t
18d00 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 hat identifies t
18d10 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a he trigger..**.*
18d20 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 * The callback f
18d30 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
18d40 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 ed by sqlite3_pr
18d50 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b ofile() is invok
18d60 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 ed.** as each SQ
18d70 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 L statement fini
18d80 73 68 65 73 2e 20 20 54 68 65 20 70 72 6f 66 69 shes. The profi
18d90 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 le callback cont
18da0 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 ains.** the orig
18db0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 inal statement t
18dc0 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d ext and an estim
18dd0 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 ate of wall-cloc
18de0 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 k time.** of how
18df0 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 long that state
18e00 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e ment took to run
18e10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
18e20 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 41 50 te3_profile() AP
18e30 49 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 I is currently c
18e40 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 onsidered experi
18e50 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 mental and.** is
18e60 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
18e70 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e ge or removal in
18e80 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 a future releas
18e90 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 72 69 e..**.** The tri
18ea0 67 67 65 72 20 72 65 70 6f 72 74 69 6e 67 20 66 gger reporting f
18eb0 65 61 74 75 72 65 20 6f 66 20 74 68 65 20 74 72 eature of the tr
18ec0 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ace callback is
18ed0 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 65 78 considered.** ex
18ee0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 perimental and i
18ef0 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 s subject to cha
18f00 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69 nge or removal i
18f10 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
18f20 73 2e 0a 2a 2a 20 46 75 74 75 72 65 20 76 65 72 s..** Future ver
18f30 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
18f40 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6e might also add n
18f50 65 77 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 ew trace callbac
18f60 6b 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 k.** invocations
18f70 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
18f80 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 TS:.**.** {H1228
18f90 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 1} The callback
18fa0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 function registe
18fb0 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f red by [sqlite3_
18fc0 74 72 61 63 65 28 29 5d 20 69 73 0a 2a 2a 20 20 trace()] is.**
18fd0 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 whenever
18fe0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
18ff0 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74 t first begins t
19000 6f 20 65 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a o execute and.**
19010 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 whenev
19020 65 72 20 61 20 74 72 69 67 67 65 72 20 73 75 62 er a trigger sub
19030 70 72 6f 67 72 61 6d 20 66 69 72 73 74 20 62 65 program first be
19040 67 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a gins to run..**.
19050 2a 2a 20 7b 48 31 32 32 38 32 7d 20 45 61 63 68 ** {H12282} Each
19060 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
19070 33 5f 74 72 61 63 65 28 29 5d 20 6f 76 65 72 72 3_trace()] overr
19080 69 64 65 73 20 74 68 65 20 70 72 65 76 69 6f 75 ides the previou
19090 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 sly.**
190a0 72 65 67 69 73 74 65 72 65 64 20 74 72 61 63 65 registered trace
190b0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a callback..**.**
190c0 20 7b 48 31 32 32 38 33 7d 20 41 20 4e 55 4c 4c {H12283} A NULL
190d0 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 trace callback
190e0 64 69 73 61 62 6c 65 73 20 74 72 61 63 69 6e 67 disables tracing
190f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 34 7d ..**.** {H12284}
19100 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
19110 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 ent to the trace
19120 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 callback is a c
19130 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 opy of.**
19140 20 20 20 74 68 65 20 70 6f 69 6e 74 65 72 20 77 the pointer w
19150 68 69 63 68 20 77 61 73 20 74 68 65 20 33 72 64 hich was the 3rd
19160 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 argument to [sq
19170 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a lite3_trace()]..
19180 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 35 7d 20 54 **.** {H12285} T
19190 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
191a0 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 nt to the trace
191b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a callback is a.**
191c0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 zero-t
191d0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 erminated UTF-8
191e0 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e string containin
191f0 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 g the original t
19200 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ext.**
19210 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 of the SQL state
19220 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 ment as it was p
19230 61 73 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 assed into [sqli
19240 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
19250 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 ].** or
19260 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2c the equivalent,
19270 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 or an SQL comme
19280 6e 74 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 nt indicating th
19290 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 e beginning.**
192a0 20 20 20 20 20 20 20 20 6f 66 20 61 20 74 72 69 of a tri
192b0 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e gger subprogram.
192c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 37 7d 20 .**.** {H12287}
192d0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e The callback fun
192e0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 ction registered
192f0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f by [sqlite3_pro
19300 66 69 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b file()] is invok
19310 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 ed.** a
19320 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 s each SQL state
19330 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a ment finishes..*
19340 2a 0a 2a 2a 20 7b 48 31 32 32 38 38 7d 20 54 68 *.** {H12288} Th
19350 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
19360 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 r to the profile
19370 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 callback is a c
19380 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 opy of.**
19390 20 20 20 74 68 65 20 33 72 64 20 70 61 72 61 6d the 3rd param
193a0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
193b0 5f 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a _profile()]..**.
193c0 2a 2a 20 7b 48 31 32 32 38 39 7d 20 54 68 65 20 ** {H12289} The
193d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
193e0 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 to the profile
193f0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a callback is a.**
19400 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 zero-t
19410 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 erminated UTF-8
19420 73 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 string that cont
19430 61 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 ains the complet
19440 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20 e text of.**
19450 20 20 20 20 20 20 74 68 65 20 53 51 4c 20 73 74 the SQL st
19460 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 atement as it wa
19470 73 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 5b s processed by [
19480 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
19490 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 v2()].**
194a0 20 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c or the equival
194b0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 ent..**.** {H122
194c0 39 30 7d 20 54 68 65 20 74 68 69 72 64 20 70 61 90} The third pa
194d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 rameter to the p
194e0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 rofile callback
194f0 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a is an estimate.*
19500 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 * of th
19510 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f e number of nano
19520 73 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d seconds of wall-
19530 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 75 69 clock time requi
19540 72 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 red to.**
19550 20 20 20 72 75 6e 20 74 68 65 20 53 51 4c 20 73 run the SQL s
19560 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 tatement from st
19570 61 72 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a art to finish..*
19580 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f /.void *sqlite3_
19590 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 trace(sqlite3*,
195a0 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f void(*xTrace)(vo
195b0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 id*,const char*)
195c0 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a , void*);.void *
195d0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 sqlite3_profile(
195e0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 sqlite3*,. voi
195f0 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 d(*xProfile)(voi
19600 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 d*,const char*,s
19610 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 qlite3_uint64),
19620 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
19630 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 API3REF: Query P
19640 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b rogress Callback
19650 73 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 30 34 s {H12910} <S604
19660 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 00>.**.** This r
19670 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 outine configure
19680 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e s a callback fun
19690 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 ction - the.** p
196a0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b rogress callback
196b0 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b - that is invok
196c0 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 ed periodically
196d0 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 during long.** r
196e0 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 unning calls to
196f0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
19700 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
19710 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 )] and.** [sqlit
19720 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e e3_get_table()].
19730 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 An example use
19740 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 for this.** int
19750 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 erface is to kee
19760 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 p a GUI updated
19770 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 during a large q
19780 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 uery..**.** If t
19790 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c he progress call
197a0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e back returns non
197b0 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 -zero, the opera
197c0 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 tion is.** inter
197d0 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 rupted. This fe
197e0 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 ature can be use
197f0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 d to implement a
19800 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 .** "Cancel" but
19810 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 64 69 61 ton on a GUI dia
19820 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 log box..**.** I
19830 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
19840 20 7b 48 31 32 39 31 31 7d 20 54 68 65 20 63 61 {H12911} The ca
19850 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
19860 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 registered by sq
19870 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 lite3_progress_h
19880 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 andler().**
19890 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 is invoked
198a0 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 periodically dur
198b0 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 ing long running
198c0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 calls to.**
198d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 [sqlite3_s
198e0 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 tep()]..**.** {H
198f0 31 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67 72 12912} The progr
19900 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ess callback is
19910 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 invoked once for
19920 20 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c every N virtual
19930 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61 63 .** mac
19940 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 68 hine opcodes, wh
19950 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
19960 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ond argument to.
19970 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
19980 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 [sqlite3_progres
19990 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c s_handler()] cal
199a0 6c 20 74 68 61 74 20 72 65 67 69 73 74 65 72 65 l that registere
199b0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 d.** th
199c0 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 e callback. If
199d0 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 N is less than 1
199e0 2c 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 , sqlite3_progre
199f0 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 ss_handler().**
19a00 20 20 20 20 20 20 20 20 20 61 63 74 73 20 61 73 acts as
19a10 20 69 66 20 61 20 4e 55 4c 4c 20 70 72 6f 67 72 if a NULL progr
19a20 65 73 73 20 68 61 6e 64 6c 65 72 20 68 61 64 20 ess handler had
19a30 62 65 65 6e 20 73 70 65 63 69 66 69 65 64 2e 0a been specified..
19a40 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 33 7d 20 54 **.** {H12913} T
19a50 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c he progress call
19a60 62 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20 69 back itself is i
19a70 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 dentified by the
19a80 20 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20 20 third.**
19a90 20 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 argument to s
19aa0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f qlite3_progress_
19ab0 68 61 6e 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a 2a handler()..**.**
19ac0 20 7b 48 31 32 39 31 34 7d 20 54 68 65 20 66 6f {H12914} The fo
19ad0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f urth argument to
19ae0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 sqlite3_progres
19af0 73 5f 68 61 6e 64 6c 65 72 28 29 20 69 73 20 61 s_handler() is a
19b00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 6f 69 .** voi
19b10 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 d pointer passed
19b20 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73 to the progress
19b30 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 callback.**
19b40 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 65 function e
19b50 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 69 ach time it is i
19b60 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 nvoked..**.** {H
19b70 31 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c 6c 12915} If a call
19b80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
19b90 70 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e 20 p()] results in
19ba0 66 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70 63 fewer than N opc
19bb0 6f 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 odes.**
19bc0 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 2c being executed,
19bd0 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 then the progre
19be0 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e ss callback is n
19bf0 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a ever invoked..**
19c00 0a 2a 2a 20 7b 48 31 32 39 31 36 7d 20 45 76 65 .** {H12916} Eve
19c10 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ry call to [sqli
19c20 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e te3_progress_han
19c30 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 dler()].**
19c40 20 20 20 20 6f 76 65 72 77 72 69 74 65 73 20 61 overwrites a
19c50 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 ny previously re
19c60 67 69 73 74 65 72 65 64 20 70 72 6f 67 72 65 73 gistered progres
19c70 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a s handler..**.**
19c80 20 7b 48 31 32 39 31 37 7d 20 49 66 20 74 68 65 {H12917} If the
19c90 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
19ca0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 r callback is NU
19cb0 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72 LL then no progr
19cc0 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ess.**
19cd0 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b handler is invok
19ce0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 ed..**.** {H1291
19cf0 38 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 8} If the progre
19d00 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 ss callback retu
19d10 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68 rns a result oth
19d20 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a er than 0, then.
19d30 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
19d40 62 65 68 61 76 69 6f 72 20 69 73 20 61 20 69 66 behavior is a if
19d50 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 [sqlite3_interr
19d60 75 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20 upt()] had been
19d70 63 61 6c 6c 65 64 2e 0a 2a 2a 20 20 20 20 20 20 called..**
19d80 20 20 20 20 3c 53 33 30 35 30 30 3e 0a 2a 2f 0a <S30500>.*/.
19d90 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f void sqlite3_pro
19da0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 gress_handler(sq
19db0 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 lite3*, int, int
19dc0 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 (*)(void*), void
19dd0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
19de0 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e REF: Opening A N
19df0 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e ew Database Conn
19e00 65 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d 20 ection {H12700}
19e10 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S40200>.**.** T
19e20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 hese routines op
19e30 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 en an SQLite dat
19e40 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 abase file whose
19e50 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62 name is given b
19e60 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d y the.** filenam
19e70 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 e argument. The
19e80 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
19e90 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 t is interpreted
19ea0 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a as UTF-8 for.**
19eb0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
19ec0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e and sqlite3_open
19ed0 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 _v2() and as UTF
19ee0 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 -16 in the nativ
19ef0 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 e byte.** order
19f00 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e for sqlite3_open
19f10 31 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61 73 16(). A [databas
19f20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 e connection] ha
19f30 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a ndle is usually.
19f40 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a ** returned in *
19f50 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e ppDb, even if an
19f60 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 error occurs.
19f70 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 The only excepti
19f80 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 on is that.** if
19f90 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c SQLite is unabl
19fa0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 e to allocate me
19fb0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
19fc0 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
19fd0 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c t,.** a NULL wil
19fe0 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 l be written int
19ff0 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 o *ppDb instead
1a000 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 of a pointer to
1a010 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a the [sqlite3].**
1a020 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65 20 object. If the
1a030 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
1a040 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 ed (and/or creat
1a050 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 ed) successfully
1a060 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 , then.** [SQLIT
1a070 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 E_OK] is returne
1a080 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e d. Otherwise an
1a090 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 [error code] is
1a0a0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 0a returned. The.
1a0b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d ** [sqlite3_errm
1a0c0 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 sg()] or [sqlite
1a0d0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 3_errmsg16()] ro
1a0e0 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 utines can be us
1a0f0 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 ed to obtain.**
1a100 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 an English langu
1a110 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 age description
1a120 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a of the error..**
1a130 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 .** The default
1a140 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 encoding for the
1a150 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 database will b
1a160 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 e UTF-8 if.** sq
1a170 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 lite3_open() or
1a180 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1a190 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a ) is called and.
1a1a0 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 ** UTF-16 in the
1a1b0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
1a1c0 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 er if sqlite3_op
1a1d0 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a en16() is used..
1a1e0 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 **.** Whether or
1a1f0 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 not an error oc
1a200 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 curs when it is
1a210 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 opened, resource
1a220 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 s.** associated
1a230 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 with the [databa
1a240 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 se connection] h
1a250 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 andle should be
1a260 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 released by.** p
1a270 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 assing it to [sq
1a280 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 lite3_close()] w
1a290 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e hen it is no lon
1a2a0 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a ger required..**
1a2b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
1a2c0 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 open_v2() interf
1a2d0 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 ace works like s
1a2e0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a qlite3_open().**
1a2f0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 except that it
1a300 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 accepts two addi
1a310 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 tional parameter
1a320 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c s for additional
1a330 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 control.** over
1a340 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 the new databas
1a350 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 e connection. T
1a360 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 he flags paramet
1a370 65 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 er can take one
1a380 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 of.** the follow
1a390 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 ing three values
1a3a0 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d , optionally com
1a3b0 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a bined with the .
1a3c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
1a3d0 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 3a 0a 2a NOMUTEX] flag:.*
1a3e0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 *.** <dl>.** <dt
1a3f0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 >[SQLITE_OPEN_RE
1a400 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 ADONLY]</dt>.**
1a410 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 <dd>The database
1a420 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 is opened in re
1a430 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 ad-only mode. I
1a440 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 f the database d
1a450 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 oes not.** alrea
1a460 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 dy exist, an err
1a470 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c or is returned.<
1a480 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b /dd>.**.** <dt>[
1a490 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
1a4a0 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c WRITE]</dt>.** <
1a4b0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 dd>The database
1a4c0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
1a4d0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e ading and writin
1a4e0 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f g if possible, o
1a4f0 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c r reading.** onl
1a500 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 y if the file is
1a510 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 write protected
1a520 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e by the operatin
1a530 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 g system. In ei
1a540 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 ther.** case the
1a550 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 database must a
1a560 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 lready exist, ot
1a570 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 herwise an error
1a580 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 is returned.</d
1a590 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 d>.**.** <dt>[SQ
1a5a0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
1a5b0 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f ITE] | [SQLITE_O
1a5c0 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e PEN_CREATE]</dt>
1a5d0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 .** <dd>The data
1a5e0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 base is opened f
1a5f0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 or reading and w
1a600 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 riting, and is c
1a610 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 reates it if.**
1a620 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 it does not alre
1a630 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 ady exist. This
1a640 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 is the behavior
1a650 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 that is always u
1a660 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 sed for.** sqlit
1a670 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
1a680 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c lite3_open16().<
1a690 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a /dd>.** </dl>.**
1a6a0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 .** If the 3rd p
1a6b0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
1a6c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
1a6d0 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a not one of the.
1a6e0 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 ** combinations
1a6f0 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f shown above or o
1a700 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e ne of the combin
1a710 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f ations shown abo
1a720 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 ve combined.** w
1a730 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
1a740 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c OPEN_NOMUTEX] fl
1a750 61 67 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 ag, then the beh
1a760 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
1a770 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ed..**.** If the
1a780 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f [SQLITE_OPEN_NO
1a790 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 MUTEX] flag is s
1a7a0 65 74 2c 20 74 68 65 6e 20 6d 75 74 65 78 65 73 et, then mutexes
1a7b0 20 6f 6e 20 74 68 65 0a 2a 2a 20 6f 70 65 6e 65 on the.** opene
1a7c0 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e d [database conn
1a7d0 65 63 74 69 6f 6e 5d 20 61 72 65 20 64 69 73 61 ection] are disa
1a7e0 62 6c 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 bled and the app
1a7f0 6c 69 61 74 69 6f 6e 20 6d 75 73 74 0a 2a 2a 20 liation must.**
1a800 69 6e 73 75 72 65 20 74 68 61 74 20 61 63 63 65 insure that acce
1a810 73 73 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 ss to the [datab
1a820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
1a830 61 6e 64 20 69 74 73 20 61 73 73 6f 63 69 61 74 and its associat
1a840 65 64 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 ed.** [prepared
1a850 73 74 61 74 65 6d 65 6e 74 73 5d 20 69 73 20 73 statements] is s
1a860 65 72 69 61 6c 69 7a 65 64 2e 20 20 54 68 65 20 erialized. The
1a870 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d [SQLITE_OPEN_NOM
1a880 55 54 45 58 5d 20 66 6c 61 67 0a 2a 2a 20 69 73 UTEX] flag.** is
1a890 20 74 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 the default beh
1a8a0 61 76 69 6f 72 20 69 73 20 53 51 4c 69 74 65 20 avior is SQLite
1a8b0 69 73 20 63 6f 6e 66 69 67 75 72 65 64 20 75 73 is configured us
1a8c0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ing the.** [SQLI
1a8d0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
1a8e0 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 HREAD] or [SQLIT
1a8f0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
1a900 48 52 45 41 44 5d 20 6f 70 74 69 6f 6e 73 0a 2a HREAD] options.*
1a910 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f * to [sqlite3_co
1a920 6e 66 69 67 28 29 5d 2e 20 20 54 68 65 20 5b 53 nfig()]. The [S
1a930 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
1a940 45 58 5d 20 66 6c 61 67 20 6f 6e 6c 79 20 6d 61 EX] flag only ma
1a950 6b 65 73 20 61 0a 2a 2a 20 64 69 66 66 65 72 65 kes a.** differe
1a960 6e 63 65 20 77 68 65 6e 20 53 51 4c 69 74 65 20 nce when SQLite
1a970 69 73 20 69 6e 20 69 74 73 20 64 65 66 61 75 6c is in its defaul
1a980 74 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 t [SQLITE_CONFIG
1a990 5f 53 45 52 49 41 4c 49 5a 45 44 5d 20 6d 6f 64 _SERIALIZED] mod
1a9a0 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 e..**.** If the
1a9b0 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 filename is ":me
1a9c0 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 mory:", then a p
1a9d0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 rivate, temporar
1a9e0 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 y in-memory data
1a9f0 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 base.** is creat
1aa00 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 ed for the conne
1aa10 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d ction. This in-
1aa20 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 memory database
1aa30 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e will vanish when
1aa40 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
1aa50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 connection is c
1aa60 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 losed. Future v
1aa70 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
1aa80 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 e might.** make
1aa90 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 use of additiona
1aaa0 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 l special filena
1aab0 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 mes that begin w
1aac0 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 ith the ":" char
1aad0 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 acter..** It is
1aae0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 recommended that
1aaf0 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 when a database
1ab00 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c filename actual
1ab10 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 ly does begin wi
1ab20 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 th.** a ":" char
1ab30 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 acter you should
1ab40 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 prefix the file
1ab50 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 name with a path
1ab60 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 name such as.**
1ab70 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d "./" to avoid am
1ab80 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 biguity..**.** I
1ab90 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 f the filename i
1aba0 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e s an empty strin
1abb0 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 g, then a privat
1abc0 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 e, temporary.**
1abd0 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 on-disk database
1abe0 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 will be created
1abf0 2e 20 20 54 68 69 73 20 70 72 69 76 61 74 65 20 . This private
1ac00 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
1ac10 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c .** automaticall
1ac20 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f y deleted as soo
1ac30 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 n as the databas
1ac40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
1ac50 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 closed..**.** Th
1ac60 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
1ac70 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 er to sqlite3_op
1ac80 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e en_v2() is the n
1ac90 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 ame of the.** [s
1aca0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
1acb0 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 ct that defines
1acc0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
1acd0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 stem interface t
1ace0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 hat.** the new d
1acf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1ad00 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 on should use.
1ad10 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
1ad20 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 rameter is.** a
1ad30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
1ad40 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 n the default [s
1ad50 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
1ad60 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a ct is used..**.*
1ad70 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e * <b>Note to Win
1ad80 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 dows users:</b>
1ad90 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 The encoding us
1ada0 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e ed for the filen
1adb0 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 ame argument.**
1adc0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 of sqlite3_open(
1add0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 ) and sqlite3_op
1ade0 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 en_v2() must be
1adf0 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 UTF-8, not whate
1ae00 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 ver.** codepage
1ae10 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 is currently def
1ae20 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 ined. Filenames
1ae30 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 containing inte
1ae40 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 rnational.** cha
1ae50 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 racters must be
1ae60 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 converted to UTF
1ae70 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 -8 prior to pass
1ae80 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a ing them into.**
1ae90 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
1aea0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
1aeb0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 v2()..**.** INVA
1aec0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
1aed0 31 32 37 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 12701} The [sqli
1aee0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
1aef0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c lite3_open16()],
1af00 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
1af10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
1af20 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 2()] interfaces
1af30 63 72 65 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 create a new.**
1af40 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 [databa
1af50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
1af60 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a ssociated with.*
1af70 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 64 * the d
1af80 61 74 61 62 61 73 65 20 66 69 6c 65 20 67 69 76 atabase file giv
1af90 65 6e 20 69 6e 20 74 68 65 69 72 20 66 69 72 73 en in their firs
1afa0 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a t parameter..**.
1afb0 2a 2a 20 7b 48 31 32 37 30 32 7d 20 54 68 65 20 ** {H12702} The
1afc0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
1afd0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 t is interpreted
1afe0 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 as UTF-8.**
1aff0 20 20 20 20 20 20 66 6f 72 20 5b 73 71 6c 69 74 for [sqlit
1b000 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b e3_open()] and [
1b010 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1b020 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 )] and as UTF-16
1b030 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 .** in
1b040 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 the native byte
1b050 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 order for [sqlit
1b060 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a e3_open16()]..**
1b070 0a 2a 2a 20 7b 48 31 32 37 30 33 7d 20 41 20 73 .** {H12703} A s
1b080 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 uccessful invoca
1b090 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
1b0a0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
1b0b0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a e3_open16()],.**
1b0c0 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 or [sq
1b0d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
1b0e0 20 77 72 69 74 65 73 20 61 20 70 6f 69 6e 74 65 writes a pointe
1b0f0 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 r to a new.**
1b100 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 [database
1b110 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 connection] int
1b120 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b o *ppDb..**.** {
1b130 48 31 32 37 30 34 7d 20 54 68 65 20 5b 73 71 6c H12704} The [sql
1b140 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
1b150 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
1b160 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 , and.**
1b170 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f [sqlite3_open_
1b180 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 v2()] interfaces
1b190 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
1b1a0 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65 73 73 OK] upon success
1b1b0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 ,.** or
1b1c0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 an appropriate
1b1d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 [error code] on
1b1e0 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b failure..**.** {
1b1f0 48 31 32 37 30 36 7d 20 54 68 65 20 64 65 66 61 H12706} The defa
1b200 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e ult text encodin
1b210 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 g for a new data
1b220 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69 base created usi
1b230 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ng.** [
1b240 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 sqlite3_open()]
1b250 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e or [sqlite3_open
1b260 5f 76 32 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 _v2()] will be U
1b270 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 TF-8..**.** {H12
1b280 37 30 37 7d 20 54 68 65 20 64 65 66 61 75 6c 74 707} The default
1b290 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 text encoding f
1b2a0 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 or a new databas
1b2b0 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a e created using.
1b2c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
1b2d0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77 ite3_open16()] w
1b2e0 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a ill be UTF-16..*
1b2f0 2a 0a 2a 2a 20 7b 48 31 32 37 30 39 7d 20 54 68 *.** {H12709} Th
1b300 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 e [sqlite3_open(
1b310 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 F,D)] interface
1b320 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f is equivalent to
1b330 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
1b340 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c lite3_open_v2(F,
1b350 44 2c 47 2c 30 29 5d 20 77 68 65 72 65 20 74 68 D,G,0)] where th
1b360 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 69 73 e G parameter is
1b370 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 .** [SQ
1b380 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
1b390 49 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 ITE]|[SQLITE_OPE
1b3a0 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a N_CREATE]..**.**
1b3b0 20 7b 48 31 32 37 31 31 7d 20 49 66 20 74 68 65 {H12711} If the
1b3c0 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 G parameter to
1b3d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
1b3e0 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 (F,D,G,V)] conta
1b3f0 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ins the.**
1b400 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 bit value [S
1b410 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
1b420 4e 4c 59 5d 20 74 68 65 6e 20 74 68 65 20 64 61 NLY] then the da
1b430 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
1b440 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 .** for
1b450 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a reading only..*
1b460 2a 0a 2a 2a 20 7b 48 31 32 37 31 32 7d 20 49 66 *.** {H12712} If
1b470 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 the G parameter
1b480 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 to [sqlite3_ope
1b490 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 n_v2(F,D,G,V)] c
1b4a0 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 ontains the.**
1b4b0 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 bit valu
1b4c0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 e [SQLITE_OPEN_R
1b4d0 45 41 44 57 52 49 54 45 5d 20 74 68 65 6e 20 74 EADWRITE] then t
1b4e0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
1b4f0 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 pened.**
1b500 20 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 reading and wr
1b510 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c iting if possibl
1b520 65 2c 20 6f 72 20 66 6f 72 20 72 65 61 64 69 6e e, or for readin
1b530 67 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a g only if the.**
1b540 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 20 69 file i
1b550 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 s write protecte
1b560 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 d by the operati
1b570 6e 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a ng system..**.**
1b580 20 7b 48 31 32 37 31 33 7d 20 49 66 20 74 68 65 {H12713} If the
1b590 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 G parameter to
1b5a0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 [sqlite3_open(v2
1b5b0 28 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 (F,D,G,V)] omits
1b5c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
1b5d0 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 bit value [SQLI
1b5e0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 TE_OPEN_CREATE]
1b5f0 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 and the database
1b600 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 does not.**
1b610 20 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79 previously
1b620 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 exist, an error
1b630 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
1b640 0a 2a 2a 20 7b 48 31 32 37 31 34 7d 20 49 66 20 .** {H12714} If
1b650 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 the G parameter
1b660 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
1b670 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f (v2(F,D,G,V)] co
1b680 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 ntains the.**
1b690 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 bit value
1b6a0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
1b6b0 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 EATE] and the da
1b6c0 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a tabase does not.
1b6d0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65 76 ** prev
1b6e0 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 74 68 iously exist, th
1b6f0 65 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 en an attempt is
1b700 20 6d 61 64 65 20 74 6f 20 63 72 65 61 74 65 20 made to create
1b710 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 and.**
1b720 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 64 initialize the d
1b730 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b atabase..**.** {
1b740 48 31 32 37 31 37 7d 20 49 66 20 74 68 65 20 66 H12717} If the f
1b750 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
1b760 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 to [sqlite3_ope
1b770 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f n()], [sqlite3_o
1b780 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 pen16()],.**
1b790 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 or [sqlite
1b7a0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 3_open_v2()] is
1b7b0 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e ":memory:", then
1b7c0 20 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 an private,.**
1b7d0 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 72 ephemer
1b7e0 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 al, in-memory da
1b7f0 74 61 62 61 73 65 20 69 73 20 63 72 65 61 74 65 tabase is create
1b800 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 d for the connec
1b810 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20 tion..**
1b820 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 <todo>Is SQLIT
1b830 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 E_OPEN_CREATE|SQ
1b840 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
1b850 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 ITE required.**
1b860 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 in sqli
1b870 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f te3_open_v2()?</
1b880 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 todo>.**.** {H12
1b890 37 31 39 7d 20 49 66 20 74 68 65 20 66 69 6c 65 719} If the file
1b8a0 6e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20 name is NULL or
1b8b0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c an empty string,
1b8c0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c then a private,
1b8d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 68 .** eph
1b8e0 65 6d 65 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 emeral on-disk d
1b8f0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 atabase will be
1b900 63 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 created..**
1b910 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 <todo>Is SQ
1b920 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
1b930 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 |SQLITE_OPEN_REA
1b940 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64 0a DWRITE required.
1b950 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 ** in s
1b960 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
1b970 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b ?</todo>.**.** {
1b980 48 31 32 37 32 31 7d 20 54 68 65 20 5b 64 61 74 H12721} The [dat
1b990 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1b9a0 5d 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 ] created by [sq
1b9b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c lite3_open_v2(F,
1b9c0 44 2c 47 2c 56 29 5d 0a 2a 2a 20 20 20 20 20 20 D,G,V)].**
1b9d0 20 20 20 20 77 69 6c 6c 20 75 73 65 20 74 68 65 will use the
1b9e0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
1b9f0 62 6a 65 63 74 20 69 64 65 6e 74 69 66 69 65 64 bject identified
1ba00 20 62 79 20 74 68 65 20 56 20 70 61 72 61 6d 65 by the V parame
1ba10 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ter,.**
1ba20 20 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 or the default
1ba30 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
1ba40 6a 65 63 74 20 69 66 20 56 20 69 73 20 61 20 4e ject if V is a N
1ba50 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
1ba60 2a 2a 20 7b 48 31 32 37 32 33 7d 20 54 77 6f 20 ** {H12723} Two
1ba70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1ba80 74 69 6f 6e 73 5d 20 77 69 6c 6c 20 73 68 61 72 tions] will shar
1ba90 65 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 e a common cache
1baa0 20 69 66 20 62 6f 74 68 20 77 65 72 65 0a 2a 2a if both were.**
1bab0 20 20 20 20 20 20 20 20 20 20 6f 70 65 6e 65 64 opened
1bac0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 56 with the same V
1bad0 46 53 20 77 68 69 6c 65 20 5b 73 68 61 72 65 64 FS while [shared
1bae0 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 77 61 73 cache mode] was
1baf0 20 65 6e 61 62 6c 65 64 20 61 6e 64 0a 2a 2a 20 enabled and.**
1bb00 20 20 20 20 20 20 20 20 20 69 66 20 62 6f 74 68 if both
1bb10 20 66 69 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61 filenames compa
1bb20 72 65 20 65 71 75 61 6c 20 75 73 69 6e 67 20 6d re equal using m
1bb30 65 6d 63 6d 70 28 29 20 61 66 74 65 72 20 68 61 emcmp() after ha
1bb40 76 69 6e 67 20 62 65 65 6e 0a 2a 2a 20 20 20 20 ving been.**
1bb50 20 20 20 20 20 20 70 72 6f 63 65 73 73 65 64 20 processed
1bb60 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
1bb70 76 66 73 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e vfs | xFullPathn
1bb80 61 6d 65 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 ame] method of t
1bb90 68 65 20 56 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73 he VFS..*/.int s
1bba0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 qlite3_open(. c
1bbb0 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e onst char *filen
1bbc0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 ame, /* Databa
1bbd0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 se filename (UTF
1bbe0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 -8) */. sqlite3
1bbf0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 **ppDb
1bc00 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
1bc10 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a db handle */.);.
1bc20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e int sqlite3_open
1bc30 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 16(. const void
1bc40 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a *filename, /*
1bc50 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 Database filena
1bc60 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 me (UTF-16) */.
1bc70 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 sqlite3 **ppDb
1bc80 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a /* OUT:
1bc90 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c SQLite db handl
1bca0 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 e */.);.int sqli
1bcb0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 te3_open_v2(. c
1bcc0 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e onst char *filen
1bcd0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 ame, /* Databa
1bce0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 se filename (UTF
1bcf0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 -8) */. sqlite3
1bd00 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 **ppDb,
1bd10 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
1bd20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 db handle */. i
1bd30 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 nt flags,
1bd40 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 /* Flags
1bd50 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
1bd60 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 *zVfs /*
1bd70 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 Name of VFS modu
1bd80 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a le to use */.);.
1bd90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1bda0 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 Error Codes And
1bdb0 20 4d 65 73 73 61 67 65 73 20 7b 48 31 32 38 30 Messages {H1280
1bdc0 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 0} <S60200>.**.*
1bdd0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 * The sqlite3_er
1bde0 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 rcode() interfac
1bdf0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 e returns the nu
1be00 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f meric [result co
1be10 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e de] or.** [exten
1be20 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d ded result code]
1be30 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 for the most re
1be40 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 cent failed sqli
1be50 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a te3_* API call.*
1be60 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
1be70 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f h a [database co
1be80 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 nnection]. If a
1be90 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 prior API call f
1bea0 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 ailed.** but the
1beb0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 most recent API
1bec0 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c call succeeded,
1bed0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
1bee0 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 e from.** sqlite
1bef0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 3_errcode() is u
1bf00 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
1bf10 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d The sqlite3_errm
1bf20 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 sg() and sqlite3
1bf30 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 _errmsg16() retu
1bf40 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 rn English-langu
1bf50 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 age.** text that
1bf60 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 describes the e
1bf70 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 rror, as either
1bf80 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 UTF-8 or UTF-16
1bf90 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a respectively..**
1bfa0 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 Memory to hold
1bfb0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
1bfc0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 e string is mana
1bfd0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a ged internally..
1bfe0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
1bff0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 on does not need
1c000 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 to worry about
1c010 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 freeing the resu
1c020 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 lt..** However,
1c030 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 the error string
1c040 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 might be overwr
1c050 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 itten or dealloc
1c060 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 ated by.** subse
1c070 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f quent calls to o
1c080 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 ther SQLite inte
1c090 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e rface functions.
1c0a0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 .**.** If an int
1c0b0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 erface fails wit
1c0c0 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c h SQLITE_MISUSE,
1c0d0 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 that means the
1c0e0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 interface.** was
1c0f0 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 invoked incorre
1c100 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c ctly by the appl
1c110 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 ication. In tha
1c120 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 t case, the.** e
1c130 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 rror code and me
1c140 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 ssage may or may
1c150 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a not be set..**.
1c160 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
1c170 2a 0a 2a 2a 20 7b 48 31 32 38 30 31 7d 20 54 68 *.** {H12801} Th
1c180 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f e [sqlite3_errco
1c190 64 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 de(D)] interface
1c1a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
1c1b0 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 eric.**
1c1c0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f [result code] o
1c1d0 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 r [extended resu
1c1e0 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 lt code] for the
1c1f0 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a most recently.*
1c200 2a 20 20 20 20 20 20 20 20 20 20 66 61 69 6c 65 * faile
1c210 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c d interface call
1c220 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
1c230 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
1c240 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a onnection] D..**
1c250 0a 2a 2a 20 7b 48 31 32 38 30 33 7d 20 54 68 65 .** {H12803} The
1c260 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
1c270 28 44 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 (D)] and [sqlite
1c280 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a 3_errmsg16(D)].*
1c290 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 * inter
1c2a0 66 61 63 65 73 20 72 65 74 75 72 6e 20 45 6e 67 faces return Eng
1c2b0 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 lish-language te
1c2c0 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 xt that describe
1c2d0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 s.** th
1c2e0 65 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 6d e error in the m
1c2f0 6f 73 74 6c 79 20 72 65 63 65 6e 74 6c 79 20 66 ostly recently f
1c300 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 ailed interface
1c310 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20 call,.**
1c320 20 20 65 6e 63 6f 64 65 64 20 61 73 20 65 69 74 encoded as eit
1c330 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 her UTF-8 or UTF
1c340 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 -16 respectively
1c350 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 37 7d ..**.** {H12807}
1c360 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 The strings ret
1c370 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
1c380 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 3_errmsg()] and
1c390 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 [sqlite3_errmsg1
1c3a0 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 6()].**
1c3b0 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c are valid until
1c3c0 20 74 68 65 20 6e 65 78 74 20 53 51 4c 69 74 65 the next SQLite
1c3d0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2e interface call.
1c3e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 38 7d 20 .**.** {H12808}
1c3f0 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 Calls to API rou
1c400 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f tines that do no
1c410 74 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f t return an erro
1c420 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 r code.**
1c430 20 20 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 (example: [sq
1c440 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
1c450 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 ()]) do not.**
1c460 20 20 20 20 20 20 20 20 63 68 61 6e 67 65 20 74 change t
1c470 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 72 he error code or
1c480 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e 65 message returne
1c490 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 d by.**
1c4a0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
1c4b0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 e()], [sqlite3_e
1c4c0 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 rrmsg()], or [sq
1c4d0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 lite3_errmsg16()
1c4e0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 39 ]..**.** {H12809
1c4f0 7d 20 49 6e 74 65 72 66 61 63 65 73 20 74 68 61 } Interfaces tha
1c500 74 20 61 72 65 20 6e 6f 74 20 61 73 73 6f 63 69 t are not associ
1c510 61 74 65 64 20 77 69 74 68 20 61 20 73 70 65 63 ated with a spec
1c520 69 66 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 ific.**
1c530 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1c540 63 74 69 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73 ction] (examples
1c550 3a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 :.** [s
1c560 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 qlite3_mprintf()
1c570 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e ] or [sqlite3_en
1c580 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 able_shared_cach
1c590 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 e()].**
1c5a0 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 do not change t
1c5b0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e he values return
1c5c0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 ed by.**
1c5d0 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f [sqlite3_errco
1c5e0 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f de()], [sqlite3_
1c5f0 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 errmsg()], or [s
1c600 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
1c610 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 )]..*/.int sqlit
1c620 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 e3_errcode(sqlit
1c630 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 e3 *db);.const c
1c640 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 har *sqlite3_err
1c650 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 msg(sqlite3*);.c
1c660 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
1c670 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 e3_errmsg16(sqli
1c680 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
1c690 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 PI3REF: SQL Stat
1c6a0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 ement Object {H1
1c6b0 33 30 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 3000} <H13010>.*
1c6c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 * KEYWORDS: {pre
1c6d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d pared statement}
1c6e0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 {prepared state
1c6f0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 ments}.**.** An
1c700 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
1c710 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e object represen
1c720 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 ts a single SQL
1c730 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 statement..** Th
1c740 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 is object is var
1c750 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 iously known as
1c760 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 a "prepared stat
1c770 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 ement" or a.** "
1c780 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 compiled SQL sta
1c790 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c tement" or simpl
1c7a0 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e y as a "statemen
1c7b0 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 t"..**.** The li
1c7c0 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e fe of a statemen
1c7d0 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f t object goes so
1c7e0 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 mething like thi
1c7f0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a s:.**.** <ol>.**
1c800 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 <li> Create the
1c810 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 object using [s
1c820 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1c830 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 2()] or a relate
1c840 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 d.** functi
1c850 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 on..** <li> Bind
1c860 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 values to [host
1c870 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 parameters] usi
1c880 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 ng the sqlite3_b
1c890 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 ind_*().**
1c8a0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c interfaces..** <
1c8b0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 li> Run the SQL
1c8c0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 by calling [sqli
1c8d0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 te3_step()] one
1c8e0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a or more times..*
1c8f0 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 * <li> Reset the
1c900 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 statement using
1c910 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
1c920 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a )] then go back.
1c930 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 ** to step
1c940 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 2. Do this zero
1c950 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a or more times..
1c960 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 ** <li> Destroy
1c970 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 the object using
1c980 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
1c990 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a ze()]..** </ol>.
1c9a0 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 **.** Refer to d
1c9b0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 ocumentation on
1c9c0 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f individual metho
1c9d0 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 ds above for add
1c9e0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 itional.** infor
1c9f0 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 mation..*/.typed
1ca00 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
1ca10 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 3_stmt sqlite3_s
1ca20 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 tmt;../*.** CAPI
1ca30 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 3REF: Run-time L
1ca40 69 6d 69 74 73 20 7b 48 31 32 37 36 30 7d 20 3c imits {H12760} <
1ca50 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S20600>.**.** Th
1ca60 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c is interface all
1ca70 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ows the size of
1ca80 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 various construc
1ca90 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 ts to be limited
1caa0 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 .** on a connect
1cab0 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f ion by connectio
1cac0 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 n basis. The fi
1cad0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
1cae0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 the.** [databas
1caf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 e connection] wh
1cb00 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 ose limit is to
1cb10 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 be set or querie
1cb20 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e d. The.** secon
1cb30 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f d parameter is o
1cb40 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 ne of the [limit
1cb50 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 categories] tha
1cb60 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c t define a.** cl
1cb70 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 ass of construct
1cb80 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d s to be size lim
1cb90 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 ited. The third
1cba0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
1cbb0 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 e.** new limit f
1cbc0 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 or that construc
1cbd0 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e t. The function
1cbe0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 returns the old
1cbf0 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 limit..**.** If
1cc00 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 the new limit i
1cc10 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d s a negative num
1cc20 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 ber, the limit i
1cc30 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 s unchanged..**
1cc40 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61 For the limit ca
1cc50 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 tegory of SQLITE
1cc60 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 _LIMIT_XYZ there
1cc70 20 69 73 20 61 20 68 61 72 64 20 75 70 70 65 72 is a hard upper
1cc80 0a 2a 2a 20 62 6f 75 6e 64 20 73 65 74 20 62 79 .** bound set by
1cc90 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 a compile-time
1cca0 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
1ccb0 61 63 72 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54 acro named SQLIT
1ccc0 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54 E_MAX_XYZ..** (T
1ccd0 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 he "_LIMIT_" in
1cce0 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e the name is chan
1ccf0 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 ged to "_MAX_".)
1cd00 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20 .** Attempts to
1cd10 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 increase a limit
1cd20 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 above its hard
1cd30 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a upper bound are.
1cd40 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e ** silently trun
1cd50 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 cated to the har
1cd60 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a d upper limit..*
1cd70 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 *.** Run time li
1cd80 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 mits are intende
1cd90 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 d for use in app
1cda0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d lications that m
1cdb0 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 anage.** both th
1cdc0 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c eir own internal
1cdd0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c database and al
1cde0 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 so databases tha
1cdf0 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 t are controlled
1ce00 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 .** by untrusted
1ce10 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 external source
1ce20 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 s. An example a
1ce30 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 pplication might
1ce40 20 62 65 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77 be a.** webbrow
1ce50 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 ser that has its
1ce60 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 own databases f
1ce70 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f or storing histo
1ce80 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 ry and.** separa
1ce90 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e te databases con
1cea0 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 trolled by JavaS
1ceb0 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f cript applicatio
1cec0 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a ns downloaded.**
1ced0 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 off the Interne
1cee0 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c t. The internal
1cef0 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 databases can b
1cf00 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c e given the.** l
1cf10 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 arge, default li
1cf20 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 mits. Databases
1cf30 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 managed by exte
1cf40 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e rnal sources can
1cf50 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 .** be given muc
1cf60 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 h smaller limits
1cf70 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 designed to pre
1cf80 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 vent a denial of
1cf90 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 service.** atta
1cfa0 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 ck. Developers
1cfb0 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 might also want
1cfc0 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 to use the [sqli
1cfd0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
1cfe0 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 er()].** interfa
1cff0 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f ce to further co
1d000 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 ntrol untrusted
1d010 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f SQL. The size o
1d020 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a f the database.*
1d030 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 * created by an
1d040 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 untrusted script
1d050 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 can be containe
1d060 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b d using the.** [
1d070 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 max_page_count]
1d080 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 [PRAGMA]..**.**
1d090 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d New run-time lim
1d0a0 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 it categories ma
1d0b0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
1d0c0 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a ture releases..*
1d0d0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
1d0e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 32 7d 20 .**.** {H12762}
1d0f0 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c A successful cal
1d100 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 l to [sqlite3_li
1d110 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 mit(D,C,V)] wher
1d120 65 20 56 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 e V is.**
1d130 20 20 20 70 6f 73 69 74 69 76 65 20 63 68 61 6e positive chan
1d140 67 65 73 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e ges the limit on
1d150 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e the size of con
1d160 73 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a struct C in the.
1d170 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 ** [dat
1d180 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1d190 5d 20 44 20 74 6f 20 74 68 65 20 6c 65 73 73 65 ] D to the lesse
1d1a0 72 20 6f 66 20 56 20 61 6e 64 20 74 68 65 20 68 r of V and the h
1d1b0 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 20 20 20 ard upper.**
1d1c0 20 20 20 20 20 20 62 6f 75 6e 64 20 6f 6e 20 74 bound on t
1d1d0 68 65 20 73 69 7a 65 20 6f 66 20 43 20 74 68 61 he size of C tha
1d1e0 74 20 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70 t is set at comp
1d1f0 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 ile-time..**.**
1d200 7b 48 31 32 37 36 36 7d 20 41 20 73 75 63 63 65 {H12766} A succe
1d210 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
1d220 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 qlite3_limit(D,C
1d230 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 20 ,V)] where V is
1d240 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 negative.**
1d250 20 20 20 20 20 6c 65 61 76 65 73 20 74 68 65 20 leaves the
1d260 73 74 61 74 65 20 6f 66 20 74 68 65 20 5b 64 61 state of the [da
1d270 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1d280 6e 5d 20 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a n] D unchanged..
1d290 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 39 7d 20 41 **.** {H12769} A
1d2a0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
1d2b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d to [sqlite3_lim
1d2c0 69 74 28 44 2c 43 2c 56 29 5d 20 72 65 74 75 72 it(D,C,V)] retur
1d2d0 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ns the.**
1d2e0 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 value of the
1d2f0 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a limit on the siz
1d300 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43 e of construct C
1d310 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 in the.**
1d320 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f [database co
1d330 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 61 73 20 69 nnection] D as i
1d340 74 20 77 61 73 20 70 72 69 6f 72 20 74 6f 20 74 t was prior to t
1d350 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 he call..*/.int
1d360 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 sqlite3_limit(sq
1d370 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 lite3*, int id,
1d380 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a int newVal);../*
1d390 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 .** CAPI3REF: Ru
1d3a0 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 n-Time Limit Cat
1d3b0 65 67 6f 72 69 65 73 20 7b 48 31 32 37 39 30 7d egories {H12790}
1d3c0 20 3c 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 <H12760>.** KEY
1d3d0 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 WORDS: {limit ca
1d3e0 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 tegory} {limit c
1d3f0 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a ategories}.**.**
1d400 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
1d410 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 define various
1d420 61 73 70 65 63 74 73 20 6f 66 20 61 20 5b 64 61 aspects of a [da
1d430 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1d440 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 n].** that can b
1d450 65 20 6c 69 6d 69 74 65 64 20 69 6e 20 73 69 7a e limited in siz
1d460 65 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73 e by calls to [s
1d470 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e qlite3_limit()].
1d480 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67 73 .** The meanings
1d490 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 of the various
1d4a0 6c 69 6d 69 74 73 20 61 72 65 20 61 73 20 66 6f limits are as fo
1d4b0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c llows:.**.** <dl
1d4c0 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f >.** <dt>SQLITE_
1d4d0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 LIMIT_LENGTH</dt
1d4e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
1d4f0 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 imum size of any
1d500 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 string or BLOB
1d510 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 or table row.<dd
1d520 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
1d530 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e TE_LIMIT_SQL_LEN
1d540 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e GTH</dt>.** <dd>
1d550 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 The maximum leng
1d560 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 th of an SQL sta
1d570 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a tement.</dd>.**.
1d580 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ** <dt>SQLITE_LI
1d590 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a MIT_COLUMN</dt>.
1d5a0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
1d5b0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c um number of col
1d5c0 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 umns in a table
1d5d0 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e definition or in
1d5e0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 the.** result s
1d5f0 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 6f et of a SELECT o
1d600 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 r the maximum nu
1d610 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
1d620 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f in an index.** o
1d630 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 r in an ORDER BY
1d640 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 or GROUP BY cla
1d650 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 use.</dd>.**.**
1d660 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
1d670 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e _EXPR_DEPTH</dt>
1d680 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
1d690 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 mum depth of the
1d6a0 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 parse tree on a
1d6b0 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f ny expression.</
1d6c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
1d6d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f LITE_LIMIT_COMPO
1d6e0 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a UND_SELECT</dt>.
1d6f0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
1d700 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 um number of ter
1d710 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 ms in a compound
1d720 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e SELECT statemen
1d730 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 t.</dd>.**.** <d
1d740 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 t>SQLITE_LIMIT_V
1d750 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c DBE_OP</dt>.** <
1d760 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
1d770 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 umber of instruc
1d780 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 tions in a virtu
1d790 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 al machine progr
1d7a0 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d am.** used to im
1d7b0 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 plement an SQL s
1d7c0 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a tatement.</dd>.*
1d7d0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
1d7e0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 LIMIT_FUNCTION_A
1d7f0 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 RG</dt>.** <dd>T
1d800 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
1d810 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f r of arguments o
1d820 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 n a function.</d
1d830 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
1d840 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 ITE_LIMIT_ATTACH
1d850 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ED</dt>.** <dd>T
1d860 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
1d870 72 20 6f 66 20 61 74 74 61 63 68 65 64 20 64 61 r of attached da
1d880 74 61 62 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a tabases.</dd>.**
1d890 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c .** <dt>SQLITE_L
1d8a0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 IMIT_LIKE_PATTER
1d8b0 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a N_LENGTH</dt>.**
1d8c0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
1d8d0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 length of the p
1d8e0 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 attern argument
1d8f0 74 6f 20 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a to the LIKE or.*
1d900 2a 20 47 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73 * GLOB operators
1d910 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
1d920 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 >SQLITE_LIMIT_VA
1d930 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 RIABLE_NUMBER</d
1d940 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
1d950 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
1d960 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 variables in an
1d970 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 SQL statement th
1d980 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 at can.** be bou
1d990 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c nd.</dd>.** </dl
1d9a0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c >.*/.#define SQL
1d9b0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 ITE_LIMIT_LENGTH
1d9c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1d9d0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
1d9e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c LITE_LIMIT_SQL_L
1d9f0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 ENGTH
1da00 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
1da10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 QLITE_LIMIT_COLU
1da20 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 MN
1da30 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
1da40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 SQLITE_LIMIT_EXP
1da50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 R_DEPTH
1da60 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
1da70 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f SQLITE_LIMIT_CO
1da80 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 MPOUND_SELECT
1da90 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 4.#defin
1daa0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 e SQLITE_LIMIT_V
1dab0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 DBE_OP
1dac0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 5.#defi
1dad0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
1dae0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 FUNCTION_ARG
1daf0 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 6.#def
1db00 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
1db10 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 _ATTACHED
1db20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 7.#de
1db30 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
1db40 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c T_LIKE_PATTERN_L
1db50 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 ENGTH 8.#d
1db60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
1db70 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
1db80 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a ER 9..
1db90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1dba0 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c Compiling An SQL
1dbb0 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 Statement {H130
1dbc0 31 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 10} <S10000>.**
1dbd0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 KEYWORDS: {SQL s
1dbe0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 tatement compile
1dbf0 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 r}.**.** To exec
1dc00 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 ute an SQL query
1dc10 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 , it must first
1dc20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f be compiled into
1dc30 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 a byte-code.**
1dc40 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e program using on
1dc50 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 e of these routi
1dc60 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 nes..**.** The f
1dc70 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 irst argument, "
1dc80 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 db", is a [datab
1dc90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
1dca0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a obtained from a.
1dcb0 2a 2a 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f ** prior call to
1dcc0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
1dcd0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
1dce0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 _v2()] or [sqlit
1dcf0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a e3_open16()]..**
1dd00 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 .** The second a
1dd10 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c rgument, "zSql",
1dd20 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e is the statemen
1dd30 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 t to be compiled
1dd40 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 , encoded.** as
1dd50 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
1dd60 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c UTF-16. The sql
1dd70 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 ite3_prepare() a
1dd80 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
1dd90 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 re_v2().** inter
1dda0 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c faces use UTF-8,
1ddb0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
1ddc0 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c pare16() and sql
1ddd0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
1dde0 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 2().** use UTF-1
1ddf0 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6..**.** If the
1de00 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 nByte argument i
1de10 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f s less than zero
1de20 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 , then zSql is r
1de30 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a ead up to the.**
1de40 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d first zero term
1de50 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 inator. If nByte
1de60 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
1de70 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 , then it is the
1de80 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 maximum.** numb
1de90 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 er of bytes rea
1dea0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 d from zSql. Wh
1deb0 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d en nByte is non-
1dec0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a negative, the.**
1ded0 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 zSql string end
1dee0 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 s at either the
1def0 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 first '\000' or
1df00 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 '\u0000' charact
1df10 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 er or.** the nBy
1df20 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 te-th byte, whic
1df30 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 hever comes firs
1df40 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 t. If the caller
1df50 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 knows.** that t
1df60 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 he supplied stri
1df70 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e ng is nul-termin
1df80 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 ated, then there
1df90 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 is a small.** p
1dfa0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e erformance advan
1dfb0 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 tage to be gaine
1dfc0 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 d by passing an
1dfd0 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 nByte parameter
1dfe0 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c that.** is equal
1dff0 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f to the number o
1e000 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 f bytes in the i
1e010 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 nput string <i>i
1e020 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 ncluding</i>.**
1e030 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 the nul-terminat
1e040 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 or bytes..**.**
1e050 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 *pzTail is made
1e060 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 to point to the
1e070 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20 first byte past
1e080 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a the end of the.*
1e090 2a 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 * first SQL stat
1e0a0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 ement in zSql.
1e0b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f These routines o
1e0c0 6e 6c 79 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 nly compile the
1e0d0 66 69 72 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65 first.** stateme
1e0e0 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a nt in zSql, so *
1e0f0 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 pzTail is left p
1e100 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20 ointing to what
1e110 72 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d remains.** uncom
1e120 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 piled..**.** *pp
1e130 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 Stmt is left poi
1e140 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 nting to a compi
1e150 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 led [prepared st
1e160 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 atement] that ca
1e170 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 n be.** executed
1e180 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
1e190 73 74 65 70 28 29 5d 2e 20 20 49 66 20 74 68 65 step()]. If the
1e1a0 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 re is an error,
1e1b0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a *ppStmt is set.*
1e1c0 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 * to NULL. If t
1e1d0 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f he input text co
1e1e0 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 ntains no SQL (i
1e1f0 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 f the input is a
1e200 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e n empty.** strin
1e210 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 g or a comment)
1e220 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 then *ppStmt is
1e230 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 set to NULL..**
1e240 7b 41 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c {A13018} The cal
1e250 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 ling procedure i
1e260 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
1e270 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 r deleting the c
1e280 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 ompiled.** SQL s
1e290 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b tatement using [
1e2a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
1e2b0 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 ()] after it has
1e2c0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 finished with i
1e2d0 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 t..**.** On succ
1e2e0 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d ess, [SQLITE_OK]
1e2f0 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 is returned, ot
1e300 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f herwise an [erro
1e310 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
1e320 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ned..**.** The s
1e330 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1e340 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 2() and sqlite3_
1e350 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 prepare16_v2() i
1e360 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a nterfaces are.**
1e370 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 recommended for
1e380 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d all new program
1e390 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 s. The two older
1e3a0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
1e3b0 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 retained.** for
1e3c0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
1e3d0 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 ibility, but the
1e3e0 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 ir use is discou
1e3f0 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 raged..** In the
1e400 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 "v2" interfaces
1e410 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 , the prepared s
1e420 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 tatement.** that
1e430 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 is returned (th
1e440 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d e [sqlite3_stmt]
1e450 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e object) contain
1e460 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a s a copy of the.
1e470 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 ** original SQL
1e480 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 text. This cause
1e490 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 s the [sqlite3_s
1e4a0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tep()] interface
1e4b0 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 to.** behave a
1e4c0 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 differently in t
1e4d0 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c wo ways:.**.** <
1e4e0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 ol>.** <li>.** I
1e4f0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 f the database s
1e500 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 chema changes, i
1e510 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e nstead of return
1e520 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 ing [SQLITE_SCHE
1e530 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 MA] as it.** alw
1e540 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 ays used to do,
1e550 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1e560 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 will automatica
1e570 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 lly recompile th
1e580 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 e SQL.** stateme
1e590 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 nt and try to ru
1e5a0 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 n it again. If
1e5b0 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 the schema has c
1e5c0 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 hanged in.** a w
1e5d0 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 ay that makes th
1e5e0 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c e statement no l
1e5f0 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 onger valid, [sq
1e600 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
1e610 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 ll still.** retu
1e620 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d rn [SQLITE_SCHEM
1e630 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 A]. But unlike
1e640 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 the legacy behav
1e650 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 ior, [SQLITE_SCH
1e660 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 EMA] is.** now a
1e670 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 fatal error. C
1e680 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
1e690 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 prepare_v2()] ag
1e6a0 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b ain will not mak
1e6b0 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 e the.** error g
1e6c0 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 o away. Note: u
1e6d0 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d se [sqlite3_errm
1e6e0 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 sg()] to find th
1e6f0 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 e text.** of the
1e700 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 parsing error t
1e710 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 hat results in a
1e720 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 n [SQLITE_SCHEMA
1e730 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c ] return..** </l
1e740 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a i>.**.** <li>.**
1e750 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f When an error o
1e760 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f ccurs, [sqlite3_
1e770 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 step()] will ret
1e780 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 urn one of the d
1e790 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f etailed.** [erro
1e7a0 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 r codes] or [ext
1e7b0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
1e7c0 73 5d 2e 20 20 54 68 65 20 6c 65 67 61 63 79 20 s]. The legacy
1e7d0 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 behavior was tha
1e7e0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 t.** [sqlite3_st
1e7f0 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 ep()] would only
1e800 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 return a generi
1e810 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d c [SQLITE_ERROR]
1e820 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 result code.**
1e830 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 and you would ha
1e840 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 ve to make a sec
1e850 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ond call to [sql
1e860 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e ite3_reset()] in
1e870 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e order.** to fin
1e880 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 d the underlying
1e890 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 cause of the pr
1e8a0 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 oblem. With the
1e8b0 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 "v2" prepare.**
1e8c0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 interfaces, the
1e8d0 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f underlying reaso
1e8e0 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 n for the error
1e8f0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 is returned imme
1e900 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 diately..** </li
1e910 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a >.** </ol>.**.**
1e920 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
1e930 2a 2a 20 7b 48 31 33 30 31 31 7d 20 54 68 65 20 ** {H13011} The
1e940 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1e950 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 (db,zSql,...)] a
1e960 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b nd.** [
1e970 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1e980 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d v2(db,zSql,...)]
1e990 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 interfaces inte
1e9a0 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 rpret the.**
1e9b0 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 text in th
1e9c0 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 eir zSql paramet
1e9d0 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a er as UTF-8..**.
1e9e0 2a 2a 20 7b 48 31 33 30 31 32 7d 20 54 68 65 20 ** {H13012} The
1e9f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1ea00 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 16(db,zSql,...)]
1ea10 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
1ea20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1ea30 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e e16_v2(db,zSql,.
1ea40 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 ..)] interfaces
1ea50 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a interpret the.**
1ea60 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20 69 text i
1ea70 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72 n their zSql par
1ea80 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 31 36 ameter as UTF-16
1ea90 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 in the native b
1eaa0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a yte order..**.**
1eab0 20 7b 48 31 33 30 31 33 7d 20 49 66 20 74 68 65 {H13013} If the
1eac0 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 nByte argument
1ead0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 to [sqlite3_prep
1eae0 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e are_v2(db,zSql,n
1eaf0 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 Byte,...)].**
1eb00 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 and its v
1eb10 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73 73 20 ariants is less
1eb20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 20 53 than zero, the S
1eb30 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20 20 20 QL text is.**
1eb40 20 20 20 20 20 20 20 72 65 61 64 20 66 72 6f 6d read from
1eb50 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 zSql is read up
1eb60 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 to the first ze
1eb70 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a ro terminator..*
1eb80 2a 0a 2a 2a 20 7b 48 31 33 30 31 34 7d 20 49 66 *.** {H13014} If
1eb90 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d the nByte argum
1eba0 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ent to [sqlite3_
1ebb0 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 prepare_v2(db,zS
1ebc0 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a ql,nByte,...)].*
1ebd0 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 69 * and i
1ebe0 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20 6e ts variants is n
1ebf0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 on-negative, the
1ec00 6e 20 61 74 20 6d 6f 73 74 20 6e 42 79 74 65 73 n at most nBytes
1ec10 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 bytes of.**
1ec20 20 20 20 20 20 20 53 51 4c 20 74 65 78 74 20 69 SQL text i
1ec30 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c s read from zSql
1ec40 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 35 7d ..**.** {H13015}
1ec50 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 In [sqlite3_pre
1ec60 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c pare_v2(db,zSql,
1ec70 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64 N,P,pzTail)] and
1ec80 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a its variants.**
1ec90 20 20 20 20 20 20 20 20 20 20 69 66 20 74 68 65 if the
1eca0 20 7a 53 71 6c 20 69 6e 70 75 74 20 74 65 78 74 zSql input text
1ecb0 20 63 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74 contains more t
1ecc0 68 61 6e 20 6f 6e 65 20 53 51 4c 20 73 74 61 74 han one SQL stat
1ecd0 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 ement.**
1ece0 20 20 61 6e 64 20 70 7a 54 61 69 6c 20 69 73 20 and pzTail is
1ecf0 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a not NULL, then *
1ed00 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 pzTail is made t
1ed10 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a o point to the.*
1ed20 2a 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74 * first
1ed30 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65 byte past the e
1ed40 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 nd of the first
1ed50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e SQL statement in
1ed60 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20 zSql..**
1ed70 20 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f <todo>What do
1ed80 65 73 20 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74 es *pzTail point
1ed90 20 74 6f 20 69 66 20 74 68 65 72 65 20 69 73 20 to if there is
1eda0 6f 6e 65 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f one statement?</
1edb0 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 todo>.**.** {H13
1edc0 30 31 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 016} A successfu
1edd0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
1ede0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 e3_prepare_v2(db
1edf0 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e ,zSql,N,ppStmt,.
1ee00 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ..)].**
1ee10 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 or one of its v
1ee20 61 72 69 61 6e 74 73 20 77 72 69 74 65 73 20 69 ariants writes i
1ee30 6e 74 6f 20 2a 70 70 53 74 6d 74 20 61 20 70 6f nto *ppStmt a po
1ee40 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a inter to a new.*
1ee50 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 * [prep
1ee60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
1ee70 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 or a pointer to
1ee80 4e 55 4c 4c 20 69 66 20 7a 53 71 6c 20 63 6f 6e NULL if zSql con
1ee90 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 tains.**
1eea0 20 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 nothing other
1eeb0 74 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 20 than whitespace
1eec0 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a or comments..**.
1eed0 2a 2a 20 7b 48 31 33 30 31 39 7d 20 54 68 65 20 ** {H13019} The
1eee0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1eef0 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 _v2()] interface
1ef00 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 and its variant
1ef10 73 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 s return.**
1ef20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d [SQLITE_OK]
1ef30 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 or an appropria
1ef40 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 te [error code]
1ef50 75 70 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a upon failure..**
1ef60 0a 2a 2a 20 7b 48 31 33 30 32 31 7d 20 42 65 66 .** {H13021} Bef
1ef70 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ore [sqlite3_pre
1ef80 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 pare(db,zSql,nBy
1ef90 74 65 2c 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c te,ppStmt,pzTail
1efa0 29 5d 20 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20 )] or its.**
1efb0 20 20 20 20 20 20 76 61 72 69 61 6e 74 73 20 72 variants r
1efc0 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 20 eturns an error
1efd0 28 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 (any value other
1efe0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b than [SQLITE_OK
1eff0 5d 29 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ]),.**
1f000 74 68 65 79 20 66 69 72 73 74 20 73 65 74 20 2a they first set *
1f010 70 70 53 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a ppStmt to NULL..
1f020 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 */.int sqlite3_p
1f030 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 repare(. sqlite
1f040 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
1f050 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
1f060 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
1f070 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 char *zSql,
1f080 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
1f090 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 nt, UTF-8 encode
1f0a0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
1f0b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
1f0c0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
1f0d0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
1f0e0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
1f0f0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
1f100 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
1f110 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
1f120 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 nst char **pzTai
1f130 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
1f140 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
1f150 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
1f160 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 */.);.int sqlite
1f170 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 3_prepare_v2(.
1f180 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
1f190 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
1f1a0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
1f1b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c const char *zSql
1f1c0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 , /* SQL s
1f1d0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 tatement, UTF-8
1f1e0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 encoded */. int
1f1f0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 nByte,
1f200 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
1f210 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 length of zSql i
1f220 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 n bytes. */. sq
1f230 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 lite3_stmt **ppS
1f240 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 tmt, /* OUT: St
1f250 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a atement handle *
1f260 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
1f270 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f *pzTail /* O
1f280 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 UT: Pointer to u
1f290 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 nused portion of
1f2a0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 zSql */.);.int
1f2b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
1f2c0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 6(. sqlite3 *db
1f2d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
1f2e0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
1f2f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
1f300 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
1f310 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
1f320 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f TF-16 encoded */
1f330 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
1f340 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
1f350 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
1f360 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
1f370 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
1f380 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
1f390 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
1f3a0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
1f3b0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 void **pzTail
1f3c0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
1f3d0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
1f3e0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
1f3f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 ;.int sqlite3_pr
1f400 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 epare16_v2(. sq
1f410 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
1f420 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
1f430 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
1f440 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 nst void *zSql,
1f450 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
1f460 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 tement, UTF-16 e
1f470 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
1f480 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
1f490 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
1f4a0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
1f4b0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
1f4c0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
1f4d0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
1f4e0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
1f4f0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a . const void **
1f500 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
1f510 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
1f520 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
1f530 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a zSql */.);../*.*
1f540 2a 20 43 41 50 49 52 45 46 3a 20 52 65 74 72 69 * CAPIREF: Retri
1f550 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 eving Statement
1f560 53 51 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48 31 SQL {H13100} <H1
1f570 33 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 3000>.**.** This
1f580 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 interface can b
1f590 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 e used to retrie
1f5a0 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 ve a saved copy
1f5b0 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a of the original.
1f5c0 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 ** SQL text used
1f5d0 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 to create a [pr
1f5e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1f5f0 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d ] if that statem
1f600 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 ent was.** compi
1f610 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 led using either
1f620 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1f630 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 e_v2()] or [sqli
1f640 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
1f650 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ()]..**.** INVAR
1f660 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
1f670 33 31 30 31 7d 20 49 66 20 74 68 65 20 5b 70 72 3101} If the [pr
1f680 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1f690 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 ] passed as the
1f6a0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 argument to.**
1f6b0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
1f6c0 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 _sql()] was comp
1f6d0 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 iled using eithe
1f6e0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
1f6f0 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 re_v2()] or.**
1f700 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
1f710 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
1f720 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f , then [sqlite3_
1f730 73 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a 2a sql()] returns.*
1f740 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 * a poi
1f750 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 nter to a zero-t
1f760 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 erminated string
1f770 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55 54 containing a UT
1f780 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a 2a F-8 rendering.**
1f790 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 of the
1f7a0 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 original SQL st
1f7b0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b atement..**.** {
1f7c0 48 31 33 31 30 32 7d 20 49 66 20 74 68 65 20 5b H13102} If the [
1f7d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1f7e0 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 nt] passed as th
1f7f0 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a e argument to.**
1f800 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
1f810 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f e3_sql()] was co
1f820 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 mpiled using eit
1f830 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 her [sqlite3_pre
1f840 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 pare()] or.**
1f850 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
1f860 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 prepare16()], th
1f870 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 en [sqlite3_sql(
1f880 29 5d 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c )] returns a NUL
1f890 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
1f8a0 20 7b 48 31 33 31 30 33 7d 20 54 68 65 20 73 74 {H13103} The st
1f8b0 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 ring returned by
1f8c0 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 53 29 [sqlite3_sql(S)
1f8d0 5d 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c ] is valid until
1f8e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
1f8f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1f900 6d 65 6e 74 5d 20 53 20 69 73 20 64 65 6c 65 74 ment] S is delet
1f910 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
1f920 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 3_finalize(S)]..
1f930 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
1f940 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 qlite3_sql(sqlit
1f950 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
1f960 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1f970 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 : Dynamically Ty
1f980 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 ped Value Object
1f990 20 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32 30 {H15000} <S2020
1f9a0 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 0>.** KEYWORDS:
1f9b0 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 {protected sqlit
1f9c0 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f e3_value} {unpro
1f9d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
1f9e0 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 alue}.**.** SQLi
1f9f0 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 te uses the sqli
1fa00 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
1fa10 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c to represent al
1fa20 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 l values.** that
1fa30 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 can be stored i
1fa40 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 n a database tab
1fa50 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 le. SQLite uses
1fa60 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a dynamic typing.*
1fa70 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 * for the values
1fa80 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c 75 it stores. Valu
1fa90 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c es stored in sql
1faa0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
1fab0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 ts.** can be int
1fac0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 egers, floating
1fad0 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 point values, st
1fae0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 rings, BLOBs, or
1faf0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 NULL..**.** An
1fb00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
1fb10 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 ject may be eith
1fb20 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f er "protected" o
1fb30 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e r "unprotected".
1fb40 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 .** Some interfa
1fb50 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 ces require a pr
1fb60 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
1fb70 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e value. Other in
1fb80 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c terfaces.** will
1fb90 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 accept either a
1fba0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e protected or an
1fbb0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c unprotected sql
1fbc0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 ite3_value..** E
1fbd0 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 very interface t
1fbe0 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 hat accepts sqli
1fbf0 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 te3_value argume
1fc00 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a nts specifies.**
1fc10 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
1fc20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 it requires a pr
1fc30 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
1fc40 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 value..**.** The
1fc50 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 terms "protecte
1fc60 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 d" and "unprotec
1fc70 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 ted" refer to wh
1fc80 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 ether or not.**
1fc90 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e a mutex is held.
1fca0 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 A internal mut
1fcb0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 ex is held for a
1fcc0 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 protected.** sq
1fcd0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
1fce0 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 ct but no mutex
1fcf0 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 is held for an u
1fd00 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 nprotected.** sq
1fd10 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
1fd20 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 ct. If SQLite i
1fd30 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 s compiled to be
1fd40 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 single-threaded
1fd50 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 .** (with [SQLIT
1fd60 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 E_THREADSAFE=0]
1fd70 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 and with [sqlite
1fd80 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 3_threadsafe()]
1fd90 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 returning 0).**
1fda0 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 or if SQLite is
1fdb0 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 run in one of re
1fdc0 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 duced mutex mode
1fdd0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f s .** [SQLITE_CO
1fde0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
1fdf0 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f D] or [SQLITE_CO
1fe00 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 NFIG_MULTITHREAD
1fe10 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 ].** then there
1fe20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f is no distinctio
1fe30 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 n between protec
1fe40 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 ted and unprotec
1fe50 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 ted.** sqlite3_v
1fe60 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 alue objects and
1fe70 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 they can be use
1fe80 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c d interchangeabl
1fe90 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 y. However,.**
1fea0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 for maximum code
1feb0 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 portability it
1fec0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 is recommended t
1fed0 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 hat applications
1fee0 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 .** still make t
1fef0 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 he distinction b
1ff00 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 etween between p
1ff10 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 rotected and unp
1ff20 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
1ff30 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
1ff40 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 s even when not
1ff50 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 strictly require
1ff60 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c d..**.** The sql
1ff70 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
1ff80 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 ts that are pass
1ff90 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 ed as parameters
1ffa0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 into the.** imp
1ffb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b lementation of [
1ffc0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
1ffd0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
1ffe0 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 s] are protected
1fff0 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 ..** The sqlite3
20000 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 _value object re
20010 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 turned by.** [sq
20020 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
20030 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 ue()] is unprote
20040 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 cted..** Unprote
20050 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
20060 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f ue objects may o
20070 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 nly be used with
20080 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
20090 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 ult_value()] and
200a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 [sqlite3_bind_v
200b0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 alue()]..** The
200c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
200d0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 lob | sqlite3_va
200e0 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 lue_type()] fami
200f0 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 ly of.** interfa
20100 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 ces require prot
20110 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
20120 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a lue objects..*/.
20130 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d typedef struct M
20140 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 em sqlite3_value
20150 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
20160 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 F: SQL Function
20170 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b Context Object {
20180 48 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30 3e H16001} <S20200>
20190 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 .**.** The conte
201a0 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 xt in which an S
201b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 QL function exec
201c0 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 utes is stored i
201d0 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f n an.** sqlite3_
201e0 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 context object.
201f0 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e A pointer to an
20200 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
20210 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c object.** is al
20220 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d ways first param
20230 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 eter to [applica
20240 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
20250 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 functions]..**
20260 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d The application-
20270 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
20280 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
20290 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 ion will pass th
202a0 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 is.** pointer th
202b0 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 rough into calls
202c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
202d0 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 ult_int | sqlite
202e0 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 3_result()],.**
202f0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 [sqlite3_aggrega
20300 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b te_context()], [
20310 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
20320 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 a()],.** [sqlite
20330 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 3_context_db_han
20340 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 dle()], [sqlite3
20350 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c _get_auxdata()],
20360 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 .** and/or [sqli
20370 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
20380 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 )]..*/.typedef s
20390 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f truct sqlite3_co
203a0 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f ntext sqlite3_co
203b0 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ntext;../*.** CA
203c0 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 PI3REF: Binding
203d0 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 Values To Prepar
203e0 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b 48 ed Statements {H
203f0 31 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 13500} <S70300>.
20400 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f ** KEYWORDS: {ho
20410 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 st parameter} {h
20420 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 ost parameters}
20430 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 {host parameter
20440 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 name}.** KEYWORD
20450 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 S: {SQL paramete
20460 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 r} {SQL paramete
20470 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 rs} {parameter b
20480 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e inding}.**.** In
20490 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 the SQL strings
204a0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 input to [sqlit
204b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
204c0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 and its variant
204d0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d s,.** literals m
204e0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 ay be replaced b
204f0 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e y a parameter in
20500 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 66 6f one of these fo
20510 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a rms:.**.** <ul>.
20520 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c ** <li> ?.** <l
20530 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e i> ?NNN.** <li>
20540 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 :VVV.** <li>
20550 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 @VVV.** <li> $V
20560 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a VV.** </ul>.**.*
20570 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74 * In the paramet
20580 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 er forms shown a
20590 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 bove NNN is an i
205a0 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a nteger literal,.
205b0 2a 2a 20 61 6e 64 20 56 56 56 20 69 73 20 61 6e ** and VVV is an
205c0 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 alpha-numeric p
205d0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20 54 arameter name. T
205e0 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 he values of the
205f0 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 se.** parameters
20600 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 (also called "h
20610 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 ost parameter na
20620 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 mes" or "SQL par
20630 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e ameters").** can
20640 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 be set using th
20650 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
20660 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 () routines defi
20670 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 ned here..**.**
20680 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
20690 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 nt to the sqlite
206a0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
206b0 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a nes is always.**
206c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
206d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d e [sqlite3_stmt]
206e0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 object returned
206f0 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 from.** [sqlite
20700 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
20710 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e or its variants.
20720 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e .**.** The secon
20730 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
20740 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 e index of the S
20750 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 QL parameter to
20760 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 6c be set..** The l
20770 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 eftmost SQL para
20780 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 meter has an ind
20790 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 ex of 1. When t
207a0 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a he same named.**
207b0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 SQL parameter i
207c0 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e s used more than
207d0 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e once, second an
207e0 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 d subsequent.**
207f0 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 occurrences have
20800 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 the same index
20810 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 as the first occ
20820 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 urrence..** The
20830 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 index for named
20840 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 parameters can b
20850 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e e looked up usin
20860 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 g the.** [sqlite
20870 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
20880 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 _index()] API if
20890 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 desired. The i
208a0 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e ndex.** for "?NN
208b0 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 N" parameters is
208c0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e the value of NN
208d0 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 N..** The NNN va
208e0 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 lue must be betw
208f0 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 een 1 and the [s
20900 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a qlite3_limit()].
20910 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 ** parameter [SQ
20920 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 LITE_LIMIT_VARIA
20930 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 BLE_NUMBER] (def
20940 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 ault value: 999)
20950 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 ..**.** The thir
20960 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
20970 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 e value to bind
20980 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 to the parameter
20990 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 ..**.** In those
209a0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 routines that h
209b0 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 ave a fourth arg
209c0 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 ument, its value
209d0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 is the.** numbe
209e0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
209f0 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f e parameter. To
20a00 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 be clear: the v
20a10 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e alue is the.** n
20a20 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 umber of <u>byte
20a30 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c s</u> in the val
20a40 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 ue, not the numb
20a50 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
20a60 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 ..** If the four
20a70 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
20a80 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 negative, the le
20a90 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 ngth of the stri
20aa0 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d ng is.** the num
20ab0 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 ber of bytes up
20ac0 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 to the first zer
20ad0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a o terminator..**
20ae0 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 72 .** The fifth ar
20af0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
20b00 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 3_bind_blob(), s
20b10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
20b20 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 (), and.** sqlit
20b30 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 e3_bind_text16()
20b40 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 is a destructor
20b50 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 used to dispose
20b60 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a of the BLOB or.
20b70 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 ** string after
20b80 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 SQLite has finis
20b90 68 65 64 20 77 69 74 68 20 69 74 2e 20 49 66 20 hed with it. If
20ba0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 the fifth argume
20bb0 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 nt is.** the spe
20bc0 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 cial value [SQLI
20bd0 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e TE_STATIC], then
20be0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 SQLite assumes
20bf0 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f that the.** info
20c00 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 rmation is in st
20c10 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 atic, unmanaged
20c20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e space and does n
20c30 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 ot need to be fr
20c40 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 eed..** If the f
20c50 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 ifth argument ha
20c60 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c s the value [SQL
20c70 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 ITE_TRANSIENT],
20c80 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d then.** SQLite m
20c90 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 akes its own pri
20ca0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 vate copy of the
20cb0 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c data immediatel
20cc0 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 y, before.** the
20cd0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
20ce0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
20cf0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c s..**.** The sql
20d00 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c ite3_bind_zerobl
20d10 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e ob() routine bin
20d20 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e ds a BLOB of len
20d30 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 gth N that.** is
20d40 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 filled with zer
20d50 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 oes. A zeroblob
20d60 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d uses a fixed am
20d70 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a ount of memory.*
20d80 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 * (just an integ
20d90 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 er to hold its s
20da0 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 ize) while it is
20db0 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 being processed
20dc0 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 ..** Zeroblobs a
20dd0 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 re intended to s
20de0 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c erve as placehol
20df0 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 ders for BLOBs w
20e00 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 hose.** content
20e10 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e is later written
20e20 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
20e30 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 e3_blob_open | i
20e40 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 ncremental BLOB
20e50 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a I/O] routines..*
20e60 2a 20 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c * A negative val
20e70 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 ue for the zerob
20e80 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 lob results in a
20e90 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f zero-length BLO
20ea0 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c B..**.** The sql
20eb0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f ite3_bind_*() ro
20ec0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 utines must be c
20ed0 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b alled after.** [
20ee0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
20ef0 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 v2()] (and its v
20f00 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c ariants) or [sql
20f10 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e ite3_reset()] an
20f20 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c d.** before [sql
20f30 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a ite3_step()]..**
20f40 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f Bindings are no
20f50 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 t cleared by the
20f60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
20f70 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 )] routine..** U
20f80 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 nbound parameter
20f90 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 s are interprete
20fa0 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a d as NULL..**.**
20fb0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
20fc0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f return [SQLITE_O
20fd0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 K] on success or
20fe0 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 an error code i
20ff0 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f f.** anything go
21000 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 es wrong. [SQLI
21010 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 TE_RANGE] is ret
21020 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 urned if the par
21030 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 ameter.** index
21040 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e is out of range.
21050 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d [SQLITE_NOMEM]
21060 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 is returned if
21070 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a malloc() fails..
21080 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 ** [SQLITE_MISUS
21090 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 E] might be retu
210a0 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 6f rned if these ro
210b0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 utines are calle
210c0 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 d on a.** virtua
210d0 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 l machine that i
210e0 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 s the wrong stat
210f0 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 e or which has a
21100 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 lready been fina
21110 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 lized..** Detect
21120 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73 ion of misuse is
21130 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 unreliable. Ap
21140 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c plications shoul
21150 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 d not depend.**
21160 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 on SQLITE_MISUSE
21170 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 returns. SQLIT
21180 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65 E_MISUSE is inte
21190 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 nded to indicate
211a0 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 a.** a logic er
211b0 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69 ror in the appli
211c0 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 cation. Future
211d0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
211e0 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 te might.** pani
211f0 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 65 c rather than re
21200 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 turn SQLITE_MISU
21210 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c SE..**.** See al
21220 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
21230 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
21240 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 t()],.** [sqlite
21250 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
21260 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 _name()], and [s
21270 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
21280 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
21290 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
212a0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 36 7d :.**.** {H13506}
212b0 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d The [SQL statem
212c0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72 65 ent compiler] re
212d0 63 6f 67 6e 69 7a 65 73 20 74 6f 6b 65 6e 73 20 cognizes tokens
212e0 6f 66 20 74 68 65 20 66 6f 72 6d 73 0a 2a 2a 20 of the forms.**
212f0 20 20 20 20 20 20 20 20 20 22 3f 22 2c 20 22 3f "?", "?
21300 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c 20 22 3a NNN", "$VVV", ":
21310 56 56 56 22 2c 20 61 6e 64 20 22 40 56 56 56 22 VVV", and "@VVV"
21320 20 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74 65 as SQL paramete
21330 72 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 rs,.**
21340 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 79 where NNN is any
21350 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 sequence of one
21360 20 6f 72 20 6d 6f 72 65 20 64 69 67 69 74 73 0a or more digits.
21370 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 ** and
21380 77 68 65 72 65 20 56 56 56 20 69 73 20 61 6e 79 where VVV is any
21390 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 sequence of one
213a0 20 6f 72 20 6d 6f 72 65 20 61 6c 70 68 61 6e 75 or more alphanu
213b0 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 meric.**
213c0 20 20 63 68 61 72 61 63 74 65 72 73 20 6f 72 20 characters or
213d0 22 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 "::" optionally
213e0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20 73 74 followed by a st
213f0 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 0a ring containing.
21400 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20 73 ** no s
21410 70 61 63 65 73 20 61 6e 64 20 63 6f 6e 74 61 69 paces and contai
21420 6e 65 64 20 77 69 74 68 69 6e 20 70 61 72 65 6e ned within paren
21430 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 theses..**.** {H
21440 31 33 35 30 39 7d 20 54 68 65 20 69 6e 69 74 69 13509} The initi
21450 61 6c 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 al value of an S
21460 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 QL parameter is
21470 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 NULL..**.** {H13
21480 35 31 32 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 512} The index o
21490 66 20 61 6e 20 22 3f 22 20 53 51 4c 20 70 61 72 f an "?" SQL par
214a0 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6c 61 ameter is one la
214b0 72 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a rger than the.**
214c0 20 20 20 20 20 20 20 20 20 20 6c 61 72 67 65 73 larges
214d0 74 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 t index of SQL p
214e0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
214f0 6c 65 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a left, or 1 if.**
21500 20 20 20 20 20 20 20 20 20 20 74 68 65 20 22 3f the "?
21510 22 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 " is the leftmos
21520 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 2e t SQL parameter.
21530 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 35 7d 20 .**.** {H13515}
21540 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 The index of an
21550 22 3f 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d "?NNN" SQL param
21560 65 74 65 72 20 69 73 20 74 68 65 20 69 6e 74 65 eter is the inte
21570 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b ger NNN..**.** {
21580 48 31 33 35 31 38 7d 20 54 68 65 20 69 6e 64 65 H13518} The inde
21590 78 20 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c 20 x of an ":VVV",
215a0 22 24 56 56 56 22 2c 20 6f 72 20 22 40 56 56 56 "$VVV", or "@VVV
215b0 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 " SQL parameter
215c0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 is.** t
215d0 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 69 he same as the i
215e0 6e 64 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74 ndex of leftmost
215f0 20 6f 63 63 75 72 72 65 6e 63 65 73 20 6f 66 20 occurrences of
21600 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 the same.**
21610 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2c 20 parameter,
21620 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61 6e or one more than
21630 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 the largest ind
21640 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 ex over all.**
21650 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 paramete
21660 72 73 20 74 6f 20 74 68 65 20 6c 65 66 74 20 69 rs to the left i
21670 66 20 74 68 69 73 20 69 73 20 74 68 65 20 66 69 f this is the fi
21680 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 0a 2a rst occurrence.*
21690 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 * of th
216a0 69 73 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 is parameter, or
216b0 20 31 20 69 66 20 74 68 69 73 20 69 73 20 74 68 1 if this is th
216c0 65 20 6c 65 66 74 6d 6f 73 74 20 70 61 72 61 6d e leftmost param
216d0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 eter..**.** {H13
216e0 35 32 31 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 521} The [SQL st
216f0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 atement compiler
21700 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 ] fails with an
21710 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 0a 2a [SQLITE_RANGE].*
21720 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 * error
21730 20 69 66 20 74 68 65 20 69 6e 64 65 78 20 6f 66 if the index of
21740 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 an SQL paramete
21750 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 r is less than 1
21760 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
21770 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 greater than the
21780 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 53 51 compile-time SQ
21790 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c LITE_MAX_VARIABL
217a0 45 5f 4e 55 4d 42 45 52 0a 2a 2a 20 20 20 20 20 E_NUMBER.**
217b0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2e 0a parameter..
217c0 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 34 7d 20 43 **.** {H13524} C
217d0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
217e0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c _bind_text | sql
217f0 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c ite3_bind(S,N,V,
21800 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 ...)].**
21810 20 20 61 73 73 6f 63 69 61 74 65 20 74 68 65 20 associate the
21820 76 61 6c 75 65 20 56 20 77 69 74 68 20 61 6c 6c value V with all
21830 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 SQL parameters
21840 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 having an.**
21850 20 20 20 20 20 20 69 6e 64 65 78 20 6f 66 20 4e index of N
21860 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 in the [prepare
21870 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a d statement] S..
21880 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 37 7d 20 43 **.** {H13527} C
21890 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
218a0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c _bind_text | sql
218b0 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e ite3_bind(S,N,..
218c0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 .)].**
218d0 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 63 override prior c
218e0 61 6c 6c 73 20 77 69 74 68 20 74 68 65 20 73 61 alls with the sa
218f0 6d 65 20 76 61 6c 75 65 73 20 6f 66 20 53 20 61 me values of S a
21900 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 nd N..**.** {H13
21910 35 33 30 7d 20 42 69 6e 64 69 6e 67 73 20 65 73 530} Bindings es
21920 74 61 62 6c 69 73 68 65 64 20 62 79 20 5b 73 71 tablished by [sq
21930 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 lite3_bind_text
21940 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 | sqlite3_bind(S
21950 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 ,...)].**
21960 20 20 20 70 65 72 73 69 73 74 20 61 63 72 6f 73 persist acros
21970 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 s calls to [sqli
21980 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a te3_reset(S)]..*
21990 2a 0a 2a 2a 20 7b 48 31 33 35 33 33 7d 20 49 6e *.** {H13533} In
219a0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
219b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e e3_bind_blob(S,N
219c0 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 ,V,L,D)],.**
219d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 [sqlite3_b
219e0 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c ind_text(S,N,V,L
219f0 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 ,D)], or.**
21a00 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 [sqlite3_bi
21a10 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c nd_text16(S,N,V,
21a20 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e L,D)] SQLite bin
21a30 64 73 20 74 68 65 20 66 69 72 73 74 20 4c 0a 2a ds the first L.*
21a40 2a 20 20 20 20 20 20 20 20 20 20 62 79 74 65 73 * bytes
21a50 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 of the BLOB or
21a60 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 string pointed t
21a70 6f 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a o by V, when L.*
21a80 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f * is no
21a90 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a n-negative..**.*
21aa0 2a 20 7b 48 31 33 35 33 36 7d 20 49 6e 20 63 61 * {H13536} In ca
21ab0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
21ac0 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c bind_text(S,N,V,
21ad0 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 L,D)] or.**
21ae0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 [sqlite3_bi
21af0 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c nd_text16(S,N,V,
21b00 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e L,D)] SQLite bin
21b10 64 73 20 63 68 61 72 61 63 74 65 72 73 0a 2a 2a ds characters.**
21b20 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 56 from V
21b30 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 through the fir
21b40 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 st zero characte
21b50 72 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 r when L is nega
21b60 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 tive..**.** {H13
21b70 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 539} In calls to
21b80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
21b90 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c lob(S,N,V,L,D)],
21ba0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
21bb0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 lite3_bind_text(
21bc0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a S,N,V,L,D)], or.
21bd0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
21be0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 ite3_bind_text16
21bf0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 (S,N,V,L,D)] whe
21c00 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63 69 n D is the speci
21c10 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 al.** c
21c20 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f onstant [SQLITE_
21c30 53 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 STATIC], SQLite
21c40 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 assumes that the
21c50 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20 value V.**
21c60 20 20 20 20 20 69 73 20 68 65 6c 64 20 69 6e 20 is held in
21c70 73 74 61 74 69 63 20 75 6e 6d 61 6e 61 67 65 64 static unmanaged
21c80 20 73 70 61 63 65 20 74 68 61 74 20 77 69 6c 6c space that will
21c90 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20 not change.**
21ca0 20 20 20 20 20 20 20 20 64 75 72 69 6e 67 20 74 during t
21cb0 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 he lifetime of t
21cc0 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a he binding..**.*
21cd0 2a 20 7b 48 31 33 35 34 32 7d 20 49 6e 20 63 61 * {H13542} In ca
21ce0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
21cf0 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c bind_blob(S,N,V,
21d00 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 L,D)],.**
21d10 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 [sqlite3_bind
21d20 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 _text(S,N,V,L,D)
21d30 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 ], or.**
21d40 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f [sqlite3_bind_
21d50 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 text16(S,N,V,L,D
21d60 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65 )] when D is the
21d70 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 special.**
21d80 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 constant [S
21d90 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d QLITE_TRANSIENT]
21da0 2c 20 74 68 65 20 72 6f 75 74 69 6e 65 20 6d 61 , the routine ma
21db0 6b 65 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 kes a.**
21dc0 20 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f private copy o
21dd0 66 20 74 68 65 20 76 61 6c 75 65 20 56 20 62 65 f the value V be
21de0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e fore it returns.
21df0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 35 7d 20 .**.** {H13545}
21e00 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c In calls to [sql
21e10 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 ite3_bind_blob(S
21e20 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 ,N,V,L,D)],.**
21e30 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
21e40 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 _bind_text(S,N,V
21e50 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 ,L,D)], or.**
21e60 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
21e70 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c bind_text16(S,N,
21e80 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 V,L,D)] when D i
21e90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a s a pointer to.*
21ea0 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 75 6e * a fun
21eb0 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e ction, SQLite in
21ec0 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63 74 vokes that funct
21ed0 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20 74 ion to destroy t
21ee0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 he.** v
21ef0 61 6c 75 65 20 56 20 61 66 74 65 72 20 69 74 20 alue V after it
21f00 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 has finished usi
21f10 6e 67 20 74 68 65 20 76 61 6c 75 65 20 56 2e 0a ng the value V..
21f20 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 38 7d 20 49 **.** {H13548} I
21f30 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 n calls to [sqli
21f40 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f te3_bind_zeroblo
21f50 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 b(S,N,V,L)] the
21f60 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 value bound.**
21f70 20 20 20 20 20 20 20 20 69 73 20 61 20 42 4c 4f is a BLO
21f80 42 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f 72 B of L bytes, or
21f90 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 a zero-length B
21fa0 4c 4f 42 20 69 66 20 4c 20 69 73 20 6e 65 67 61 LOB if L is nega
21fb0 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 tive..**.** {H13
21fc0 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 551} In calls to
21fd0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 [sqlite3_bind_v
21fe0 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65 alue(S,N,V)] the
21ff0 20 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a V argument may.
22000 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 20 65 ** be e
22010 69 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63 74 ither a [protect
22020 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
22030 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a ] object or an.*
22040 2a 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70 72 * [unpr
22050 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
22060 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a value] object..*
22070 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 /.int sqlite3_bi
22080 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f nd_blob(sqlite3_
22090 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
220a0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 t void*, int n,
220b0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
220c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
220d0 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 d_double(sqlite3
220e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 _stmt*, int, dou
220f0 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ble);.int sqlite
22100 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 3_bind_int(sqlit
22110 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 e3_stmt*, int, i
22120 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 nt);.int sqlite3
22130 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 _bind_int64(sqli
22140 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
22150 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
22160 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
22170 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 _null(sqlite3_st
22180 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 mt*, int);.int s
22190 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
221a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
221b0 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a int, const char*
221c0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 , int n, void(*)
221d0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 (void*));.int sq
221e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
221f0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
22200 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 int, const void
22210 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 *, int, void(*)(
22220 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c void*));.int sql
22230 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
22240 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
22250 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 nt, const sqlite
22260 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 3_value*);.int s
22270 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f qlite3_bind_zero
22280 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d blob(sqlite3_stm
22290 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b t*, int, int n);
222a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
222b0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 : Number Of SQL
222c0 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31 33 36 Parameters {H136
222d0 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 00} <S70300>.**.
222e0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
222f0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 can be used to f
22300 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ind the number o
22310 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 f [SQL parameter
22320 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 s].** in a [prep
22330 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
22340 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 SQL parameters
22350 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 are tokens of t
22360 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 he.** form "?",
22370 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 "?NNN", ":AAA",
22380 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 "$AAA", or "@AAA
22390 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a " that serve as.
223a0 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 ** placeholders
223b0 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 for values that
223c0 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e are [sqlite3_bin
223d0 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a d_blob | bound].
223e0 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 ** to the parame
223f0 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 ters at a later
22400 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 time..**.** This
22410 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c routine actuall
22420 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e y returns the in
22430 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 dex of the large
22440 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a st (rightmost).*
22450 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 * parameter. For
22460 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 all forms excep
22470 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c t ?NNN, this wil
22480 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 l correspond to
22490 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
224a0 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 unique paramete
224b0 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 rs. If paramete
224c0 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61 rs of the ?NNN a
224d0 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 re used,.** ther
224e0 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e e may be gaps in
224f0 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a the list..**.**
22500 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
22510 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 te3_bind_blob|sq
22520 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a lite3_bind()],.*
22530 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
22540 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 parameter_name()
22550 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
22560 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
22570 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a r_index()]..**.*
22580 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
22590 0a 2a 2a 20 7b 48 31 33 36 30 31 7d 20 54 68 65 .** {H13601} The
225a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
225b0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 53 arameter_count(S
225c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
225d0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 urns.**
225e0 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 the largest ind
225f0 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70 61 ex of all SQL pa
22600 72 61 6d 65 74 65 72 73 20 69 6e 20 74 68 65 0a rameters in the.
22610 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 ** [pre
22620 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
22630 20 53 2c 20 6f 72 20 30 20 69 66 20 53 20 63 6f S, or 0 if S co
22640 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 ntains no SQL pa
22650 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 rameters..*/.int
22660 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 sqlite3_bind_pa
22670 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 rameter_count(sq
22680 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f lite3_stmt*);../
22690 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
226a0 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 ame Of A Host Pa
226b0 72 61 6d 65 74 65 72 20 7b 48 31 33 36 32 30 7d rameter {H13620}
226c0 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S70300>.**.**
226d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 This routine ret
226e0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
226f0 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 o the name of th
22700 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 e n-th.** [SQL p
22710 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b arameter] in a [
22720 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
22730 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 nt]..** SQL para
22740 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f meters of the fo
22750 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 rm "?NNN" or ":A
22760 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 AA" or "@AAA" or
22770 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 "$AAA".** have
22780 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 a name which is
22790 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e the string "?NNN
227a0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 " or ":AAA" or "
227b0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a @AAA" or "$AAA".
227c0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e ** respectively.
227d0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 .** In other wor
227e0 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 ds, the initial
227f0 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 ":" or "$" or "@
22800 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 " or "?".** is i
22810 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 ncluded as part
22820 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 of the name..**
22830 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 Parameters of th
22840 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f e form "?" witho
22850 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 ut a following i
22860 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e nteger have no n
22870 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 ame.** and are a
22880 6c 73 6f 20 72 65 66 65 72 72 65 64 20 74 6f 20 lso referred to
22890 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 as "anonymous pa
228a0 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a rameters"..**.**
228b0 20 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 The first host
228c0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e parameter has an
228d0 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 index of 1, not
228e0 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 0..**.** If the
228f0 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 value n is out
22900 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 of range or if t
22910 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 he n-th paramete
22920 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 r is.** nameless
22930 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 , then NULL is r
22940 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 eturned. The re
22950 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 turned string is
22960 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 .** always in UT
22970 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 F-8 encoding eve
22980 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 n if the named p
22990 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 arameter was.**
229a0 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 originally speci
229b0 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 fied as UTF-16 i
229c0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 n [sqlite3_prepa
229d0 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 re16()] or.** [s
229e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
229f0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 _v2()]..**.** Se
22a00 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
22a10 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
22a20 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b e3_bind()],.** [
22a30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
22a40 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
22a50 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
22a60 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
22a70 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 index()]..**.**
22a80 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
22a90 2a 20 7b 48 31 33 36 32 31 7d 20 54 68 65 20 5b * {H13621} The [
22aa0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
22ab0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 ameter_name(S,N)
22ac0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
22ad0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 rns.**
22ae0 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e a UTF-8 renderin
22af0 67 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f 66 g of the name of
22b00 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 the SQL paramet
22b10 65 72 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 er in.**
22b20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 the [prepared
22b30 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 statement] S hav
22b40 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a ing index N, or.
22b50 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c ** NULL
22b60 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 if there is no
22b70 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77 69 SQL parameter wi
22b80 74 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 th index N or if
22b90 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
22ba0 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 parameter with
22bb0 69 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61 6e index N is an an
22bc0 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 onymous paramete
22bd0 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 r "?"..*/.const
22be0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 char *sqlite3_bi
22bf0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d nd_parameter_nam
22c00 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
22c10 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 int);../*.** CA
22c20 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 PI3REF: Index Of
22c30 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 A Parameter Wit
22c40 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b h A Given Name {
22c50 48 31 33 36 34 30 7d 20 3c 53 37 30 33 30 30 3e H13640} <S70300>
22c60 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 .**.** Return th
22c70 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 e index of an SQ
22c80 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 L parameter give
22c90 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 n its name. The
22ca0 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 .** index value
22cb0 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 returned is suit
22cc0 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 able for use as
22cd0 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 the second.** pa
22ce0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
22cf0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 te3_bind_blob|sq
22d00 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 lite3_bind()].
22d10 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 A zero.** is ret
22d20 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 urned if no matc
22d30 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 hing parameter i
22d40 73 20 66 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 s found. The pa
22d50 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 rameter.** name
22d60 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e must be given in
22d70 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 UTF-8 even if t
22d80 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 he original stat
22d90 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 ement.** was pre
22da0 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 pared from UTF-1
22db0 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6 text using [sq
22dc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
22dd0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 v2()]..**.** See
22de0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
22df0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 bind_blob|sqlite
22e00 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 3_bind()],.** [s
22e10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
22e20 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 meter_count()],
22e30 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
22e40 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
22e50 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 ndex()]..**.** I
22e60 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
22e70 20 7b 48 31 33 36 34 31 7d 20 54 68 65 20 5b 73 {H13641} The [s
22e80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
22e90 6d 65 74 65 72 5f 69 6e 64 65 78 28 53 2c 4e 29 meter_index(S,N)
22ea0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
22eb0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 rns.**
22ec0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 53 51 4c the index of SQL
22ed0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 parameter in th
22ee0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
22ef0 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 ement].**
22f00 20 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 S whose name
22f10 6d 61 74 63 68 65 73 20 74 68 65 20 55 54 46 2d matches the UTF-
22f20 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 8 string N, or 0
22f30 20 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 if there is.**
22f40 20 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 no matc
22f50 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 h..*/.int sqlite
22f60 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
22f70 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 _index(sqlite3_s
22f80 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 tmt*, const char
22f90 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a *zName);../*.**
22fa0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 CAPI3REF: Reset
22fb0 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e All Bindings On
22fc0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 A Prepared Stat
22fd0 65 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c ement {H13660} <
22fe0 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f S70300>.**.** Co
22ff0 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e ntrary to the in
23000 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c tuition of many,
23010 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
23020 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 )] does not rese
23030 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 t.** the [sqlite
23040 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 3_bind_blob | bi
23050 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 ndings] on a [pr
23060 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
23070 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 72 ]..** Use this r
23080 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 outine to reset
23090 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 all host paramet
230a0 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a ers to NULL..**.
230b0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
230c0 2a 0a 2a 2a 20 7b 48 31 33 36 36 31 7d 20 54 68 *.** {H13661} Th
230d0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 e [sqlite3_clear
230e0 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e _bindings(S)] in
230f0 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 61 terface resets a
23100 6c 6c 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 ll SQL.**
23110 20 20 20 70 61 72 61 6d 65 74 65 72 20 62 69 6e parameter bin
23120 64 69 6e 67 73 20 69 6e 20 74 68 65 20 5b 70 72 dings in the [pr
23130 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
23140 5d 20 53 20 62 61 63 6b 20 74 6f 20 4e 55 4c 4c ] S back to NULL
23150 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
23160 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 _clear_bindings(
23170 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
23180 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
23190 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d Number Of Colum
231a0 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 ns In A Result S
231b0 65 74 20 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 et {H13710} <S10
231c0 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 700>.**.** Retur
231d0 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 n the number of
231e0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 columns in the r
231f0 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e esult set return
23200 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 ed by the.** [pr
23210 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
23220 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ]. This routine
23230 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 returns 0 if pSt
23240 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 mt is an SQL.**
23250 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 statement that d
23260 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 oes not return d
23270 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 ata (for example
23280 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a an [UPDATE])..*
23290 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
232a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 31 31 7d 20 .**.** {H13711}
232b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c The [sqlite3_col
232c0 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e umn_count(S)] in
232d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
232e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
232f0 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e column
23300 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 s in the result
23310 73 65 74 20 67 65 6e 65 72 61 74 65 64 20 62 79 set generated by
23320 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
23330 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 tatement] S,.**
23340 20 20 20 20 20 20 20 20 20 6f 72 20 30 20 69 66 or 0 if
23350 20 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 S does not gene
23360 72 61 74 65 20 61 20 72 65 73 75 6c 74 20 73 65 rate a result se
23370 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 t..*/.int sqlite
23380 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 3_column_count(s
23390 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
233a0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
233b0 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 3REF: Column Nam
233c0 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 es In A Result S
233d0 65 74 20 7b 48 31 33 37 32 30 7d 20 3c 53 31 30 et {H13720} <S10
233e0 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 700>.**.** These
233f0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
23400 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e the name assign
23410 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c ed to a particul
23420 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 ar column.** in
23430 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f the result set o
23440 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 f a [SELECT] sta
23450 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c tement. The sql
23460 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
23470 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
23480 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
23490 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d r to a zero-term
234a0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
234b0 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 ing.** and sqlit
234c0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
234d0 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 () returns a poi
234e0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 nter to a zero-t
234f0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 erminated.** UTF
23500 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 -16 string. The
23510 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
23520 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 is the [prepare
23530 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 d statement].**
23540 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 that implements
23550 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 the [SELECT] sta
23560 74 65 6d 65 6e 74 2e 20 54 68 65 20 73 65 63 6f tement. The seco
23570 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
23580 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 the.** column nu
23590 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74 6d mber. The leftm
235a0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 ost column is nu
235b0 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 mber 0..**.** Th
235c0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
235d0 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c g pointer is val
235e0 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 id until either
235f0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
23600 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 atement].** is d
23610 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c estroyed by [sql
23620 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
23630 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 or until the ne
23640 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 xt call to.** sq
23650 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
23660 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 e() or sqlite3_c
23670 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f olumn_name16() o
23680 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d n the same colum
23690 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 n..**.** If sqli
236a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 te3_malloc() fai
236b0 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 ls during the pr
236c0 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 ocessing of eith
236d0 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 er routine.** (f
236e0 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e or example durin
236f0 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 g a conversion f
23700 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 rom UTF-8 to UTF
23710 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e -16) then a.** N
23720 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
23730 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 eturned..**.** T
23740 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 he name of a res
23750 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 ult column is th
23760 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 e value of the "
23770 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a AS" clause for.*
23780 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 * that column, i
23790 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 f there is an AS
237a0 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 clause. If the
237b0 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 re is no AS clau
237c0 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e se.** then the n
237d0 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d ame of the colum
237e0 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 n is unspecified
237f0 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 and may change
23800 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 from.** one rele
23810 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f ase of SQLite to
23820 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a the next..**.**
23830 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
23840 2a 2a 20 7b 48 31 33 37 32 31 7d 20 41 20 73 75 ** {H13721} A su
23850 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 ccessful invocat
23860 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 ion of the [sqli
23870 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
23880 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 S,N)].**
23890 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 interface retu
238a0 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 rns the name of
238b0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 the Nth column (
238c0 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 where 0 is.**
238d0 20 20 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d the leftm
238e0 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 ost column) for
238f0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f the result set o
23900 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 f the.**
23910 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 [prepared stat
23920 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 ement] S as a ze
23930 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
23940 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a F-8 string..**.*
23950 2a 20 7b 48 31 33 37 32 33 7d 20 41 20 73 75 63 * {H13723} A suc
23960 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 cessful invocati
23970 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 on of the [sqlit
23980 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
23990 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 (S,N)].**
239a0 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 interface ret
239b0 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 urns the name of
239c0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
239d0 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 (where 0 is.**
239e0 20 20 20 20 20 20 20 20 74 68 65 20 6c 65 66 74 the left
239f0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 most column) for
23a00 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
23a10 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 of the.**
23a20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 [prepared sta
23a30 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a tement] S as a z
23a40 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
23a50 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 TF-16 string.**
23a60 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65 20 in the
23a70 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
23a80 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 34 r..**.** {H13724
23a90 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
23aa0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e olumn_name()] an
23ab0 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d [sqlite3_colum
23ac0 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 n_name16()].**
23ad0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 interfac
23ae0 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c es return a NULL
23af0 20 70 6f 69 6e 74 65 72 20 69 66 20 74 68 65 79 pointer if they
23b00 20 61 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a are unable to.*
23b10 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 * alloc
23b20 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f ate memory to ho
23b30 6c 64 20 74 68 65 69 72 20 6e 6f 72 6d 61 6c 20 ld their normal
23b40 72 65 74 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a return strings..
23b50 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 35 7d 20 49 **.** {H13725} I
23b60 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 f the N paramete
23b70 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f r to [sqlite3_co
23b80 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 lumn_name(S,N)]
23b90 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b or.** [
23ba0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
23bb0 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f ame16(S,N)] is o
23bc0 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 ut of range, the
23bd0 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 n the.**
23be0 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 interfaces ret
23bf0 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 urn a NULL point
23c00 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 er..**.** {H1372
23c10 36 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 6} The strings r
23c20 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
23c30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
23c40 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 S,N)] and.**
23c50 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 [sqlite3_c
23c60 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e olumn_name16(S,N
23c70 29 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 )] are valid unt
23c80 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 il the next.**
23c90 20 20 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 call to
23ca0 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77 either routine w
23cb0 69 74 68 20 74 68 65 20 73 61 6d 65 20 53 20 61 ith the same S a
23cc0 6e 64 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a nd N parameters.
23cd0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 ** or u
23ce0 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 ntil [sqlite3_fi
23cf0 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 nalize(S)] is ca
23d00 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 lled..**.** {H13
23d10 37 32 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75 727} When a resu
23d20 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b lt column of a [
23d30 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
23d40 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 t contains.**
23d50 20 20 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61 an AS cla
23d60 75 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 use, the name of
23d70 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 that column is
23d80 74 68 65 20 69 64 65 6e 74 69 66 69 65 72 0a 2a the identifier.*
23d90 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 * to th
23da0 65 20 72 69 67 68 74 20 6f 66 20 74 68 65 20 41 e right of the A
23db0 53 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f S keyword..*/.co
23dc0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
23dd0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 3_column_name(sq
23de0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
23df0 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 N);.const void
23e00 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
23e10 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
23e20 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f tmt*, int N);../
23e30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
23e40 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e ource Of Data In
23e50 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 A Query Result
23e60 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30 30 {H13740} <S10700
23e70 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f >.**.** These ro
23e80 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 utines provide a
23e90 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d means to determ
23ea0 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 ine what column
23eb0 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 of what.** table
23ec0 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 61 in which databa
23ed0 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 se a result of a
23ee0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
23ef0 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a ent comes from..
23f00 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 ** The name of t
23f10 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 he database or t
23f20 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 able or column c
23f30 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 an be returned a
23f40 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 s.** either a UT
23f50 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 F-8 or UTF-16 st
23f60 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61 ring. The _data
23f70 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 base_ routines r
23f80 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 eturn.** the dat
23f90 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 abase name, the
23fa0 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 _table_ routines
23fb0 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c return the tabl
23fc0 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 e name, and.** t
23fd0 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 he origin_ routi
23fe0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 nes return the c
23ff0 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 olumn name..** T
24000 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
24010 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 ng is valid unti
24020 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 l the [prepared
24030 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 statement] is de
24040 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 stroyed.** using
24050 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
24060 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 ze()] or until t
24070 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 he same informat
24080 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 ion is requested
24090 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 .** again in a d
240a0 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e ifferent encodin
240b0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d g..**.** The nam
240c0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 es returned are
240d0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d the original un-
240e0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 aliased names of
240f0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
24100 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c , table, and col
24110 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 umn..**.** The f
24120 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
24130 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 the following c
24140 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 alls is a [prepa
24150 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
24160 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f ** These functio
24170 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d ns return inform
24180 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 ation about the
24190 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 Nth column retur
241a0 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 ned by.** the st
241b0 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e atement, where N
241c0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 is the second f
241d0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 unction argument
241e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e ..**.** If the N
241f0 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e th column return
24200 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d ed by the statem
24210 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 ent is an expres
24220 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 sion or.** subqu
24230 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 ery and is not a
24240 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 column value, t
24250 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 hen all of these
24260 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 functions retur
24270 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 n.** NULL. Thes
24280 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 e routine might
24290 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c also return NULL
242a0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c if a memory all
242b0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a ocation error.**
242c0 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77 occurs. Otherw
242d0 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e ise, they return
242e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
242f0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 attached databa
24300 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 se, table.** and
24310 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 column that que
24320 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e ry result column
24330 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 was extracted f
24340 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 rom..**.** As wi
24350 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c th all other SQL
24360 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 ite APIs, those
24370 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22 postfixed with "
24380 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 16" return.** UT
24390 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 F-16 encoded str
243a0 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 ings, the other
243b0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
243c0 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a UTF-8. {END}.**
243d0 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 .** These APIs a
243e0 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c re only availabl
243f0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 e if the library
24400 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 was compiled wi
24410 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 th the.** [SQLIT
24420 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f E_ENABLE_COLUMN_
24430 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 METADATA] C-prep
24440 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 rocessor symbol
24450 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b defined..**.** {
24460 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 A13751}.** If tw
24470 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 o or more thread
24480 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f s call one or mo
24490 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 re of these rout
244a0 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 ines against the
244b0 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 same.** prepare
244c0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 d statement and
244d0 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 column at the sa
244e0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 me time then the
244f0 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 results are.**
24500 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
24510 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
24520 2a 2a 20 7b 48 31 33 37 34 31 7d 20 54 68 65 20 ** {H13741} The
24530 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
24540 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c database_name(S,
24550 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 N)] interface re
24560 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 turns either.**
24570 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 the UTF
24580 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 -8 zero-terminat
24590 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 ed name of the d
245a0 61 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69 atabase from whi
245b0 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ch the.**
245c0 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f Nth result co
245d0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 lumn of the [pre
245e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
245f0 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c S is extracted,
24600 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
24610 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 NULL if the Nth
24620 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 column of S is a
24630 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 general express
24640 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ion.**
24650 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 or if unable to
24660 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 allocate memory
24670 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d to store the nam
24680 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 32 e..**.** {H13742
24690 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
246a0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e olumn_database_n
246b0 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 ame16(S,N)] inte
246c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 rface returns ei
246d0 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 ther.**
246e0 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 the UTF-16 nati
246f0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 ve byte order ze
24700 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 ro-terminated na
24710 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 me of the databa
24720 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 se.** f
24730 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74 rom which the Nt
24740 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 h result column
24750 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 of the [prepared
24760 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 statement] S is
24770 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 74 .** ext
24780 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 racted, or NULL
24790 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d if the Nth colum
247a0 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 n of S is a gene
247b0 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a ral expression.*
247c0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 * or if
247d0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
247e0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 ate memory to st
247f0 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a ore the name..**
24800 0a 2a 2a 20 7b 48 31 33 37 34 33 7d 20 54 68 65 .** {H13743} The
24810 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
24820 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 _table_name(S,N)
24830 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
24840 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 rns either.**
24850 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 the UTF-8
24860 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
24870 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 name of the tab
24880 6c 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 le from which th
24890 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 e.** Nt
248a0 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 h result column
248b0 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 of the [prepared
248c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 statement] S is
248d0 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 extracted,.**
248e0 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 or NULL
248f0 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d if the Nth colum
24900 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 n of S is a gene
24910 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a ral expression.*
24920 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 * or if
24930 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
24940 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 ate memory to st
24950 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a ore the name..**
24960 0a 2a 2a 20 7b 48 31 33 37 34 34 7d 20 54 68 65 .** {H13744} The
24970 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
24980 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c _table_name16(S,
24990 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 N)] interface re
249a0 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 turns either.**
249b0 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 the UTF
249c0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 -16 native byte
249d0 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 order zero-termi
249e0 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 nated name of th
249f0 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 e table.**
24a00 20 20 20 20 66 72 6f 6d 20 77 68 69 63 68 20 74 from which t
24a10 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f he Nth result co
24a20 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 lumn of the [pre
24a30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
24a40 20 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 S is.**
24a50 20 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 extracted, or
24a60 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 NULL if the Nth
24a70 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 column of S is a
24a80 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 general express
24a90 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ion.**
24aa0 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 or if unable to
24ab0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 allocate memory
24ac0 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d to store the nam
24ad0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 35 e..**.** {H13745
24ae0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
24af0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d olumn_origin_nam
24b00 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 e(S,N)] interfac
24b10 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 e returns either
24b20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
24b30 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d UTF-8 zero-term
24b40 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 inated name of t
24b50 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 he table column
24b60 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a from which the.*
24b70 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 * Nth r
24b80 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 esult column of
24b90 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
24ba0 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 atement] S is ex
24bb0 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 tracted,.**
24bc0 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 or NULL if
24bd0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f the Nth column o
24be0 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c f S is a general
24bf0 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 expression.**
24c00 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e or if un
24c10 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 able to allocate
24c20 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 memory to store
24c30 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a the name..**.**
24c40 20 7b 48 31 33 37 34 36 7d 20 54 68 65 20 5b 73 {H13746} The [s
24c50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 qlite3_column_or
24c60 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 igin_name16(S,N)
24c70 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
24c80 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 rns either.**
24c90 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 the UTF-1
24ca0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 6 native byte or
24cb0 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 der zero-termina
24cc0 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 ted name of the
24cd0 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 table.**
24ce0 20 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 column from wh
24cf0 69 63 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 ich the Nth resu
24d00 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 lt column of the
24d10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
24d20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
24d30 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64 ] S is extracted
24d40 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 , or NULL if the
24d50 20 4e 74 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 Nth column.**
24d60 20 20 20 20 20 20 20 20 6f 66 20 53 20 69 73 20 of S is
24d70 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 a general expres
24d80 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c sion or if unabl
24d90 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 e to allocate me
24da0 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 mory.**
24db0 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 to store the na
24dc0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 me..**.** {H1374
24dd0 38 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 8} The return va
24de0 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 lues from.**
24df0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 [sqlite3_c
24e00 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e olumn_database_n
24e10 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 ame | column met
24e20 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 adata interfaces
24e30 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 ].** ar
24e40 65 20 76 61 6c 69 64 20 66 6f 72 20 74 68 65 20 e valid for the
24e50 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 lifetime of the
24e60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
24e70 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ent].**
24e80 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 65 6e or until the en
24e90 63 6f 64 69 6e 67 20 69 73 20 63 68 61 6e 67 65 coding is change
24ea0 64 20 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 d by another met
24eb0 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 adata.**
24ec0 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c interface call
24ed0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 70 72 for the same pr
24ee0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
24ef0 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a and column..**.
24f00 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a ** ASSUMPTIONS:.
24f10 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 20 49 **.** {A13751} I
24f20 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 f two or more th
24f30 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f reads call one o
24f40 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 r more.**
24f50 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 [sqlite3_colu
24f60 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 mn_database_name
24f70 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 | column metada
24f80 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a ta interfaces].*
24f90 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 74 * for t
24fa0 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 he same [prepare
24fb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 d statement] and
24fc0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a result column.*
24fd0 2a 20 20 20 20 20 20 20 20 20 20 61 74 20 74 68 * at th
24fe0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e e same time then
24ff0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
25000 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 undefined..*/.c
25010 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
25020 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 e3_column_databa
25030 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f se_name(sqlite3_
25040 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
25050 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
25060 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
25070 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
25080 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 tmt*,int);.const
25090 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
250a0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 olumn_table_name
250b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
250c0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
250d0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
250e0 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c table_name16(sql
250f0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
25100 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
25110 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 ite3_column_orig
25120 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f in_name(sqlite3_
25130 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
25140 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
25150 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
25160 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
25170 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t*,int);../*.**
25180 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 CAPI3REF: Declar
25190 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 ed Datatype Of A
251a0 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 Query Result {H
251b0 31 33 37 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 13760} <S10700>.
251c0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
251d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b parameter is a [
251e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
251f0 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 nt]..** If this
25200 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b statement is a [
25210 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
25220 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f t and the Nth co
25230 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 lumn of the.** r
25240 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 eturned result s
25250 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 et of that [SELE
25260 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 CT] is a table c
25270 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a olumn (not an.**
25280 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 expression or s
25290 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 ubquery) then th
252a0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 e declared type
252b0 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 of the table.**
252c0 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e column is return
252d0 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 ed. If the Nth
252e0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 column of the re
252f0 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a sult set is an.*
25300 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 * expression or
25310 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 subquery, then a
25320 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 NULL pointer is
25330 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 returned..** Th
25340 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
25350 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d g is always UTF-
25360 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 8 encoded. {END}
25370 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 .**.** For examp
25380 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 le, given the da
25390 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a tabase schema:.*
253a0 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c *.** CREATE TABL
253b0 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 E t1(c1 VARIANT)
253c0 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 ;.**.** and the
253d0 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d following statem
253e0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c ent to be compil
253f0 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 ed:.**.** SELECT
25400 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d c1 + 1, c1 FROM
25410 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 t1;.**.** this
25420 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 routine would re
25430 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 turn the string
25440 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 "VARIANT" for th
25450 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a e second result.
25460 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 ** column (i==1)
25470 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 , and a NULL poi
25480 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 nter for the fir
25490 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e st result column
254a0 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 (i==0)..**.** S
254b0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d QLite uses dynam
254c0 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 ic run-time typi
254d0 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 ng. So just bec
254e0 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a ause a column.**
254f0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 is declared to
25500 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 contain a partic
25510 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e ular type does n
25520 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 ot mean that the
25530 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 .** data stored
25540 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 in that column i
25550 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 s of the declare
25560 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 d type. SQLite
25570 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 is.** strongly t
25580 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 yped, but the ty
25590 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 ping is dynamic
255a0 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 not static. Typ
255b0 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 e.** is associat
255c0 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 ed with individu
255d0 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 al values, not w
255e0 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 ith the containe
255f0 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f rs.** used to ho
25600 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e ld those values.
25610 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
25620 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 31 S:.**.** {H13761
25630 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 } A successful
25640 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
25650 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 _column_decltype
25660 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 (S,N)] returns a
25670 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 7a 65 .** ze
25680 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
25690 46 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 F-8 string conta
256a0 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72 ining the declar
256b0 65 64 20 64 61 74 61 74 79 70 65 0a 2a 2a 20 20 ed datatype.**
256c0 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 of the
256d0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 table column tha
256e0 74 20 61 70 70 65 61 72 73 20 61 73 20 74 68 65 t appears as the
256f0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d Nth column (num
25700 62 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 bered.**
25710 20 20 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 from 0) of th
25720 65 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 e result set to
25730 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
25740 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a atement] S..**.*
25750 2a 20 7b 48 31 33 37 36 32 7d 20 20 41 20 73 75 * {H13762} A su
25760 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
25770 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
25780 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 _decltype16(S,N)
25790 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 ].** r
257a0 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 eturns a zero-te
257b0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 rminated UTF-16
257c0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
257d0 72 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 r string.**
257e0 20 20 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 containing
257f0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 the declared da
25800 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 tatype of the ta
25810 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 ble column that
25820 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 appears.**
25830 20 20 20 20 20 61 73 20 74 68 65 20 4e 74 68 20 as the Nth
25840 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 column (numbered
25850 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 from 0) of the
25860 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 result set to th
25870 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b e.** [
25880 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
25890 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 nt] S..**.** {H1
258a0 33 37 36 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 3763} If N is l
258b0 65 73 73 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 ess than 0 or N
258c0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 is greater than
258d0 6f 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 or equal to.**
258e0 20 20 20 20 20 20 20 20 20 74 68 65 20 6e 75 6d the num
258f0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
25900 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 n the [prepared
25910 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a statement] S,.**
25920 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 or if
25930 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
25940 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70 72 65 of S is an expre
25950 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 ssion or subquer
25960 79 20 72 61 74 68 65 72 0a 2a 2a 20 20 20 20 20 y rather.**
25970 20 20 20 20 20 20 74 68 61 6e 20 61 20 74 61 62 than a tab
25980 6c 65 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 le column, or if
25990 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
259a0 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20 tion failure.**
259b0 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 occurs
259c0 20 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67 during encoding
259d0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68 conversions, th
259e0 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 en.**
259f0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
25a00 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 3_column_decltyp
25a10 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 e(S,N)] or.**
25a20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
25a30 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 _column_decltype
25a40 31 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20 16(S,N)] return
25a50 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 NULL..*/.const c
25a60 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
25a70 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c umn_decltype(sql
25a80 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
25a90 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
25aa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c ite3_column_decl
25ab0 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 type16(sqlite3_s
25ac0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a tmt*,int);../*.*
25ad0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c * CAPI3REF: Eval
25ae0 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 uate An SQL Stat
25af0 65 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c ement {H13200} <
25b00 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 S10000>.**.** Af
25b10 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 ter a [prepared
25b20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 statement] has b
25b30 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 een prepared usi
25b40 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 ng either.** [sq
25b50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
25b60 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
25b70 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 prepare16_v2()]
25b80 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 or one of the le
25b90 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 gacy.** interfac
25ba0 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 es [sqlite3_prep
25bb0 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 are()] or [sqlit
25bc0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c e3_prepare16()],
25bd0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a this function.*
25be0 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 * must be called
25bf0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
25c00 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 es to evaluate t
25c10 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a he statement..**
25c20 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 .** The details
25c30 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 of the behavior
25c40 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 of the sqlite3_s
25c50 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 tep() interface
25c60 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 depend.** on whe
25c70 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 ther the stateme
25c80 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 nt was prepared
25c90 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 using the newer
25ca0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a "v2" interface.*
25cb0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
25cc0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
25cd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
25ce0 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 v2()] or the old
25cf0 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 er legacy.** int
25d00 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f erface [sqlite3_
25d10 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b prepare()] and [
25d20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
25d30 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 6()]. The use o
25d40 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 f the.** new "v2
25d50 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 " interface is r
25d60 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e ecommended for n
25d70 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ew applications
25d80 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a but the legacy.*
25d90 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c * interface will
25da0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 continue to be
25db0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a supported..**.**
25dc0 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 In the legacy i
25dd0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 nterface, the re
25de0 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 turn value will
25df0 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 be either [SQLIT
25e00 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c E_BUSY],.** [SQL
25e10 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 ITE_DONE], [SQLI
25e20 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 TE_ROW], [SQLITE
25e30 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c _ERROR], or [SQL
25e40 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 ITE_MISUSE]..**
25e50 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e With the "v2" in
25e60 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 terface, any of
25e70 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c the other [resul
25e80 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b t codes] or.** [
25e90 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
25ea0 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 codes] might be
25eb0 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c returned as well
25ec0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ..**.** [SQLITE_
25ed0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 BUSY] means that
25ee0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e the database en
25ef0 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 gine was unable
25f00 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a to acquire the.*
25f10 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 * database locks
25f20 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 it needs to do
25f30 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 its job. If the
25f40 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 statement is a
25f50 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f [COMMIT].** or o
25f60 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 ccurs outside of
25f70 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 an explicit tra
25f80 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 nsaction, then y
25f90 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 ou can retry the
25fa0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 .** statement.
25fb0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 If the statement
25fc0 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 is not a [COMMI
25fd0 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 T] and occurs wi
25fe0 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 thin a.** explic
25ff0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 it transaction t
26000 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 hen you should r
26010 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e ollback the tran
26020 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a saction before.*
26030 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a * continuing..**
26040 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 .** [SQLITE_DONE
26050 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
26060 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 statement has f
26070 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e inished executin
26080 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c g.** successfull
26090 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 y. sqlite3_step
260a0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 () should not be
260b0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e called again on
260c0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a this virtual.**
260d0 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 machine without
260e0 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b first calling [
260f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
26100 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 to reset the vi
26110 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 rtual.** machine
26120 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 back to its ini
26130 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a tial state..**.*
26140 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 * If the SQL sta
26150 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 tement being exe
26160 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e cuted returns an
26170 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 y data, then [SQ
26180 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 LITE_ROW].** is
26190 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 returned each ti
261a0 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 me a new row of
261b0 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f data is ready fo
261c0 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 r processing by
261d0 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 the.** caller. T
261e0 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 he values may be
261f0 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 accessed using
26200 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 the [column acce
26210 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a ss functions]..*
26220 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
26230 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e is called again
26240 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 to retrieve the
26250 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 next row of dat
26260 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 a..**.** [SQLITE
26270 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 _ERROR] means th
26280 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 at a run-time er
26290 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 ror (such as a c
262a0 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f onstraint.** vio
262b0 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 lation) has occu
262c0 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 rred. sqlite3_s
262d0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 tep() should not
262e0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e be called again
262f0 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d on.** the VM. M
26300 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 ore information
26310 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 may be found by
26320 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
26330 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 _errmsg()]..** W
26340 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 ith the legacy i
26350 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 nterface, a more
26360 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 specific error
26370 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c code (for exampl
26380 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e e,.** [SQLITE_IN
26390 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 TERRUPT], [SQLIT
263a0 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 E_SCHEMA], [SQLI
263b0 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 TE_CORRUPT], and
263c0 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 so forth).** ca
263d0 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 n be obtained by
263e0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
263f0 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 3_reset()] on th
26400 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
26410 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 tatement]. In t
26420 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
26430 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 e,.** the more s
26440 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f pecific error co
26450 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 de is returned d
26460 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 irectly by sqlit
26470 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a e3_step()..**.**
26480 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
26490 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
264a0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 this routine was
264b0 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 called inapprop
264c0 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 riately..** Perh
264d0 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 aps it was calle
264e0 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 d on a [prepared
264f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
26500 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 has.** already
26510 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 been [sqlite3_fi
26520 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a nalize | finaliz
26530 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 ed] or on one th
26540 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f at had.** previo
26550 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 usly returned [S
26560 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 QLITE_ERROR] or
26570 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 [SQLITE_DONE].
26580 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 Or it could.** b
26590 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 e the case that
265a0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
265b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
265c0 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 being used by tw
265d0 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 o or.** more thr
265e0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 eads at the same
265f0 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e moment in time.
26600 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 .**.** <b>Goofy
26610 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a Interface Alert:
26620 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 </b> In the lega
26630 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 cy interface, th
26640 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 e sqlite3_step()
26650 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 .** API always r
26660 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 eturns a generic
26670 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 error code, [SQ
26680 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c LITE_ERROR], fol
26690 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 lowing any.** er
266a0 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b ror other than [
266b0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 SQLITE_BUSY] and
266c0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
266d0 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c . You must call
266e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
266f0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 et()] or [sqlite
26700 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 3_finalize()] in
26710 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f order to find o
26720 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 ne of the.** spe
26730 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 cific [error cod
26740 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 es] that better
26750 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 describes the er
26760 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 ror..** We admit
26770 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 that this is a
26780 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 goofy design. T
26790 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 he problem has b
267a0 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 een fixed.** wit
267b0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 h the "v2" inter
267c0 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 face. If you pr
267d0 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 epare all of you
267e0 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 r SQL statements
267f0 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 .** using either
26800 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
26810 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 e_v2()] or [sqli
26820 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
26830 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f ()] instead.** o
26840 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 f the legacy [sq
26850 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
26860 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 and [sqlite3_pr
26870 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 epare16()] inter
26880 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 faces,.** then t
26890 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 he more specific
268a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 [error codes] a
268b0 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 re returned dire
268c0 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 ctly.** by sqlit
268d0 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 e3_step(). The
268e0 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 use of the "v2"
268f0 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 interface is rec
26900 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 ommended..**.**
26910 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
26920 2a 20 7b 48 31 33 32 30 32 7d 20 20 49 66 20 74 * {H13202} If t
26930 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
26940 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 61 tement] S is rea
26950 64 79 20 74 6f 20 62 65 20 72 75 6e 2c 20 74 68 dy to be run, th
26960 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 en.**
26970 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
26980 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61 74 20 ] advances that
26990 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
269a0 6e 74 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 nt until.**
269b0 20 20 20 20 20 20 63 6f 6d 70 6c 65 74 69 6f 6e completion
269c0 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69 73 20 or until it is
269d0 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 20 ready to return
269e0 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 another row of t
269f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 he.**
26a00 72 65 73 75 6c 74 20 73 65 74 2c 20 6f 72 20 75 result set, or u
26a10 6e 74 69 6c 20 61 6e 20 5b 73 71 6c 69 74 65 33 ntil an [sqlite3
26a20 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 _interrupt | int
26a30 65 72 72 75 70 74 5d 0a 2a 2a 20 20 20 20 20 20 errupt].**
26a40 20 20 20 20 20 6f 72 20 61 20 72 75 6e 2d 74 69 or a run-ti
26a50 6d 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e me error occurs.
26a60 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 34 7d 20 .**.** {H15304}
26a70 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 When a call to
26a80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
26a90 5d 20 63 61 75 73 65 73 20 74 68 65 20 5b 70 72 ] causes the [pr
26aa0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
26ab0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 53 ].** S
26ac0 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c to run to compl
26ad0 65 74 69 6f 6e 2c 20 74 68 65 20 66 75 6e 63 74 etion, the funct
26ae0 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ion returns [SQL
26af0 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a ITE_DONE]..**.**
26b00 20 7b 48 31 35 33 30 36 7d 20 20 57 68 65 6e 20 {H15306} When
26b10 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 a call to [sqlit
26b20 65 33 5f 73 74 65 70 28 53 29 5d 20 73 74 6f 70 e3_step(S)] stop
26b30 73 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 s because it is
26b40 72 65 61 64 79 20 74 6f 0a 2a 2a 20 20 20 20 20 ready to.**
26b50 20 20 20 20 20 20 72 65 74 75 72 6e 20 61 6e 6f return ano
26b60 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 20 ther row of the
26b70 72 65 73 75 6c 74 20 73 65 74 2c 20 69 74 20 72 result set, it r
26b80 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 eturns [SQLITE_R
26b90 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 OW]..**.** {H153
26ba0 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20 74 08} If a call t
26bb0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
26bc0 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 S)] encounters a
26bd0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b n.** [
26be0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
26bf0 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 6f t | interrupt] o
26c00 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 r a run-time err
26c10 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or,.**
26c20 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 61 it returns an a
26c30 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 ppropriate error
26c40 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e 6f code that is no
26c50 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 t one of.**
26c60 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b [SQLITE_OK
26c70 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c ], [SQLITE_ROW],
26c80 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 or [SQLITE_DONE
26c90 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31 30 ]..**.** {H15310
26ca0 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 } If an [sqlite
26cb0 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 3_interrupt | in
26cc0 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75 terrupt] or a ru
26cd0 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 n-time error.**
26ce0 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 occurs
26cf0 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 during a call t
26d00 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
26d10 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 S)].**
26d20 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72 65 64 for a [prepared
26d30 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 63 72 statement] S cr
26d40 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 eated using.**
26d50 20 20 20 20 20 20 20 20 20 6c 65 67 61 63 79 20 legacy
26d60 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 interfaces [sqli
26d70 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f te3_prepare()] o
26d80 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b r.** [
26d90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
26da0 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6()], then the f
26db0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
26dc0 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 either.**
26dd0 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f [SQLITE_ERRO
26de0 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 R], [SQLITE_BUSY
26df0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 ], or [SQLITE_MI
26e00 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 SUSE]..*/.int sq
26e10 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 lite3_step(sqlit
26e20 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
26e30 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
26e40 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
26e50 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b 48 a result set {H
26e60 31 33 37 37 30 7d 20 3c 53 31 30 37 30 30 3e 0a 13770} <S10700>.
26e70 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 **.** Returns th
26e80 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 e number of valu
26e90 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e es in the curren
26ea0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 t row of the res
26eb0 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 ult set..**.** I
26ec0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
26ed0 20 7b 48 31 33 37 37 31 7d 20 20 41 66 74 65 72 {H13771} After
26ee0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
26ef0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74 68 61 te3_step(S)] tha
26f00 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 t returns [SQLIT
26f10 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20 20 E_ROW],.**
26f20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 the [sqlite
26f30 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 3_data_count(S)]
26f40 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 routine will re
26f50 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 turn the same va
26f60 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 lue.**
26f70 20 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 as the [sqlite3
26f80 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 _column_count(S)
26f90 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a ] function..**.*
26fa0 2a 20 7b 48 31 33 37 37 32 7d 20 20 41 66 74 65 * {H13772} Afte
26fb0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 r [sqlite3_step(
26fc0 53 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 S)] has returned
26fd0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 any value other
26fe0 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 than.**
26ff0 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 [SQLITE_ROW]
27000 6f 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 or before [sqlit
27010 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 e3_step(S)] has
27020 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 74 been called on t
27030 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 he.**
27040 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
27050 65 6e 74 5d 20 66 6f 72 20 74 68 65 20 66 69 72 ent] for the fir
27060 73 74 20 74 69 6d 65 20 73 69 6e 63 65 20 69 74 st time since it
27070 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 was.**
27080 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 [sqlite3_prepa
27090 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 6f re | prepared] o
270a0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
270b0 20 7c 20 72 65 73 65 74 5d 2c 0a 2a 2a 20 20 20 | reset],.**
270c0 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c the [sql
270d0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
270e0 53 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 S)] routine retu
270f0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 rns zero..*/.int
27100 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
27110 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
27120 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
27130 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 CAPI3REF: Funda
27140 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 mental Datatypes
27150 20 7b 48 31 30 32 36 35 7d 20 3c 53 31 30 31 31 {H10265} <S1011
27160 30 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 0><S10120>.** KE
27170 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 YWORDS: SQLITE_T
27180 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 EXT.**.** {H1026
27190 36 7d 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6} Every value i
271a0 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 n SQLite has one
271b0 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 of five fundame
271c0 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a ntal datatypes:.
271d0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
271e0 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 i> 64-bit signed
271f0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e integer.** <li>
27200 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 64-bit IEEE flo
27210 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 ating point numb
27220 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e er.** <li> strin
27230 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a g.** <li> BLOB.*
27240 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c * <li> NULL.** <
27250 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a /ul> {END}.**.**
27260 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
27270 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 are codes for e
27280 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 ach of those typ
27290 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 es..**.** Note t
272a0 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 hat the SQLITE_T
272b0 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 EXT constant was
272c0 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 also used in SQ
272d0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a Lite version 2.*
272e0 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 * for a complete
272f0 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 ly different mea
27300 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 ning. Software
27310 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e that links again
27320 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 st both.** SQLit
27330 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 e version 2 and
27340 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
27350 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 should use SQLI
27360 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a TE3_TEXT, not.**
27370 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f SQLITE_TEXT..*/
27380 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
27390 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 INTEGER 1.#defi
273a0 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 ne SQLITE_FLOAT
273b0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
273c0 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 ITE_BLOB 4.#
273d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 define SQLITE_NU
273e0 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 LL 5.#ifdef
273f0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e SQLITE_TEXT.# un
27400 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a def SQLITE_TEXT.
27410 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 #else.# define S
27420 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 QLITE_TEXT 3
27430 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 .#endif.#define
27440 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 SQLITE3_TEXT
27450 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 3../*.** CAPI3R
27460 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 EF: Result Value
27470 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b s From A Query {
27480 48 31 33 38 30 30 7d 20 3c 53 31 30 37 30 30 3e H13800} <S10700>
27490 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 .** KEYWORDS: {c
274a0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e olumn access fun
274b0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 ctions}.**.** Th
274c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 ese routines for
274d0 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 m the "result se
274e0 74 20 71 75 65 72 79 22 20 69 6e 74 65 72 66 61 t query" interfa
274f0 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ce..**.** These
27500 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
27510 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 information abou
27520 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d t a single colum
27530 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 n of the current
27540 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f .** result row o
27550 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 f a query. In e
27560 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 very case the fi
27570 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
27580 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 a pointer.** to
27590 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
275a0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 atement] that is
275b0 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 being evaluated
275c0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 (the [sqlite3_s
275d0 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 tmt*].** that wa
275e0 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 s returned from
275f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
27600 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 _v2()] or one of
27610 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a its variants).*
27620 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 * and the second
27630 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
27640 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f index of the co
27650 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 lumn for which i
27660 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 nformation.** sh
27670 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 ould be returned
27680 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 . The leftmost
27690 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 column of the re
276a0 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 sult set has the
276b0 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 index 0..**.**
276c0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 If the SQL state
276d0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 ment does not cu
276e0 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f rrently point to
276f0 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 a valid row, or
27700 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d if the.** colum
27710 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f n index is out o
27720 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 f range, the res
27730 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ult is undefined
27740 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 ..** These routi
27750 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 nes may only be
27760 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 called when the
27770 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c most recent call
27780 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
27790 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 step()] has retu
277a0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 rned [SQLITE_ROW
277b0 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a ] and neither.**
277c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
277d0 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f )] nor [sqlite3_
277e0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 finalize()] have
277f0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 been called sub
27800 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 sequently..** If
27810 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f any of these ro
27820 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 utines are calle
27830 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 d after [sqlite3
27840 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 _reset()] or.**
27850 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
27860 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 e()] or after [s
27870 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 qlite3_step()] h
27880 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 as returned.** s
27890 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 omething other t
278a0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d han [SQLITE_ROW]
278b0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 , the results ar
278c0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 e undefined..**
278d0 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 If [sqlite3_step
278e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
278f0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c reset()] or [sql
27900 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
27910 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 .** are called f
27920 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 rom a different
27930 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 thread while any
27940 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
27950 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e es.** are pendin
27960 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 g, then the resu
27970 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 lts are undefine
27980 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c d..**.** The sql
27990 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
279a0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
279b0 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 ns the.** [SQLIT
279c0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 E_INTEGER | data
279d0 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 type code] for t
279e0 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 he initial data
279f0 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 type.** of the r
27a00 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 esult column. T
27a10 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 he returned valu
27a20 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c e is one of [SQL
27a30 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a ITE_INTEGER],.**
27a40 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c [SQLITE_FLOAT],
27a50 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 [SQLITE_TEXT],
27a60 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f [SQLITE_BLOB], o
27a70 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e r [SQLITE_NULL].
27a80 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 The value.** r
27a90 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
27aa0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
27ab0 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 is only meaning
27ac0 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a ful if no type.*
27ad0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 * conversions ha
27ae0 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 ve occurred as d
27af0 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 escribed below.
27b00 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f After a type co
27b10 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 nversion,.** the
27b20 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
27b30 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
27b40 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 n_type() is unde
27b50 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a fined. Future.*
27b60 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 * versions of SQ
27b70 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 Lite may change
27b80 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
27b90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
27ba0 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 ype().** followi
27bb0 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 ng a type conver
27bc0 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 sion..**.** If t
27bd0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 he result is a B
27be0 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 LOB or UTF-8 str
27bf0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c ing then the sql
27c00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
27c10 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 s().** routine r
27c20 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
27c30 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
27c40 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e at BLOB or strin
27c50 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 g..** If the res
27c60 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 ult is a UTF-16
27c70 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c string, then sql
27c80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
27c90 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 s() converts.**
27ca0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 the string to UT
27cb0 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 F-8 and then ret
27cc0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
27cd0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 of bytes..** If
27ce0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
27cf0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 numeric value th
27d00 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
27d10 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a n_bytes() uses.*
27d20 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 * [sqlite3_snpri
27d30 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 ntf()] to conver
27d40 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 t that value to
27d50 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 a UTF-8 string a
27d60 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 nd returns.** th
27d70 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
27d80 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 s in that string
27d90 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 ..** The value r
27da0 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 eturned does not
27db0 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 include the zer
27dc0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 o terminator at
27dd0 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 the end.** of th
27de0 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 e string. For c
27df0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 larity: the valu
27e00 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 e returned is th
27e10 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 e number of.** b
27e20 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 ytes in the stri
27e30 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 ng, not the numb
27e40 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
27e50 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 ..**.** Strings
27e60 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
27e70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
27e80 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f ) and sqlite3_co
27e90 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a lumn_text16(),.*
27ea0 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 * even empty str
27eb0 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 ings, are always
27ec0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 zero terminated
27ed0 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a . The return.**
27ee0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
27ef0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
27f00 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e ) for a zero-len
27f10 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 gth BLOB is an a
27f20 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e rbitrary.** poin
27f30 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 ter, possibly ev
27f40 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 en a NULL pointe
27f50 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c r..**.** The sql
27f60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
27f70 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 s16() routine is
27f80 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 similar to sqli
27f90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
27fa0 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 ().** but leaves
27fb0 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 the result in U
27fc0 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 TF-16 in native
27fd0 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 byte order inste
27fe0 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 ad of UTF-8..**
27ff0 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 The zero termina
28000 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 tor is not inclu
28010 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e ded in this coun
28020 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a t..**.** The obj
28030 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 ect returned by
28040 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
28050 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a value()] is an.*
28060 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 * [unprotected s
28070 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
28080 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 ject. An unprot
28090 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
280a0 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 lue object.** ma
280b0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 y only be used w
280c0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e ith [sqlite3_bin
280d0 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b d_value()] and [
280e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
280f0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 alue()]..** If t
28100 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 he [unprotected
28110 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
28120 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 bject returned b
28130 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f y.** [sqlite3_co
28140 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 lumn_value()] is
28150 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 used in any oth
28160 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e er way, includin
28170 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f g calls.** to ro
28180 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c utines like [sql
28190 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 ite3_value_int()
281a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
281b0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 e_text()],.** or
281c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
281d0 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 bytes()], then t
281e0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
281f0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
28200 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
28210 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 ttempt to conver
28220 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 t the value wher
28230 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 e appropriate.
28240 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 For.** example,
28250 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 if the internal
28260 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 representation i
28270 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 s FLOAT and a te
28280 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 xt result.** is
28290 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 requested, [sqli
282a0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 te3_snprintf()]
282b0 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c is used internal
282c0 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 ly to perform th
282d0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 e.** conversion
282e0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 automatically.
282f0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 The following ta
28300 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 ble details the
28310 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 conversions.** t
28320 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a hat are applied:
28330 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
28340 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f te>.** <table bo
28350 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 rder="1">.** <tr
28360 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 ><th> Internal<b
28370 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 r>Type <th> Requ
28380 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 ested<br>Type <t
28390 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a h> Conversion.*
283a0 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e *.** <tr><td> N
283b0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 ULL <td> INTE
283c0 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c GER <td> Resul
283d0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 t is 0.** <tr><t
283e0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
283f0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
28400 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a Result is 0.0.**
28410 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
28420 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
28430 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
28440 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
28450 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
28460 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
28470 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
28480 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
28490 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
284a0 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 R <td> FLOAT
284b0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 <td> Convert f
284c0 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 rom integer to f
284d0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e loat.** <tr><td>
284e0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 INTEGER <td>
284f0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 TEXT <td> AS
28500 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 CII rendering of
28510 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 the integer.**
28520 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 <tr><td> INTEGER
28530 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
28540 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e <td> Same as IN
28550 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c TEGER->TEXT.** <
28560 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 tr><td> FLOAT
28570 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
28580 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f <td> Convert fro
28590 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 m float to integ
285a0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 er.** <tr><td>
285b0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 FLOAT <td> T
285c0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 EXT <td> ASCI
285d0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 I rendering of t
285e0 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e he float.** <tr>
285f0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 <td> FLOAT <t
28600 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
28610 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d > Same as FLOAT-
28620 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 >TEXT.** <tr><td
28630 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 > TEXT <td>
28640 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 INTEGER <td> U
28650 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 se atoi().** <tr
28660 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c ><td> TEXT <
28670 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
28680 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a d> Use atof().**
28690 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 <tr><td> TEXT
286a0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
286b0 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 <td> No change
286c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c .** <tr><td> BL
286d0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 OB <td> INTEG
286e0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 ER <td> Conver
286f0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 t to TEXT then u
28700 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 se atoi().** <tr
28710 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c ><td> BLOB <
28720 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
28730 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 d> Convert to TE
28740 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 XT then use atof
28750 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ().** <tr><td>
28760 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 BLOB <td> T
28770 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 EXT <td> Add
28780 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f a zero terminato
28790 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c r if needed.** <
287a0 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f /table>.** </blo
287b0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
287c0 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d he table above m
287d0 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 akes reference t
287e0 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 o standard C lib
287f0 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 rary functions a
28800 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f toi().** and ato
28810 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 f(). SQLite doe
28820 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 s not really use
28830 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
28840 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a . It has its.**
28850 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 own equivalent
28860 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 internal routine
28870 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 s. The atoi() a
28880 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 nd atof() names
28890 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 are.** used in t
288a0 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 he table for bre
288b0 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 vity and because
288c0 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 they are famili
288d0 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 ar to most.** C
288e0 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a programmers..**.
288f0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 ** Note that whe
28900 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f n type conversio
28910 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 ns occur, pointe
28920 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 rs returned by p
28930 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f rior.** calls to
28940 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
28950 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f blob(), sqlite3_
28960 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 column_text(), a
28970 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 nd/or.** sqlite3
28980 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
28990 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 may be invalida
289a0 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e ted..** Type con
289b0 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 versions and poi
289c0 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f nter invalidatio
289d0 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a ns might occur.*
289e0 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 * in the followi
289f0 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 ng cases:.**.**
28a00 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 <ul>.** <li> The
28a10 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
28a20 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 is a BLOB and s
28a30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
28a40 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 xt() or.**
28a50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
28a60 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 ext16() is calle
28a70 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 d. A zero-termi
28a80 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 nator might.**
28a90 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 need to be a
28aa0 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 dded to the stri
28ab0 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e ng.</li>.** <li>
28ac0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e The initial con
28ad0 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 tent is UTF-8 te
28ae0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 xt and sqlite3_c
28af0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
28b00 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 or.** sqlit
28b10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
28b20 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 () is called. T
28b30 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 he content must
28b40 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 be converted.**
28b50 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c to UTF-16.<
28b60 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 /li>.** <li> The
28b70 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
28b80 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 is UTF-16 text
28b90 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
28ba0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a mn_bytes() or.**
28bb0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f sqlite3_co
28bc0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 lumn_text() is c
28bd0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 alled. The cont
28be0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 ent must be conv
28bf0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f erted.** to
28c00 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 UTF-8.</li>.**
28c10 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 </ul>.**.** Conv
28c20 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 ersions between
28c30 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 UTF-16be and UTF
28c40 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 -16le are always
28c50 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 done in place a
28c60 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 nd do.** not inv
28c70 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 alidate a prior
28c80 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 pointer, though
28c90 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f of course the co
28ca0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 ntent of the buf
28cb0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 fer.** that the
28cc0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f prior pointer po
28cd0 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 ints to will hav
28ce0 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e e been modified.
28cf0 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a Other kinds.**
28d00 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 of conversion a
28d10 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 re done in place
28d20 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 when it is poss
28d30 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 ible, but someti
28d40 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 mes they.** are
28d50 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 not possible and
28d60 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 in those cases
28d70 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 prior pointers a
28d80 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a re invalidated..
28d90 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 **.** The safest
28da0 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 and easiest to
28db0 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 remember policy
28dc0 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 is to invoke the
28dd0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 se routines.** i
28de0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c n one of the fol
28df0 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a lowing ways:.**.
28e00 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e ** <ul>.** <li>
28e10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
28e20 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 ext() followed b
28e30 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
28e40 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a _bytes()</li>.**
28e50 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f <li>sqlite3_co
28e60 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c lumn_blob() foll
28e70 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f owed by sqlite3_
28e80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f column_bytes()</
28e90 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 li>.** <li>sqli
28ea0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
28eb0 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6() followed by
28ec0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
28ed0 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a ytes16()</li>.**
28ee0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 </ul>.**.** In
28ef0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 other words, you
28f00 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c should call sql
28f10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
28f20 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 (),.** sqlite3_c
28f30 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 olumn_blob(), or
28f40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
28f50 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 text16() first t
28f60 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 o force the resu
28f70 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 lt.** into the d
28f80 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 esired format, t
28f90 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 hen invoke sqlit
28fa0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
28fb0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ) or.** sqlite3_
28fc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
28fd0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a to find the siz
28fe0 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e e of the result.
28ff0 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c Do not mix cal
29000 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 ls.** to sqlite3
29010 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f _column_text() o
29020 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
29030 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c _blob() with cal
29040 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ls to.** sqlite3
29050 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
29060 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 ), and do not mi
29070 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 x calls to sqlit
29080 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
29090 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 ().** with calls
290a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
290b0 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a mn_bytes()..**.*
290c0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 * The pointers r
290d0 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 eturned are vali
290e0 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 d until a type c
290f0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 onversion occurs
29100 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 as.** described
29110 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c above, or until
29120 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
29130 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
29140 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 set()] or.** [sq
29150 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
29160 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 ] is called. Th
29170 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 e memory space u
29180 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 sed to hold stri
29190 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 ngs.** and BLOBs
291a0 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 is freed automa
291b0 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e tically. Do <b>
291c0 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 not</b> pass the
291d0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e pointers return
291e0 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 ed.** [sqlite3_c
291f0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b olumn_blob()], [
29200 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
29210 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 ext()], etc. int
29220 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 o.** [sqlite3_fr
29230 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ee()]..**.** If
29240 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
29250 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 ion error occurs
29260 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c during the eval
29270 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a uation of any.**
29280 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
29290 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 es, a default va
292a0 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e lue is returned.
292b0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 The default va
292c0 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 lue.** is either
292d0 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 the integer 0,
292e0 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 the floating poi
292f0 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f nt number 0.0, o
29300 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e r a NULL.** poin
29310 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 ter. Subsequent
29320 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
29330 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 e3_errcode()] wi
29340 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 ll return.** [SQ
29350 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a LITE_NOMEM]..**.
29360 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
29370 2a 0a 2a 2a 20 7b 48 31 33 38 30 33 7d 20 54 68 *.** {H13803} Th
29380 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d e [sqlite3_colum
29390 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 n_blob(S,N)] int
293a0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 erface converts
293b0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
293c0 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 Nth column in th
293d0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 e current row of
293e0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
293f0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 for.**
29400 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
29410 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 atement] S into
29420 61 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e 20 a BLOB and then
29430 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 returns a.**
29440 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f pointer to
29450 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 the converted v
29460 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 alue..**.** {H13
29470 38 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 806} The [sqlite
29480 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 3_column_bytes(S
29490 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 ,N)] interface r
294a0 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 eturns the.**
294b0 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 number of
294c0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c bytes in the BL
294d0 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 OB or string (ex
294e0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a clusive of the.*
294f0 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 * zero
29500 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 terminator on th
29510 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 e string) that w
29520 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 as returned by t
29530 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d he.** m
29540 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 ost recent call
29550 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to [sqlite3_colu
29560 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 mn_blob(S,N)] or
29570 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
29580 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
29590 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b t(S,N)]..**.** {
295a0 48 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71 6c H13809} The [sql
295b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
295c0 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 s16(S,N)] interf
295d0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a ace returns the.
295e0 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 ** numb
295f0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
29600 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 he string (exclu
29610 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 sive of the.**
29620 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 zero ter
29630 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 minator on the s
29640 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 tring) that was
29650 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a returned by the.
29660 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 ** most
29670 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 recent call to
29680 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
29690 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a text16(S,N)]..**
296a0 0a 2a 2a 20 7b 48 31 33 38 31 32 7d 20 54 68 65 .** {H13812} The
296b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
296c0 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e _double(S,N)] in
296d0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 terface converts
296e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
296f0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 Nth column in t
29700 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f he current row o
29710 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
29720 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 for the.**
29730 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 [prepared s
29740 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f tatement] S into
29750 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e a floating poin
29760 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 t value and.**
29770 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 returns
29780 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 a copy of that v
29790 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 alue..**.** {H13
297a0 38 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 815} The [sqlite
297b0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 3_column_int(S,N
297c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e )] interface con
297d0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 verts the.**
297e0 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e Nth column
297f0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 in the current
29800 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c row of the resul
29810 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a t set for the.**
29820 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 [prepa
29830 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
29840 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 into a 64-bit s
29850 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e igned integer an
29860 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 d.** re
29870 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 turns the lower
29880 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 32 bits of that
29890 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b integer..**.** {
298a0 48 31 33 38 31 38 7d 20 54 68 65 20 5b 73 71 6c H13818} The [sql
298b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 ite3_column_int6
298c0 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 4(S,N)] interfac
298d0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a e converts the.*
298e0 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 * Nth c
298f0 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 olumn in the cur
29900 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 rent row of the
29910 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 result set for t
29920 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
29930 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
29940 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d nt] S into a 64-
29950 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
29960 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 er and.**
29970 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 returns a cop
29980 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 y of that intege
29990 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 31 r..**.** {H13821
299a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
299b0 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d olumn_text(S,N)]
299c0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 interface conve
299d0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 rts the.**
299e0 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 Nth column i
299f0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f n the current ro
29a00 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 w of the result
29a10 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 set for.**
29a20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 the [prepare
29a30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 d statement] S i
29a40 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 nto a zero-termi
29a50 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 nated UTF-8.**
29a60 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 string a
29a70 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 nd returns a poi
29a80 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 nter to that str
29a90 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 ing..**.** {H138
29aa0 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 24} The [sqlite3
29ab0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 _column_text16(S
29ac0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 ,N)] interface c
29ad0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 onverts the.**
29ae0 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 Nth colu
29af0 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e mn in the curren
29b00 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 t row of the res
29b10 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a ult set for the.
29b20 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 ** [pre
29b30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
29b40 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 S into a zero-t
29b50 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 erminated 2-byte
29b60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 .** ali
29b70 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 gned UTF-16 nati
29b80 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73 74 ve byte order st
29b90 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 ring and returns
29ba0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 .** a p
29bb0 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 ointer to that s
29bc0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 tring..**.** {H1
29bd0 33 38 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 3827} The [sqlit
29be0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 e3_column_type(S
29bf0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 ,N)] interface r
29c00 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 eturns.**
29c10 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 one of [SQLIT
29c20 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 E_NULL], [SQLITE
29c30 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 _INTEGER], [SQLI
29c40 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 TE_FLOAT],.**
29c50 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 [SQLITE_T
29c60 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 EXT], or [SQLITE
29c70 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 _BLOB] as approp
29c80 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 riate for.**
29c90 20 20 20 20 20 20 74 68 65 20 4e 74 68 20 63 6f the Nth co
29ca0 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 lumn in the curr
29cb0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 ent row of the r
29cc0 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a esult set for.**
29cd0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 the [p
29ce0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
29cf0 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 t] S..**.** {H13
29d00 38 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 830} The [sqlite
29d10 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 3_column_value(S
29d20 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 ,N)] interface r
29d30 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 eturns a.**
29d40 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 pointer to
29d50 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 an [unprotected
29d60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
29d70 62 6a 65 63 74 20 66 6f 72 20 74 68 65 0a 2a 2a bject for the.**
29d80 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f Nth co
29d90 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 lumn in the curr
29da0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 ent row of the r
29db0 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a esult set for.**
29dc0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 the [p
29dd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
29de0 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 t] S..*/.const v
29df0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
29e00 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 umn_blob(sqlite3
29e10 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
29e20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
29e30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 olumn_bytes(sqli
29e40 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
29e50 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 Col);.int sqlite
29e60 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
29e70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
29e80 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c int iCol);.doubl
29e90 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
29ea0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f _double(sqlite3_
29eb0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
29ec0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f ;.int sqlite3_co
29ed0 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 lumn_int(sqlite3
29ee0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
29ef0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 );.sqlite3_int64
29f00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
29f10 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 int64(sqlite3_st
29f20 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
29f30 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 const unsigned c
29f40 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
29f50 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 umn_text(sqlite3
29f60 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
29f70 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
29f80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
29f90 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d xt16(sqlite3_stm
29fa0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 t*, int iCol);.i
29fb0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
29fc0 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 n_type(sqlite3_s
29fd0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
29fe0 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a .sqlite3_value *
29ff0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
2a000 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d alue(sqlite3_stm
2a010 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a t*, int iCol);..
2a020 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2a030 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 Destroy A Prepar
2a040 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a ed Statement Obj
2a050 65 63 74 20 7b 48 31 33 33 30 30 7d 20 3c 53 37 ect {H13300} <S7
2a060 30 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0300><S30100>.**
2a070 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
2a080 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 finalize() funct
2a090 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f ion is called to
2a0a0 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 delete a [prepa
2a0b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
2a0c0 2a 2a 20 49 66 20 74 68 65 20 73 74 61 74 65 6d ** If the statem
2a0d0 65 6e 74 20 77 61 73 20 65 78 65 63 75 74 65 64 ent was executed
2a0e0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 successfully or
2a0f0 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 not executed at
2a100 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 all, then.** SQ
2a110 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 LITE_OK is retur
2a120 6e 65 64 2e 20 49 66 20 65 78 65 63 75 74 69 6f ned. If executio
2a130 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 n of the stateme
2a140 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 nt failed then a
2a150 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 n.** [error code
2a160 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 ] or [extended e
2a170 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
2a180 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 turned..**.** Th
2a190 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 is routine can b
2a1a0 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 e called at any
2a1b0 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 point during the
2a1c0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 execution of th
2a1d0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
2a1e0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 tatement]. If t
2a1f0 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 he virtual machi
2a200 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f ne has not.** co
2a210 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f mpleted executio
2a220 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 n when this rout
2a230 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 ine is called, t
2a240 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 hat is like.** e
2a250 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 ncountering an e
2a260 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 rror or an [sqli
2a270 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 te3_interrupt |
2a280 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 interrupt]..** I
2a290 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 ncomplete update
2a2a0 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 s may be rolled
2a2b0 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 back and transac
2a2c0 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a tions canceled,.
2a2d0 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 ** depending on
2a2e0 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 the circumstance
2a2f0 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 s, and the.** [e
2a300 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 rror code] retur
2a310 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c ned will be [SQL
2a320 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a ITE_ABORT]..**.*
2a330 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
2a340 0a 2a 2a 20 7b 48 31 31 33 30 32 7d 20 54 68 65 .** {H11302} The
2a350 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
2a360 7a 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 ze(S)] interface
2a370 20 64 65 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a destroys the.**
2a380 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 [prepa
2a390 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
2a3a0 20 61 6e 64 20 72 65 6c 65 61 73 65 73 20 61 6c and releases al
2a3b0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 l.** me
2a3c0 6d 6f 72 79 20 61 6e 64 20 66 69 6c 65 20 72 65 mory and file re
2a3d0 73 6f 75 72 63 65 73 20 68 65 6c 64 20 62 79 20 sources held by
2a3e0 74 68 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a that object..**.
2a3f0 2a 2a 20 7b 48 31 31 33 30 34 7d 20 49 66 20 74 ** {H11304} If t
2a400 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 he most recent c
2a410 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2a420 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 step(S)] for the
2a430 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
2a440 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2a450 5d 20 53 20 72 65 74 75 72 6e 65 64 20 61 6e 20 ] S returned an
2a460 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 error,.**
2a470 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 then [sqlite3
2a480 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65 _finalize(S)] re
2a490 74 75 72 6e 73 20 74 68 61 74 20 73 61 6d 65 20 turns that same
2a4a0 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 error..*/.int sq
2a4b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 lite3_finalize(s
2a4c0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
2a4d0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
2a4e0 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 3REF: Reset A Pr
2a4f0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
2a500 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 33 30 7d Object {H13330}
2a510 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S70300>.**.**
2a520 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 The sqlite3_rese
2a530 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 t() function is
2a540 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 called to reset
2a550 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
2a560 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 ement].** object
2a570 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 back to its ini
2a580 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 tial state, read
2a590 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 y to be re-execu
2a5a0 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 ted..** Any SQL
2a5b0 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 statement variab
2a5c0 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c les that had val
2a5d0 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 ues bound to the
2a5e0 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b m using.** the [
2a5f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
2a600 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 b | sqlite3_bind
2a610 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e _*() API] retain
2a620 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a their values..*
2a630 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 * Use [sqlite3_c
2a640 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d lear_bindings()]
2a650 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 to reset the bi
2a660 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ndings..**.** {H
2a670 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71 6c 69 11332} The [sqli
2a680 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e te3_reset(S)] in
2a690 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 terface resets t
2a6a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2a6b0 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 tement] S.**
2a6c0 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 74 68 back to th
2a6d0 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 e beginning of i
2a6e0 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a ts program..**.*
2a6f0 2a 20 7b 48 31 31 33 33 34 7d 20 49 66 20 74 68 * {H11334} If th
2a700 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
2a710 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
2a720 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a tep(S)] for the.
2a730 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 ** [pre
2a740 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2a750 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c S returned [SQL
2a760 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c ITE_ROW] or [SQL
2a770 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 ITE_DONE],.**
2a780 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71 or if [sq
2a790 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 lite3_step(S)] h
2a7a0 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 as never before
2a7b0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 been called on S
2a7c0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 ,.** th
2a7d0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 en [sqlite3_rese
2a7e0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 t(S)] returns [S
2a7f0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a QLITE_OK]..**.**
2a800 20 7b 48 31 31 33 33 36 7d 20 49 66 20 74 68 65 {H11336} If the
2a810 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c most recent cal
2a820 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
2a830 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a ep(S)] for the.*
2a840 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 * [prep
2a850 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2a860 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 S indicated an e
2a870 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 rror, then.**
2a880 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
2a890 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e reset(S)] return
2a8a0 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 s an appropriate
2a8b0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a [error code]..*
2a8c0 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54 68 *.** {H11338} Th
2a8d0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 e [sqlite3_reset
2a8e0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 (S)] interface d
2a8f0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 oes not change t
2a900 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 he values.**
2a910 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 of any [sq
2a920 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
2a930 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 bindings] on the
2a940 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2a950 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 ment] S..*/.int
2a960 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 sqlite3_reset(sq
2a970 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
2a980 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2a990 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 REF: Create Or R
2a9a0 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 edefine SQL Func
2a9b0 74 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c tions {H16100} <
2a9c0 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S20200>.** KEYWO
2a9d0 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 RDS: {function c
2a9e0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 reation routines
2a9f0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
2aa00 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
2aa10 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
2aa20 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
2aa30 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
2aa40 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
2aa50 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 s}.**.** These t
2aa60 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f wo functions (co
2aa70 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e llectively known
2aa80 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 as "function cr
2aa90 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 eation routines"
2aaa0 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f ).** are used to
2aab0 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f add SQL functio
2aac0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 ns or aggregates
2aad0 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 or to redefine
2aae0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 the behavior.**
2aaf0 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 of existing SQL
2ab00 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 functions or agg
2ab10 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e regates. The on
2ab20 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 ly difference be
2ab30 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f tween the.** two
2ab40 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63 is that the sec
2ab50 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 ond parameter, t
2ab60 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 he name of the (
2ab70 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e scalar) function
2ab80 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
2ab90 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 , is encoded in
2aba0 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 UTF-8 for sqlite
2abb0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2abc0 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a n() and UTF-16.*
2abd0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 * for sqlite3_cr
2abe0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
2abf0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 )..**.** The fir
2ac00 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
2ac10 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
2ac20 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 nnection] to whi
2ac30 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 ch the SQL.** fu
2ac40 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 nction is to be
2ac50 61 64 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e added. If a sin
2ac60 67 6c 65 20 70 72 6f 67 72 61 6d 20 75 73 65 73 gle program uses
2ac70 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 more than one d
2ac80 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
2ac90 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 ction internally
2aca0 2c 20 74 68 65 6e 20 53 51 4c 20 66 75 6e 63 74 , then SQL funct
2acb0 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 ions must be add
2acc0 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 ed individually
2acd0 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62 to.** each datab
2ace0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a ase connection..
2acf0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 **.** The second
2ad00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
2ad10 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 e name of the SQ
2ad20 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 L function to be
2ad30 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 created or.** r
2ad40 65 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20 6c edefined. The l
2ad50 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d ength of the nam
2ad60 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 e is limited to
2ad70 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 255 bytes, exclu
2ad80 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a sive of.** the z
2ad90 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ero-terminator.
2ada0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e Note that the n
2adb0 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 ame length limit
2adc0 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f is in bytes, no
2add0 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e t.** characters.
2ade0 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f Any attempt to
2adf0 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 create a functi
2ae00 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 on with a longer
2ae10 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 name.** will re
2ae20 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f sult in [SQLITE_
2ae30 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 ERROR] being ret
2ae40 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 urned..**.** The
2ae50 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
2ae60 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
2ae70 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 f arguments that
2ae80 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
2ae90 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 n or.** aggregat
2aea0 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 e takes. If this
2aeb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 parameter is ne
2aec0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 gative, then the
2aed0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 SQL function or
2aee0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 .** aggregate ma
2aef0 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 y take any numbe
2af00 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a r of arguments..
2af10 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 **.** The fourth
2af20 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 parameter, eTex
2af30 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 tRep, specifies
2af40 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f what.** [SQLITE_
2af50 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f UTF8 | text enco
2af60 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 ding] this SQL f
2af70 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 unction prefers
2af80 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d for.** its param
2af90 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 eters. Any SQL
2afa0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
2afb0 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 ntation should b
2afc0 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a e able to work.*
2afd0 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d * work with UTF-
2afe0 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 8, UTF-16le, or
2aff0 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 UTF-16be. But s
2b000 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ome implementati
2b010 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f ons may be.** mo
2b020 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 re efficient wit
2b030 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 h one encoding t
2b040 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 han another. It
2b050 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a is allowed to.*
2b060 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 * invoke sqlite3
2b070 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2b080 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 () or sqlite3_cr
2b090 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
2b0a0 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 ) multiple.** ti
2b0b0 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d mes with the sam
2b0c0 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 e function but w
2b0d0 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 ith different va
2b0e0 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 lues of eTextRep
2b0f0 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 ..** When multip
2b100 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
2b110 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 ns of the same f
2b120 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 unction are avai
2b130 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a lable, SQLite.**
2b140 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f will pick the o
2b150 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 ne that involves
2b160 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e the least amoun
2b170 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 t of data conver
2b180 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 sion..** If ther
2b190 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 e is only a sing
2b1a0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
2b1b0 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 n which does not
2b1c0 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a care what text.
2b1d0 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 ** encoding is u
2b1e0 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f sed, then the fo
2b1f0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 urth argument sh
2b200 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f ould be [SQLITE_
2b210 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ANY]..**.** The
2b220 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 fifth parameter
2b230 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 is an arbitrary
2b240 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d pointer. The im
2b250 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
2b260 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 the.** function
2b270 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 can gain access
2b280 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 to this pointer
2b290 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 using [sqlite3_u
2b2a0 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a ser_data()]..**.
2b2b0 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 ** The seventh,
2b2c0 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 eighth and ninth
2b2d0 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 parameters, xFu
2b2e0 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 nc, xStep and xF
2b2f0 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 inal, are.** poi
2b300 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 nters to C-langu
2b310 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 age functions th
2b320 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 at implement the
2b330 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 SQL function or
2b340 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 41 .** aggregate. A
2b350 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 scalar SQL func
2b360 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e tion requires an
2b370 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
2b380 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 of the xFunc.**
2b390 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e callback only, N
2b3a0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f ULL pointers sho
2b3b0 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73 uld be passed as
2b3c0 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 the xStep and x
2b3d0 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 Final.** paramet
2b3e0 65 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 ers. An aggregat
2b3f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 e SQL function r
2b400 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 equires an imple
2b410 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 mentation of xSt
2b420 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c ep.** and xFinal
2b430 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 and NULL should
2b440 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 be passed for x
2b450 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 Func. To delete
2b460 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 an existing.** S
2b470 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 QL function or a
2b480 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e ggregate, pass N
2b490 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 ULL for all thre
2b4a0 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 e function callb
2b4b0 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 acks..**.** It i
2b4c0 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 s permitted to r
2b4d0 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 egister multiple
2b4e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
2b4f0 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 of the same.**
2b500 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 functions with t
2b510 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 he same name but
2b520 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 with either dif
2b530 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f fering numbers o
2b540 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f f.** arguments o
2b550 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 r differing pref
2b560 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 erred text encod
2b570 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69 ings. SQLite wi
2b580 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d ll use.** the im
2b590 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 plementation mos
2b5a0 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 t closely matche
2b5b0 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 s the way in whi
2b5c0 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 ch the.** SQL fu
2b5d0 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a nction is used..
2b5e0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
2b5f0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 33 7d :.**.** {H16103}
2b600 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 The [sqlite3_cr
2b610 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
2b620 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 68 )] interface beh
2b630 61 76 65 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 aves exactly.**
2b640 20 20 20 20 20 20 20 20 20 6c 69 6b 65 20 5b 73 like [s
2b650 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2b660 6e 63 74 69 6f 6e 28 29 5d 20 69 6e 20 65 76 65 nction()] in eve
2b670 72 79 20 77 61 79 20 65 78 63 65 70 74 20 74 68 ry way except th
2b680 61 74 20 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 at it.**
2b690 20 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 interprets the
2b6a0 20 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 20 61 zFunctionName a
2b6b0 72 67 75 6d 65 6e 74 20 61 73 20 7a 65 72 6f 2d rgument as zero-
2b6c0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 terminated UTF-1
2b6d0 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6.** na
2b6e0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
2b6f0 69 6e 73 74 65 61 64 20 6f 66 20 61 73 20 7a 65 instead of as ze
2b700 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
2b710 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 F-8..**.** {H161
2b720 30 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 06} A successful
2b730 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a invocation of.*
2b740 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b * the [
2b750 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2b760 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c unction(D,X,N,E,
2b770 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 ...)] interface
2b780 72 65 67 69 73 74 65 72 73 0a 2a 2a 20 20 20 20 registers.**
2b790 20 20 20 20 20 20 6f 72 20 72 65 70 6c 61 63 65 or replace
2b7a0 73 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 s callback funct
2b7b0 69 6f 6e 73 20 69 6e 20 74 68 65 20 5b 64 61 74 ions in the [dat
2b7c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2b7d0 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ] D.**
2b7e0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e used to implemen
2b7f0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 t the SQL functi
2b800 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 on named X with
2b810 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 N parameters.**
2b820 20 20 20 20 20 20 20 20 20 61 6e 64 20 68 61 76 and hav
2b830 69 6e 67 20 61 20 70 72 65 66 65 72 72 65 64 20 ing a preferred
2b840 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 text encoding of
2b850 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 E..**.** {H1610
2b860 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 9} A successful
2b870 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
2b880 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2b890 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c (D,X,N,E,P,F,S,L
2b8a0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 )].** r
2b8b0 65 70 6c 61 63 65 73 20 74 68 65 20 50 2c 20 46 eplaces the P, F
2b8c0 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65 , S, and L value
2b8d0 73 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72 s from any prior
2b8e0 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20 calls with.**
2b8f0 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 the same
2b900 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20 D, X, N, and E
2b910 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 values..**.** {H
2b920 31 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 16112} The [sqli
2b930 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2b940 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e ion(D,X,...)] in
2b950 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 terface fails wi
2b960 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 th.** a
2b970 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 return code of
2b980 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
2b990 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 f the SQL functi
2b9a0 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20 on name X is.**
2b9b0 20 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72 20 longer
2b9c0 74 68 61 6e 20 32 35 35 20 62 79 74 65 73 20 65 than 255 bytes e
2b9d0 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 xclusive of the
2b9e0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
2b9f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 38 7d 20 .**.** {H16118}
2ba00 45 69 74 68 65 72 20 46 20 6d 75 73 74 20 62 65 Either F must be
2ba10 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 NULL and S and
2ba20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f L are non-NULL o
2ba30 72 20 65 6c 73 65 20 46 0a 2a 2a 20 20 20 20 20 r else F.**
2ba40 20 20 20 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c is non-NULL
2ba50 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65 and S and L are
2ba60 20 4e 55 4c 4c 2c 20 6f 74 68 65 72 77 69 73 65 NULL, otherwise
2ba70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
2ba80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2ba90 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c ction(D,X,N,E,P,
2baa0 46 2c 53 2c 4c 29 5d 20 72 65 74 75 72 6e 73 20 F,S,L)] returns
2bab0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a [SQLITE_ERROR]..
2bac0 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 31 7d 20 54 **.** {H16121} T
2bad0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
2bae0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e te_function(D,..
2baf0 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 .)] interface fa
2bb00 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 ils with an.**
2bb10 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f error co
2bb20 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55 de of [SQLITE_BU
2bb30 53 59 5d 20 69 66 20 74 68 65 72 65 20 65 78 69 SY] if there exi
2bb40 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 st [prepared sta
2bb50 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 tements].**
2bb60 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 64 20 associated
2bb70 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 with the [databa
2bb80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
2bb90 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 34 7d ..**.** {H16124}
2bba0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 The [sqlite3_cr
2bbb0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c eate_function(D,
2bbc0 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 X,N,...)] interf
2bbd0 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 61 ace fails with a
2bbe0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 n.** er
2bbf0 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c ror code of [SQL
2bc00 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70 61 ITE_ERROR] if pa
2bc10 72 61 6d 65 74 65 72 20 4e 20 28 73 70 65 63 69 rameter N (speci
2bc20 66 79 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 72 fying the number
2bc30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 .** of
2bc40 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 arguments to the
2bc50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 62 65 SQL function be
2bc60 69 6e 67 20 72 65 67 69 73 74 65 72 65 64 29 20 ing registered)
2bc70 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 is less.**
2bc80 20 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 than -1 or g
2bc90 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 2e reater than 127.
2bca0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 37 7d 20 .**.** {H16127}
2bcb0 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 When N is non-ne
2bcc0 67 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71 6c gative, the [sql
2bcd0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
2bce0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d tion(D,X,N,...)]
2bcf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 .** int
2bd00 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61 erface causes ca
2bd10 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e llbacks to be in
2bd20 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 voked for the SQ
2bd30 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 L function.**
2bd40 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 named X w
2bd50 68 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f hen the number o
2bd60 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 f arguments to t
2bd70 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
2bd80 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 is.** e
2bd90 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 xactly N..**.**
2bda0 7b 48 31 36 31 33 30 7d 20 57 68 65 6e 20 4e 20 {H16130} When N
2bdb0 69 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69 is -1, the [sqli
2bdc0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2bdd0 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a ion(D,X,N,...)].
2bde0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 ** inte
2bdf0 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c rface causes cal
2be00 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 lbacks to be inv
2be10 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c oked for the SQL
2be20 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 function.**
2be30 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 69 named X wi
2be40 74 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 th any number of
2be50 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a arguments..**.*
2be60 2a 20 7b 48 31 36 31 33 33 7d 20 57 68 65 6e 20 * {H16133} When
2be70 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
2be80 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2be90 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a n(D,X,N,...)].**
2bea0 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66 specif
2beb0 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 y multiple imple
2bec0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 mentations of th
2bed0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 e same function
2bee0 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e X.** an
2bef0 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c 65 d when one imple
2bf00 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e 3e mentation has N>
2bf10 3d 30 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 =0 and the other
2bf20 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20 has N=(-1).**
2bf30 20 20 20 20 20 20 20 20 74 68 65 20 69 6d 70 6c the impl
2bf40 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 ementation with
2bf50 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73 20 a non-zero N is
2bf60 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a preferred..**.**
2bf70 20 7b 48 31 36 31 33 36 7d 20 57 68 65 6e 20 63 {H16136} When c
2bf80 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
2bf90 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2bfa0 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a (D,X,N,E,...)].*
2bfb0 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69 * speci
2bfc0 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c fy multiple impl
2bfd0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 ementations of t
2bfe0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e he same function
2bff0 20 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 X with.**
2c000 20 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75 6d the same num
2c010 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 ber of arguments
2c020 20 4e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 N but with diff
2c030 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 erent.**
2c040 20 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74 encodings E, t
2c050 68 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e hen the implemen
2c060 74 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20 6d tation where E m
2c070 61 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20 20 atches the.**
2c080 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20 database
2c090 65 6e 63 6f 64 69 6e 67 20 69 73 20 70 72 65 66 encoding is pref
2c0a0 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 erred..**.** {H1
2c0b0 36 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67 67 6139} For an agg
2c0c0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 regate SQL funct
2c0d0 69 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69 6e ion created usin
2c0e0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 g.** [s
2c0f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2c100 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 nction(D,X,N,E,P
2c110 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e ,0,S,L)] the fin
2c120 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 alizer.**
2c130 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20 77 69 function L wi
2c140 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 69 6e 76 ll always be inv
2c150 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 oked exactly onc
2c160 65 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 e if the.**
2c170 20 20 20 20 20 73 74 65 70 20 66 75 6e 63 74 69 step functi
2c180 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65 64 20 6f on S is called o
2c190 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ne or more times
2c1a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 34 32 7d ..**.** {H16142}
2c1b0 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 When SQLite inv
2c1c0 6f 6b 65 73 20 65 69 74 68 65 72 20 74 68 65 20 okes either the
2c1d0 78 46 75 6e 63 20 6f 72 20 78 53 74 65 70 20 66 xFunc or xStep f
2c1e0 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 unction of.**
2c1f0 20 20 20 20 20 20 20 61 6e 20 61 70 70 6c 69 63 an applic
2c200 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
2c210 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 L function or ag
2c220 67 72 65 67 61 74 65 20 63 72 65 61 74 65 64 0a gregate created.
2c230 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b ** by [
2c240 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2c250 75 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 unction()] or [s
2c260 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2c270 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 nction16()],.**
2c280 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 then th
2c290 65 20 61 72 72 61 79 20 6f 66 20 5b 73 71 6c 69 e array of [sqli
2c2a0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
2c2b0 74 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 ts passed as the
2c2c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 69 .** thi
2c2d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 rd parameter are
2c2e0 20 61 6c 77 61 79 73 20 5b 70 72 6f 74 65 63 74 always [protect
2c2f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
2c300 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e ] objects..*/.in
2c310 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
2c320 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c _function(. sql
2c330 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 ite3 *db,. cons
2c340 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f t char *zFunctio
2c350 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
2c360 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
2c370 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c p,. void *pApp,
2c380 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
2c390 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
2c3a0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
2c3b0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
2c3c0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
2c3d0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
2c3e0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
2c3f0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
2c400 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2c410 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ).);.int sqlite3
2c420 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2c430 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 16(. sqlite3 *d
2c440 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 b,. const void
2c450 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a *zFunctionName,.
2c460 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e int nArg,. in
2c470 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f t eTextRep,. vo
2c480 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 id *pApp,. void
2c490 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 (*xFunc)(sqlite
2c4a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
2c4b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
2c4c0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 . void (*xStep)
2c4d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
2c4e0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
2c4f0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
2c500 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 *xFinal)(sqlite3
2c510 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f _context*).);../
2c520 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
2c530 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48 ext Encodings {H
2c540 31 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e 20 10267} <S50200>
2c550 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <H16100>.**.** T
2c560 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 hese constant de
2c570 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 fine integer cod
2c580 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e es that represen
2c590 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a t the various.**
2c5a0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 text encodings
2c5b0 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c supported by SQL
2c5c0 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ite..*/.#define
2c5d0 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 SQLITE_UTF8
2c5e0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
2c5f0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 SQLITE_UTF16LE
2c600 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
2c610 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 SQLITE_UTF16BE
2c620 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 3.#define
2c630 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 SQLITE_UTF16
2c640 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 4 /* Us
2c650 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
2c660 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 der */.#define S
2c670 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 QLITE_ANY
2c680 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 5 /* sql
2c690 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
2c6a0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 tion only */.#de
2c6b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
2c6c0 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 6_ALIGNED 8
2c6d0 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 /* sqlite3_creat
2c6e0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 e_collation only
2c6f0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
2c700 52 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75 REF: Obsolete Fu
2c710 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 nctions.**.** Th
2c720 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 ese functions ar
2c730 65 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 e all now obsole
2c740 74 65 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f te. In order to
2c750 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 maintain.** bac
2c760 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
2c770 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 lity with older
2c780 63 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75 code, we continu
2c790 65 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20 e to support.**
2c7a0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e these functions.
2c7b0 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 64 However, new d
2c7c0 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 evelopment proje
2c7d0 63 74 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 cts should avoid
2c7e0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 .** the use of t
2c7f0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 hese functions.
2c800 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 To help encoura
2c810 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f ge people to avo
2c820 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 id.** using thes
2c830 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 e functions, we
2c840 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f are not going to
2c850 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74 tell you want t
2c860 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 hey do..*/.int s
2c870 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
2c880 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 _count(sqlite3_c
2c890 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71 ontext*);.int sq
2c8a0 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 lite3_expired(sq
2c8b0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e lite3_stmt*);.in
2c8c0 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 t sqlite3_transf
2c8d0 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 er_bindings(sqli
2c8e0 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 te3_stmt*, sqlit
2c8f0 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 e3_stmt*);.int s
2c900 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 qlite3_global_re
2c910 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76 6f 69 cover(void);.voi
2c920 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 d sqlite3_thread
2c930 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a _cleanup(void);.
2c940 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f int sqlite3_memo
2c950 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 ry_alarm(void(*)
2c960 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 (void*,sqlite3_i
2c970 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c nt64,int),void*,
2c980 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
2c990 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2c9a0 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 Obtaining SQL F
2c9b0 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 unction Paramete
2c9c0 72 20 56 61 6c 75 65 73 20 7b 48 31 35 31 30 30 r Values {H15100
2c9d0 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a } <S20200>.**.**
2c9e0 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 The C-language
2c9f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
2ca00 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 f SQL functions
2ca10 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 and aggregates u
2ca20 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 ses.** this set
2ca30 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 of interface rou
2ca40 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 tines to access
2ca50 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 the parameter va
2ca60 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 lues on.** the f
2ca70 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 unction or aggre
2ca80 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 gate..**.** The
2ca90 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 xFunc (for scala
2caa0 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 r functions) or
2cab0 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 xStep (for aggre
2cac0 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 gates) parameter
2cad0 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 s.** to [sqlite3
2cae0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2caf0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
2cb00 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2cb10 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 16()].** define
2cb20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 callbacks that i
2cb30 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c mplement the SQL
2cb40 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 functions and a
2cb50 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 ggregates..** Th
2cb60 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
2cb70 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 to these callbac
2cb80 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f ks is an array o
2cb90 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a f pointers to.**
2cba0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
2cbb0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
2cbc0 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e ts. There is on
2cbd0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
2cbe0 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 ] object for.**
2cbf0 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 each parameter t
2cc00 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 o the SQL functi
2cc10 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 on. These routi
2cc20 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a nes are used to.
2cc30 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 ** extract value
2cc40 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 s from the [sqli
2cc50 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
2cc60 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ts..**.** These
2cc70 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e routines work on
2cc80 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 ly with [protect
2cc90 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
2cca0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e ] objects..** An
2ccb0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 y attempt to use
2ccc0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
2ccd0 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 on an [unprotect
2cce0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
2ccf0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 ].** object resu
2cd00 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 lts in undefined
2cd10 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a behavior..**.**
2cd20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
2cd30 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 work just like t
2cd40 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
2cd50 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 [column access
2cd60 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 functions].** ex
2cd70 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 cept that these
2cd80 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 routines take a
2cd90 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 single [protect
2cda0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
2cdb0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e ] object.** poin
2cdc0 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 ter instead of a
2cdd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d [sqlite3_stmt*]
2cde0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 pointer and an
2cdf0 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e integer column n
2ce00 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 umber..**.** The
2ce10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
2ce20 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 ext16() interfac
2ce30 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 e extracts a UTF
2ce40 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e -16 string.** in
2ce50 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
2ce60 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f -order of the ho
2ce70 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 st machine. The
2ce80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
2ce90 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 e_text16be() and
2cea0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
2ceb0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 ext16le() interf
2cec0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 aces.** extract
2ced0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 UTF-16 strings a
2cee0 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 s big-endian and
2cef0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 little-endian r
2cf00 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a espectively..**.
2cf10 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 ** The sqlite3_v
2cf20 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 alue_numeric_typ
2cf30 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 e() interface at
2cf40 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a tempts to apply.
2cf50 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e ** numeric affin
2cf60 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 ity to the value
2cf70 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 . This means th
2cf80 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 at an attempt is
2cf90 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 .** made to conv
2cfa0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f ert the value to
2cfb0 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 an integer or f
2cfc0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 loating point.
2cfd0 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e If.** such a con
2cfe0 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 version is possi
2cff0 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 ble without loss
2d000 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 of information
2d010 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 (in other.** wor
2d020 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 ds, if the value
2d030 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 is a string tha
2d040 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e t looks like a n
2d050 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 umber).** then t
2d060 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 he conversion is
2d070 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 performed. Oth
2d080 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 erwise no conver
2d090 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 sion occurs..**
2d0a0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 The [SQLITE_INTE
2d0b0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 GER | datatype]
2d0c0 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e after conversion
2d0d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
2d0e0 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 .** Please pay p
2d0f0 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 articular attent
2d100 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 ion to the fact
2d110 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 that the pointer
2d120 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f returned.** fro
2d130 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 m [sqlite3_value
2d140 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 _blob()], [sqlit
2d150 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d e3_value_text()]
2d160 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 , or.** [sqlite3
2d170 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d _value_text16()]
2d180 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 can be invalida
2d190 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 ted by a subsequ
2d1a0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b ent call to.** [
2d1b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
2d1c0 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 tes()], [sqlite3
2d1d0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 _value_bytes16()
2d1e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
2d1f0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 e_text()],.** or
2d200 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2d210 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a text16()]..**.**
2d220 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
2d230 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
2d240 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
2d250 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 ead as.** the SQ
2d260 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 L function that
2d270 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 supplied the [sq
2d280 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 lite3_value*] pa
2d290 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 rameters..**.**
2d2a0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
2d2b0 2a 20 7b 48 31 35 31 30 33 7d 20 54 68 65 20 5b * {H15103} The [
2d2c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c sqlite3_value_bl
2d2d0 6f 62 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 ob(V)] interface
2d2e0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a converts the.**
2d2f0 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 [prote
2d300 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2d310 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 ue] object V int
2d320 6f 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 o a BLOB and the
2d330 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 n.** re
2d340 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
2d350 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 to the converted
2d360 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 value..**.** {H
2d370 31 35 31 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 15106} The [sqli
2d380 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
2d390 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 V)] interface re
2d3a0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 turns the.**
2d3b0 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 number of
2d3c0 62 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f bytes in the BLO
2d3d0 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 B or string (exc
2d3e0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a lusive of the.**
2d3f0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 zero t
2d400 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 erminator on the
2d410 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 string) that wa
2d420 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
2d430 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f e.** mo
2d440 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
2d450 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 o [sqlite3_value
2d460 5f 62 6c 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a 20 _blob(V)] or.**
2d470 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
2d480 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 3_value_text(V)]
2d490 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 39 7d ..**.** {H15109}
2d4a0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 The [sqlite3_va
2d4b0 6c 75 65 5f 62 79 74 65 73 31 36 28 56 29 5d 20 lue_bytes16(V)]
2d4c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2d4d0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
2d4e0 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 number of byte
2d4f0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 s in the string
2d500 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 (exclusive of th
2d510 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 e.** ze
2d520 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e ro terminator on
2d530 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 the string) tha
2d540 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 t was returned b
2d550 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 y the.**
2d560 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 most recent ca
2d570 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 ll to [sqlite3_v
2d580 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 2c alue_text16(V)],
2d590 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
2d5a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
2d5b0 31 36 62 65 28 56 29 5d 2c 20 6f 72 20 5b 73 71 16be(V)], or [sq
2d5c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
2d5d0 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 16le(V)]..**.**
2d5e0 7b 48 31 35 31 31 32 7d 20 54 68 65 20 5b 73 71 {H15112} The [sq
2d5f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 lite3_value_doub
2d600 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 le(V)] interface
2d610 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a converts the.**
2d620 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 [prote
2d630 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2d640 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 ue] object V int
2d650 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 o a floating poi
2d660 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 nt value and.**
2d670 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 returns
2d680 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 a copy of that
2d690 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 value..**.** {H1
2d6a0 35 31 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 5115} The [sqlit
2d6b0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 56 29 5d e3_value_int(V)]
2d6c0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 interface conve
2d6d0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 rts the.**
2d6e0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 [protected s
2d6f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
2d700 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34 ject V into a 64
2d710 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
2d720 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 ger and.**
2d730 20 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20 returns the
2d740 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66 lower 32 bits of
2d750 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a that integer..*
2d760 2a 0a 2a 2a 20 7b 48 31 35 31 31 38 7d 20 54 68 *.** {H15118} Th
2d770 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
2d780 5f 69 6e 74 36 34 28 56 29 5d 20 69 6e 74 65 72 _int64(V)] inter
2d790 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 face converts th
2d7a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 e.** [p
2d7b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2d7c0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 _value] object V
2d7d0 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 into a 64-bit s
2d7e0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e igned integer an
2d7f0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 d.** re
2d800 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 turns a copy of
2d810 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a that integer..**
2d820 0a 2a 2a 20 7b 48 31 35 31 32 31 7d 20 54 68 65 .** {H15121} The
2d830 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2d840 74 65 78 74 28 56 29 5d 20 69 6e 74 65 72 66 61 text(V)] interfa
2d850 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a ce converts the.
2d860 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f ** [pro
2d870 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2d880 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 alue] object V i
2d890 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 nto a zero-termi
2d8a0 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 nated UTF-8.**
2d8b0 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 string a
2d8c0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 nd returns a poi
2d8d0 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 nter to that str
2d8e0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 ing..**.** {H151
2d8f0 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 24} The [sqlite3
2d900 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29 _value_text16(V)
2d910 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 ] interface conv
2d920 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 erts the.**
2d930 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 [protected
2d940 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
2d950 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a bject V into a z
2d960 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 ero-terminated 2
2d970 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 -byte.**
2d980 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 aligned UTF-16
2d990 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
2d9a0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 er.** s
2d9b0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
2d9c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
2d9d0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a hat string..**.*
2d9e0 2a 20 7b 48 31 35 31 32 37 7d 20 54 68 65 20 5b * {H15127} The [
2d9f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
2da00 78 74 31 36 62 65 28 56 29 5d 20 69 6e 74 65 72 xt16be(V)] inter
2da10 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 face converts th
2da20 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 e.** [p
2da30 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2da40 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 _value] object V
2da50 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 into a zero-ter
2da60 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a minated 2-byte.*
2da70 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e * align
2da80 65 64 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e ed UTF-16 big-en
2da90 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 dian.**
2daa0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 string and retu
2dab0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
2dac0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a that string..**
2dad0 0a 2a 2a 20 7b 48 31 35 31 33 30 7d 20 54 68 65 .** {H15130} The
2dae0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2daf0 74 65 78 74 31 36 6c 65 28 56 29 5d 20 69 6e 74 text16le(V)] int
2db00 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 erface converts
2db10 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
2db20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
2db30 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
2db40 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 V into a zero-t
2db50 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 erminated 2-byte
2db60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 .** ali
2db70 67 6e 65 64 20 55 54 46 2d 31 36 20 6c 69 74 74 gned UTF-16 litt
2db80 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 le-endian.**
2db90 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 string and
2dba0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
2dbb0 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e er to that strin
2dbc0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 33 g..**.** {H15133
2dbd0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 } The [sqlite3_v
2dbe0 61 6c 75 65 5f 74 79 70 65 28 56 29 5d 20 69 6e alue_type(V)] in
2dbf0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a terface returns.
2dc00 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 ** one
2dc10 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d of [SQLITE_NULL]
2dc20 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 , [SQLITE_INTEGE
2dc30 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 R], [SQLITE_FLOA
2dc40 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 T],.**
2dc50 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f [SQLITE_TEXT], o
2dc60 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 r [SQLITE_BLOB]
2dc70 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 as appropriate f
2dc80 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 or.** t
2dc90 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
2dca0 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a e] object V..**.
2dcb0 2a 2a 20 7b 48 31 35 31 33 36 7d 20 54 68 65 20 ** {H15136} The
2dcc0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e [sqlite3_value_n
2dcd0 75 6d 65 72 69 63 5f 74 79 70 65 28 56 29 5d 20 umeric_type(V)]
2dce0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 interface conver
2dcf0 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ts.** t
2dd00 68 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 he [protected sq
2dd10 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2dd20 65 63 74 20 56 20 69 6e 74 6f 20 65 69 74 68 65 ect V into eithe
2dd30 72 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 0a r an integer or.
2dd40 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 6c ** a fl
2dd50 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
2dd60 75 65 20 69 66 20 69 74 20 63 61 6e 20 64 6f 20 ue if it can do
2dd70 73 6f 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 so without loss
2dd80 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 of.** i
2dd90 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e 64 20 nformation, and
2dda0 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f 66 20 5b returns one of [
2ddb0 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a SQLITE_NULL],.**
2ddc0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 [SQLIT
2ddd0 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c E_INTEGER], [SQL
2dde0 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c ITE_FLOAT], [SQL
2ddf0 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a ITE_TEXT], or.**
2de00 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 [SQLIT
2de10 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f E_BLOB] as appro
2de20 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 0a 2a priate for the.*
2de30 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 * [prot
2de40 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2de50 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 61 66 lue] object V af
2de60 74 65 72 20 74 68 65 20 63 6f 6e 76 65 72 73 69 ter the conversi
2de70 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63 on attempt..*/.c
2de80 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
2de90 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 e3_value_blob(sq
2dea0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
2deb0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
2dec0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 _bytes(sqlite3_v
2ded0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 alue*);.int sqli
2dee0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 te3_value_bytes1
2def0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 6(sqlite3_value*
2df00 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 );.double sqlite
2df10 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 3_value_double(s
2df20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
2df30 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
2df40 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 e_int(sqlite3_va
2df50 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 lue*);.sqlite3_i
2df60 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c nt64 sqlite3_val
2df70 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 ue_int64(sqlite3
2df80 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 _value*);.const
2df90 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 unsigned char *s
2dfa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
2dfb0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t(sqlite3_value*
2dfc0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
2dfd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
2dfe0 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 t16(sqlite3_valu
2dff0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 e*);.const void
2e000 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
2e010 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f ext16le(sqlite3_
2e020 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 value*);.const v
2e030 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c oid *sqlite3_val
2e040 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 ue_text16be(sqli
2e050 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
2e060 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
2e070 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ype(sqlite3_valu
2e080 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
2e090 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 _value_numeric_t
2e0a0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ype(sqlite3_valu
2e0b0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 e*);../*.** CAPI
2e0c0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 3REF: Obtain Agg
2e0d0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 regate Function
2e0e0 43 6f 6e 74 65 78 74 20 7b 48 31 36 32 31 30 7d Context {H16210}
2e0f0 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20200>.**.**
2e100 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 The implementati
2e110 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 on of aggregate
2e120 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 SQL functions us
2e130 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 e this routine t
2e140 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 o allocate.** a
2e150 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 74 structure for st
2e160 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 oring their stat
2e170 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 e..**.** The fir
2e180 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 st time the sqli
2e190 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
2e1a0 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20 ntext() routine
2e1b0 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a is called for a.
2e1c0 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 ** particular ag
2e1d0 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20 gregate, SQLite
2e1e0 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73 allocates nBytes
2e1f0 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f of memory, zero
2e200 65 73 20 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d es out that.** m
2e210 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 emory, and retur
2e220 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
2e230 69 74 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e it. On second an
2e240 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c d subsequent cal
2e250 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ls to.** sqlite3
2e260 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
2e270 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d xt() for the sam
2e280 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 e aggregate func
2e290 74 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 tion index,.** t
2e2a0 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 he same buffer i
2e2b0 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65 20 s returned. The
2e2c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
2e2d0 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 f the aggregate
2e2e0 63 61 6e 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 can use.** the r
2e2f0 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 eturned buffer t
2e300 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 o accumulate dat
2e310 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 a..**.** SQLite
2e320 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 automatically fr
2e330 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 ees the allocate
2e340 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 74 68 d buffer when th
2e350 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 e aggregate.** q
2e360 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a uery concludes..
2e370 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
2e380 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 parameter should
2e390 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 be a copy of th
2e3a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f e.** [sqlite3_co
2e3b0 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 ntext | SQL func
2e3c0 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 tion context] th
2e3d0 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 at is the first
2e3e0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 parameter.** to
2e3f0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 the callback rou
2e400 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d tine that implem
2e410 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 ents the aggrega
2e420 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a te function..**.
2e430 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
2e440 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
2e450 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
2e460 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 ead in which.**
2e470 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 the aggregate SQ
2e480 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 L function is ru
2e490 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 nning..**.** INV
2e4a0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
2e4b0 48 31 36 32 31 31 7d 20 54 68 65 20 66 69 72 73 H16211} The firs
2e4c0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 t invocation of
2e4d0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 [sqlite3_aggrega
2e4e0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d te_context(C,N)]
2e4f0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 for.**
2e500 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e a particular in
2e510 73 74 61 6e 63 65 20 6f 66 20 61 6e 20 61 67 67 stance of an agg
2e520 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 regate function
2e530 28 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 (for a particula
2e540 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f r.** co
2e550 6e 74 65 78 74 20 43 29 20 63 61 75 73 65 73 20 ntext C) causes
2e560 53 51 4c 69 74 65 20 74 6f 20 61 6c 6c 6f 63 61 SQLite to alloca
2e570 74 65 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 te N bytes of me
2e580 6d 6f 72 79 2c 0a 2a 2a 20 20 20 20 20 20 20 20 mory,.**
2e590 20 20 7a 65 72 6f 20 74 68 61 74 20 6d 65 6d 6f zero that memo
2e5a0 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 61 ry, and return a
2e5b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
2e5c0 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79 allocated memory
2e5d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 33 7d ..**.** {H16213}
2e5e0 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c If a memory all
2e5f0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 ocation error oc
2e600 63 75 72 73 20 64 75 72 69 6e 67 0a 2a 2a 20 20 curs during.**
2e610 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
2e620 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
2e630 78 74 28 43 2c 4e 29 5d 20 74 68 65 6e 20 74 68 xt(C,N)] then th
2e640 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 e function retur
2e650 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 ns 0..**.** {H16
2e660 32 31 35 7d 20 53 65 63 6f 6e 64 20 61 6e 64 20 215} Second and
2e670 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 subsequent invoc
2e680 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20 20 20 20 ations of.**
2e690 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 [sqlite3_a
2e6a0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
2e6b0 28 43 2c 4e 29 5d 20 66 6f 72 20 74 68 65 20 73 (C,N)] for the s
2e6c0 61 6d 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e ame context poin
2e6d0 74 65 72 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 ter C.**
2e6e0 20 20 69 67 6e 6f 72 65 20 74 68 65 20 4e 20 70 ignore the N p
2e6f0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 arameter and ret
2e700 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f urn a pointer to
2e710 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 the same.**
2e720 20 20 20 20 20 20 62 6c 6f 63 6b 20 6f 66 20 6d block of m
2e730 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 emory returned b
2e740 79 20 74 68 65 20 66 69 72 73 74 20 69 6e 76 6f y the first invo
2e750 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 cation..**.** {H
2e760 31 36 32 31 37 7d 20 54 68 65 20 6d 65 6d 6f 72 16217} The memor
2e770 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 5b y allocated by [
2e780 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
2e790 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 e_context(C,N)]
2e7a0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 is.** a
2e7b0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 utomatically fre
2e7c0 65 64 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 63 ed on the next c
2e7d0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2e7e0 72 65 73 65 74 28 29 5d 0a 2a 2a 20 20 20 20 20 reset()].**
2e7f0 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 or [sqlite3
2e800 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 66 6f 72 _finalize()] for
2e810 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
2e820 74 61 74 65 6d 65 6e 74 5d 20 63 6f 6e 74 61 69 tatement] contai
2e830 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 ning.**
2e840 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 the aggregate f
2e850 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 unction associat
2e860 65 64 20 77 69 74 68 20 63 6f 6e 74 65 78 74 20 ed with context
2e870 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 C..*/.void *sqli
2e880 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
2e890 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f ntext(sqlite3_co
2e8a0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 ntext*, int nByt
2e8b0 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 es);../*.** CAPI
2e8c0 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 3REF: User Data
2e8d0 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 For Functions {H
2e8e0 31 36 32 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a 16240} <S20200>.
2e8f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
2e900 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 3_user_data() in
2e910 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2e920 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 a copy of.** the
2e930 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 pointer that wa
2e940 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 s the pUserData
2e950 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 parameter (the 5
2e960 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a th parameter).**
2e970 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
2e980 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2e990 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 ()].** and [sqli
2e9a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2e9b0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 ion16()] routine
2e9c0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c s that originall
2e9d0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 y.** registered
2e9e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
2e9f0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
2ea00 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 . {END}.**.** Th
2ea10 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 is routine must
2ea20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 be called from t
2ea30 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 he same thread i
2ea40 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 n which.** the a
2ea50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
2ea60 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 ed function is r
2ea70 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e unning..**.** IN
2ea80 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
2ea90 7b 48 31 36 32 34 33 7d 20 54 68 65 20 5b 73 71 {H16243} The [sq
2eaa0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 lite3_user_data(
2eab0 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 C)] interface re
2eac0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 turns a copy of
2ead0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
2eae0 50 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 P pointer from t
2eaf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
2eb00 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c te_function(D,X,
2eb10 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a N,E,P,F,S,L)].**
2eb20 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 or [sq
2eb30 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2eb40 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c ction16(D,X,N,E,
2eb50 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 P,F,S,L)] call t
2eb60 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hat.**
2eb70 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 53 registered the S
2eb80 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f QL function asso
2eb90 63 69 61 74 65 64 20 77 69 74 68 20 5b 73 71 6c ciated with [sql
2eba0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e ite3_context] C.
2ebb0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 .*/.void *sqlite
2ebc0 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 3_user_data(sqli
2ebd0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a te3_context*);..
2ebe0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2ebf0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
2ec00 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e ion For Function
2ec10 73 20 7b 48 31 36 32 35 30 7d 20 3c 53 36 30 36 s {H16250} <S606
2ec20 30 30 3e 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 00><S20200>.**.*
2ec30 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
2ec40 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 ntext_db_handle(
2ec50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
2ec60 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a rns a copy of.**
2ec70 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 the pointer to
2ec80 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
2ec90 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 nnection] (the 1
2eca0 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a st parameter).**
2ecb0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
2ecc0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2ecd0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 ()].** and [sqli
2ece0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2ecf0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 ion16()] routine
2ed00 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c s that originall
2ed10 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 y.** registered
2ed20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
2ed30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
2ed40 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
2ed50 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 35 TS:.**.** {H1625
2ed60 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 3} The [sqlite3_
2ed70 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c context_db_handl
2ed80 65 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 e(C)] interface
2ed90 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f returns a copy o
2eda0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 f the.**
2edb0 20 20 44 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d D pointer from
2edc0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 the [sqlite3_cr
2edd0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c eate_function(D,
2ede0 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a X,N,E,P,F,S,L)].
2edf0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b ** or [
2ee00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2ee10 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c unction16(D,X,N,
2ee20 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c E,P,F,S,L)] call
2ee30 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 that.**
2ee40 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 registered the
2ee50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 SQL function as
2ee60 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b 73 sociated with [s
2ee70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 qlite3_context]
2ee80 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 C..*/.sqlite3 *s
2ee90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 qlite3_context_d
2eea0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 b_handle(sqlite3
2eeb0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a _context*);../*.
2eec0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e ** CAPI3REF: Fun
2eed0 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 ction Auxiliary
2eee0 44 61 74 61 20 7b 48 31 36 32 37 30 7d 20 3c 53 Data {H16270} <S
2eef0 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20200>.**.** The
2ef00 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 following two f
2ef10 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 unctions may be
2ef20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 used by scalar S
2ef30 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a QL functions to.
2ef40 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 ** associate met
2ef50 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d adata with argum
2ef60 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 ent values. If t
2ef70 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 he same value is
2ef80 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 passed to.** mu
2ef90 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f ltiple invocatio
2efa0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 ns of the same S
2efb0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 QL function duri
2efc0 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 ng query executi
2efd0 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d on, under.** som
2efe0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 e circumstances
2eff0 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d the associated m
2f000 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 etadata may be p
2f010 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d reserved. This m
2f020 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 ay.** be used, f
2f030 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 or example, to a
2f040 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 dd a regular-exp
2f050 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 ression matching
2f060 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 scalar.** funct
2f070 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 ion. The compile
2f080 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 d version of the
2f090 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 regular express
2f0a0 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 ion is stored as
2f0b0 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 .** metadata ass
2f0c0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
2f0d0 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 SQL value passe
2f0e0 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 d as the regular
2f0f0 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 expression.** p
2f100 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d attern. The com
2f110 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 piled regular ex
2f120 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 pression can be
2f130 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 reused on multip
2f140 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e le.** invocation
2f150 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 s of the same fu
2f160 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 nction so that t
2f170 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 he original patt
2f180 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f ern string.** do
2f190 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 es not need to b
2f1a0 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 e recompiled on
2f1b0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e each invocation.
2f1c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
2f1d0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 e3_get_auxdata()
2f1e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2f1f0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
2f200 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 the metadata.**
2f210 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 associated by th
2f220 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 e sqlite3_set_au
2f230 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e xdata() function
2f240 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 with the Nth ar
2f250 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 gument.** value
2f260 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 to the applicati
2f270 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
2f280 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64 ion. If no metad
2f290 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 ata has been eve
2f2a0 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f r.** been set fo
2f2b0 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 r the Nth argume
2f2c0 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 nt of the functi
2f2d0 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f on, or if the co
2f2e0 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 rresponding.** f
2f2f0 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 unction paramete
2f300 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 r has changed si
2f310 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 nce the meta-dat
2f320 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 a was set,.** th
2f330 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 en sqlite3_get_a
2f340 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 uxdata() returns
2f350 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
2f360 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
2f370 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
2f380 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 interface saves
2f390 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a the metadata.**
2f3a0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 pointed to by i
2f3b0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 ts 3rd parameter
2f3c0 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 as the metadata
2f3d0 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a for the N-th.**
2f3e0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 argument of the
2f3f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
2f400 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 ined function.
2f410 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 Subsequent.** ca
2f420 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 lls to sqlite3_g
2f430 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 et_auxdata() mig
2f440 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 ht return this d
2f450 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a ata, if it has.*
2f460 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 * not been destr
2f470 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69 oyed..** If it i
2f480 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 s not NULL, SQLi
2f490 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 te will invoke t
2f4a0 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a he destructor.**
2f4b0 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 function given
2f4c0 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d by the 4th param
2f4d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
2f4e0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e set_auxdata() on
2f4f0 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 .** the metadata
2f500 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 when the corres
2f510 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e ponding function
2f520 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 parameter chang
2f530 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 es.** or when th
2f540 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
2f550 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 completes, which
2f560 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 ever comes first
2f570 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 ..**.** SQLite i
2f580 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 s free to call t
2f590 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e he destructor an
2f5a0 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 d drop metadata
2f5b0 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 on any.** parame
2f5c0 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 ter of any funct
2f5d0 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e ion at any time.
2f5e0 20 20 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 The only guara
2f5f0 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 ntee is that.**
2f600 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 the destructor w
2f610 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 ill be called be
2f620 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 fore the metadat
2f630 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a a is dropped..**
2f640 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c .** In practice,
2f650 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 metadata is pre
2f660 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 served between f
2f670 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f unction calls fo
2f680 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 r.** expressions
2f690 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 that are consta
2f6a0 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 nt at compile ti
2f6b0 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 me. This include
2f6c0 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c s literal.** val
2f6d0 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69 ues and SQL vari
2f6e0 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ables..**.** The
2f6f0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 se routines must
2f700 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
2f710 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
2f720 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 in which.** the
2f730 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 SQL function is
2f740 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 running..**.** I
2f750 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
2f760 20 7b 48 31 36 32 37 32 7d 20 54 68 65 20 5b 73 {H16272} The [s
2f770 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
2f780 74 61 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 ta(C,N)] interfa
2f790 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
2f7a0 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 nter.**
2f7b0 20 74 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 to metadata ass
2f7c0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
2f7d0 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f Nth parameter o
2f7e0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 f the SQL functi
2f7f0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 on.** w
2f800 68 6f 73 65 20 63 6f 6e 74 65 78 74 20 69 73 20 hose context is
2f810 43 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 C, or NULL if th
2f820 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 ere is no metada
2f830 74 61 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a ta associated.**
2f840 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 74 with t
2f850 68 61 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a hat parameter..*
2f860 2a 0a 2a 2a 20 7b 48 31 36 32 37 34 7d 20 54 68 *.** {H16274} Th
2f870 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 e [sqlite3_set_a
2f880 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d uxdata(C,N,P,D)]
2f890 20 69 6e 74 65 72 66 61 63 65 20 61 73 73 69 67 interface assig
2f8a0 6e 73 20 61 20 6d 65 74 61 64 61 74 61 0a 2a 2a ns a metadata.**
2f8b0 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 pointe
2f8c0 72 20 50 20 74 6f 20 74 68 65 20 4e 74 68 20 70 r P to the Nth p
2f8d0 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 arameter of the
2f8e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 SQL function wit
2f8f0 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2a 0a h context C..**.
2f900 2a 2a 20 7b 48 31 36 32 37 36 7d 20 53 51 4c 69 ** {H16276} SQLi
2f910 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 te will invoke t
2f920 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 he destructor D
2f930 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 with a single ar
2f940 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 gument.**
2f950 20 20 20 77 68 69 63 68 20 69 73 20 74 68 65 20 which is the
2f960 6d 65 74 61 64 61 74 61 20 70 6f 69 6e 74 65 72 metadata pointer
2f970 20 50 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 P following a c
2f980 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 all to.**
2f990 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f [sqlite3_set_
2f9a0 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 auxdata(C,N,P,D)
2f9b0 5d 20 77 68 65 6e 20 53 51 4c 69 74 65 20 63 65 ] when SQLite ce
2f9c0 61 73 65 73 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20 ases to hold.**
2f9d0 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 74 the met
2f9e0 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 adata..**.** {H1
2f9f0 36 32 37 37 7d 20 53 51 4c 69 74 65 20 63 65 61 6277} SQLite cea
2fa00 73 65 73 20 74 6f 20 68 6f 6c 64 20 6d 65 74 61 ses to hold meta
2fa10 64 61 74 61 20 66 6f 72 20 61 6e 20 53 51 4c 20 data for an SQL
2fa20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 function paramet
2fa30 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 er.** w
2fa40 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 hen the value of
2fa50 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 that parameter
2fa60 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b changes..**.** {
2fa70 48 31 36 32 37 38 7d 20 57 68 65 6e 20 5b 73 71 H16278} When [sq
2fa80 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
2fa90 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 73 20 69 a(C,N,P,D)] is i
2faa0 6e 76 6f 6b 65 64 2c 20 74 68 65 20 64 65 73 74 nvoked, the dest
2fab0 72 75 63 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 ructor.**
2fac0 20 20 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 is called for
2fad0 20 61 6e 79 20 70 72 69 6f 72 20 6d 65 74 61 64 any prior metad
2fae0 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 ata associated w
2faf0 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e ith the same fun
2fb00 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ction.**
2fb10 20 20 63 6f 6e 74 65 78 74 20 43 20 61 6e 64 20 context C and
2fb20 70 61 72 61 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a parameter N..**.
2fb30 2a 2a 20 7b 48 31 36 32 37 39 7d 20 53 51 4c 69 ** {H16279} SQLi
2fb40 74 65 20 77 69 6c 6c 20 63 61 6c 6c 20 64 65 73 te will call des
2fb50 74 72 75 63 74 6f 72 73 20 66 6f 72 20 61 6e 79 tructors for any
2fb60 20 6d 65 74 61 64 61 74 61 20 69 74 20 69 73 20 metadata it is
2fb70 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 holding.**
2fb80 20 20 20 20 69 6e 20 61 20 70 61 72 74 69 63 75 in a particu
2fb90 6c 61 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 lar [prepared st
2fba0 61 74 65 6d 65 6e 74 5d 20 53 20 77 68 65 6e 20 atement] S when
2fbb0 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 either.**
2fbc0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 [sqlite3_rese
2fbd0 74 28 53 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 t(S)] or [sqlite
2fbe0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 3_finalize(S)] i
2fbf0 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 s called..*/.voi
2fc00 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 d *sqlite3_get_a
2fc10 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 uxdata(sqlite3_c
2fc20 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b ontext*, int N);
2fc30 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 .void sqlite3_se
2fc40 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 t_auxdata(sqlite
2fc50 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 3_context*, int
2fc60 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 N, void*, void (
2fc70 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a *)(void*));.../*
2fc80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
2fc90 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 nstants Defining
2fca0 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 Special Destruc
2fcb0 74 6f 72 20 42 65 68 61 76 69 6f 72 20 7b 48 31 tor Behavior {H1
2fcc0 30 32 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 0280} <S30100>.*
2fcd0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 *.** These are s
2fce0 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f pecial values fo
2fcf0 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 r the destructor
2fd00 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 that is passed
2fd10 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e in as the.** fin
2fd20 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 al argument to r
2fd30 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 outines like [sq
2fd40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f lite3_result_blo
2fd50 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65 b()]. If the de
2fd60 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 structor.** argu
2fd70 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 ment is SQLITE_S
2fd80 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 TATIC, it means
2fd90 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 that the content
2fda0 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 pointer is cons
2fdb0 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c tant.** and will
2fdc0 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 never change.
2fdd0 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 It does not need
2fde0 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 to be destroyed
2fdf0 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 . The.** SQLITE
2fe00 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 _TRANSIENT value
2fe10 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
2fe20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b content will lik
2fe30 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a ely change in.**
2fe40 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 the near future
2fe50 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 and that SQLite
2fe60 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 should make its
2fe70 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 own private cop
2fe80 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 y of.** the cont
2fe90 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 ent before retur
2fea0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ning..**.** The
2feb0 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 typedef is neces
2fec0 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f sary to work aro
2fed0 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 und problems in
2fee0 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 certain.** C++ c
2fef0 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 ompilers. See t
2ff00 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a icket #2191..*/.
2ff10 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 typedef void (*s
2ff20 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f qlite3_destructo
2ff30 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a r_type)(void*);.
2ff40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
2ff50 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c TATIC ((sql
2ff60 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f ite3_destructor_
2ff70 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 type)0).#define
2ff80 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
2ff90 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 ((sqlite3_des
2ffa0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 tructor_type)-1)
2ffb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2ffc0 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 : Setting The Re
2ffd0 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 sult Of An SQL F
2ffe0 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d unction {H16400}
2fff0 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20200>.**.**
30000 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
30010 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 re used by the x
30020 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 Func or xFinal c
30030 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a allbacks that.**
30040 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 implement SQL f
30050 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 unctions and agg
30060 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a regates. See.**
30070 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
30080 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 _function()] and
30090 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
300a0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a _function16()].*
300b0 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c * for additional
300c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
300d0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 .** These functi
300e0 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 ons work very mu
300f0 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 ch like the [par
30100 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 ameter binding]
30110 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e family of.** fun
30120 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 ctions used to b
30130 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f ind values to ho
30140 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e st parameters in
30150 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
30160 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 ents..** Refer t
30170 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d o the [SQL param
30180 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 eter] documentat
30190 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ion for addition
301a0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
301b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
301c0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 3_result_blob()
301d0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
301e0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a he result from.*
301f0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e * an application
30200 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
30210 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 n to be the BLOB
30220 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 whose content i
30230 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 s pointed.** to
30240 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 by the second pa
30250 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 rameter and whic
30260 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e h is N bytes lon
30270 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 g where N is the
30280 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 .** third parame
30290 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ter..**.** The s
302a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 qlite3_result_ze
302b0 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 roblob() interfa
302c0 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 ces set the resu
302d0 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 lt of.** the app
302e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
302f0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
30300 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e a BLOB containin
30310 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 g all zero.** by
30320 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 tes and N bytes
30330 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e in size, where N
30340 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
30350 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
30360 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 er..**.** The sq
30370 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 lite3_result_dou
30380 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ble() interface
30390 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 sets the result
303a0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 from.** an appli
303b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
303c0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 unction to be a
303d0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 floating point v
303e0 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a alue specified.*
303f0 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 * by its 2nd arg
30400 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ument..**.** The
30410 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
30420 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 error() and sqli
30430 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
30440 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 16() functions.*
30450 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c * cause the impl
30460 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 emented SQL func
30470 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e tion to throw an
30480 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 exception..** S
30490 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 QLite uses the s
304a0 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f tring pointed to
304b0 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 by the.** 2nd p
304c0 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 arameter of sqli
304d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
304e0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 () or sqlite3_re
304f0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a sult_error16().*
30500 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 * as the text of
30510 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
30520 65 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 e. SQLite inter
30530 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a prets the error.
30540 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e ** message strin
30550 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 g from sqlite3_r
30560 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 esult_error() as
30570 20 55 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a UTF-8. SQLite.*
30580 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 * interprets the
30590 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c string from sql
305a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
305b0 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 r16() as UTF-16
305c0 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 in native.** byt
305d0 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68 65 e order. If the
305e0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
305f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 to sqlite3_resu
30600 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 lt_error().** or
30610 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
30620 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 error16() is neg
30630 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 ative then SQLit
30640 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 e takes as the e
30650 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 rror.** message
30660 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f all text up thro
30670 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 ugh the first ze
30680 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a ro character..**
30690 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 If the third pa
306a0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
306b0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
306c0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ) or.** sqlite3_
306d0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
306e0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
306f0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b then SQLite tak
30700 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 es that many.**
30710 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 bytes (not chara
30720 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 cters) from the
30730 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 2nd parameter as
30740 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
30750 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 ge..** The sqlit
30760 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
30770 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 ) and sqlite3_re
30780 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a sult_error16().*
30790 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 * routines make
307a0 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f a private copy o
307b0 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 f the error mess
307c0 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a age text before.
307d0 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 ** they return.
307e0 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c Hence, the call
307f0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e ing function can
30800 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a deallocate or.*
30810 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 * modify the tex
30820 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 t after they ret
30830 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d urn without harm
30840 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 ..** The sqlite3
30850 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f _result_error_co
30860 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 de() function ch
30870 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 anges the error
30880 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 code.** returned
30890 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 by SQLite as a
308a0 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 result of an err
308b0 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e or in a function
308c0 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a . By default,.*
308d0 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 * the error code
308e0 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 is SQLITE_ERROR
308f0 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e 74 20 . A subsequent
30900 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
30910 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a result_error().*
30920 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 * or sqlite3_res
30930 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 ult_error16() re
30940 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 sets the error c
30950 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 ode to SQLITE_ER
30960 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ROR..**.** The s
30970 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f qlite3_result_to
30980 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 obig() interface
30990 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 causes SQLite t
309a0 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 o throw an error
309b0 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 .** indicating t
309c0 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 hat a string or
309d0 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20 BLOB is to long
309e0 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a to represent..**
309f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
30a00 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 result_nomem() i
30a10 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 nterface causes
30a20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 SQLite to throw
30a30 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 an error.** indi
30a40 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 cating that a me
30a50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
30a60 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 failed..**.** Th
30a70 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
30a80 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 _int() interface
30a90 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e sets the return
30aa0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 value.** of the
30ab0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
30ac0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
30ad0 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 be the 32-bit s
30ae0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a igned integer.**
30af0 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 value given in
30b00 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 the 2nd argument
30b10 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 ..** The sqlite3
30b20 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 _result_int64()
30b30 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
30b40 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a he return value.
30b50 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 ** of the applic
30b60 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
30b70 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 nction to be the
30b80 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 64-bit signed i
30b90 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 nteger.** value
30ba0 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 given in the 2nd
30bb0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
30bc0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
30bd0 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 ult_null() inter
30be0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
30bf0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 turn value.** of
30c00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
30c10 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
30c20 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a n to be NULL..**
30c30 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
30c40 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 result_text(), s
30c50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
30c60 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 xt16(),.** sqlit
30c70 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
30c80 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 le(), and sqlite
30c90 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 3_result_text16b
30ca0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a e() interfaces.*
30cb0 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e * set the return
30cc0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 value of the ap
30cd0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
30ce0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
30cf0 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e .** a text strin
30d00 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 g which is repre
30d10 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c sented as UTF-8,
30d20 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 UTF-16 native b
30d30 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 yte order,.** UT
30d40 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 F-16 little endi
30d50 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 an, or UTF-16 bi
30d60 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 g endian, respec
30d70 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 tively..** SQLit
30d80 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 e takes the text
30d90 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 result from the
30da0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f application fro
30db0 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 m.** the 2nd par
30dc0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 ameter of the sq
30dd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
30de0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a t* interfaces..*
30df0 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 * If the 3rd par
30e00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
30e10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
30e20 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
30e30 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
30e40 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 en SQLite takes
30e50 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d result text from
30e60 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
30e70 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 er.** through th
30e80 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 e first zero cha
30e90 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 racter..** If th
30ea0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
30eb0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
30ec0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
30ed0 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e rfaces.** is non
30ee0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 -negative, then
30ef0 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e as many bytes (n
30f00 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f ot characters) o
30f10 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f f the text.** po
30f20 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 inted to by the
30f30 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 2nd parameter ar
30f40 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 e taken as the a
30f50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
30f60 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 ed.** function r
30f70 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 esult..** If the
30f80 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
30f90 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
30fa0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
30fb0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 faces.** or sqli
30fc0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 te3_result_blob
30fd0 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f is a non-NULL po
30fe0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 inter, then SQLi
30ff0 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a te calls that.**
31000 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 function as the
31010 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 destructor on t
31020 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 he text or BLOB
31030 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 result when it h
31040 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 as.** finished u
31050 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 sing that result
31060 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 ..** If the 4th
31070 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
31080 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
31090 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
310a0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 or.** sqlite3_r
310b0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 esult_blob is th
310c0 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 e special consta
310d0 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 nt SQLITE_STATIC
310e0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a , then SQLite.**
310f0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 assumes that th
31100 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 e text or BLOB r
31110 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 esult is in cons
31120 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 tant space and d
31130 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 oes not.** copy
31140 74 68 65 20 69 74 20 6f 72 20 63 61 6c 6c 20 61 the it or call a
31150 20 64 65 73 74 72 75 63 74 6f 72 20 77 68 65 6e destructor when
31160 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 it has finished
31170 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 using that resu
31180 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 lt..** If the 4t
31190 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
311a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
311b0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
311c0 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 es.** or sqlite3
311d0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 _result_blob is
311e0 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 the special cons
311f0 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e tant SQLITE_TRAN
31200 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 SIENT.** then SQ
31210 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 Lite makes a cop
31220 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 y of the result
31230 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 into space obtai
31240 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d ned from.** from
31250 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
31260 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 ()] before it re
31270 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 turns..**.** The
31280 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
31290 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 value() interfac
312a0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c e sets the resul
312b0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c t of.** the appl
312c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
312d0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
312e0 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e copy the.** [un
312f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
31300 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
31310 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
31320 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 2nd parameter.
31330 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f The.** sqlite3_
31340 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 result_value() i
31350 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 nterface makes a
31360 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 copy of the [sq
31370 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 lite3_value].**
31380 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c so that the [sql
31390 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 ite3_value] spec
313a0 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 ified in the par
313b0 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 ameter may chang
313c0 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c e or.** be deall
313d0 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c ocated after sql
313e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
313f0 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 e() returns with
31400 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b out harm..** A [
31410 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
31420 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
31430 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 may always be us
31440 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b ed where an.** [
31450 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
31460 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
31470 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 t is required, s
31480 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 o either.** kind
31490 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c of [sqlite3_val
314a0 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 ue] object can b
314b0 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73 e used with this
314c0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
314d0 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 * If these routi
314e0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 nes are called f
314f0 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 rom within the d
31500 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a ifferent thread.
31510 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 ** than the one
31520 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 containing the a
31530 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
31540 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 ed function that
31550 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 received.** the
31560 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 [sqlite3_contex
31570 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 t] pointer, the
31580 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
31590 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 fined..**.** INV
315a0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
315b0 48 31 36 34 30 33 7d 20 54 68 65 20 64 65 66 61 H16403} The defa
315c0 75 6c 74 20 72 65 74 75 72 6e 20 76 61 6c 75 65 ult return value
315d0 20 66 72 6f 6d 20 61 6e 79 20 53 51 4c 20 66 75 from any SQL fu
315e0 6e 63 74 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a nction is NULL..
315f0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 36 7d 20 54 **.** {H16406} T
31600 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 he [sqlite3_resu
31610 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 lt_blob(C,V,N,D)
31620 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e ] interface chan
31630 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ges the.**
31640 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 return value
31650 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 of function C t
31660 6f 20 62 65 20 61 20 42 4c 4f 42 20 74 68 61 74 o be a BLOB that
31670 20 69 73 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 is N bytes.**
31680 20 20 20 20 20 20 20 20 69 6e 20 6c 65 6e 67 74 in lengt
31690 68 20 61 6e 64 20 77 69 74 68 20 63 6f 6e 74 65 h and with conte
316a0 6e 74 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 nt pointed to by
316b0 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 V..**.** {H1640
316c0 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 9} The [sqlite3_
316d0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 43 2c result_double(C,
316e0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 V)] interface ch
316f0 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 anges the.**
31700 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c return val
31710 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 ue of function C
31720 20 74 6f 20 62 65 20 74 68 65 20 66 6c 6f 61 74 to be the float
31730 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 ing point value
31740 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 32 V..**.** {H16412
31750 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 } The [sqlite3_r
31760 65 73 75 6c 74 5f 65 72 72 6f 72 28 43 2c 56 2c esult_error(C,V,
31770 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 N)] interface ch
31780 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e anges the return
31790 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c .** val
317a0 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 ue of function C
317b0 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 to be an except
317c0 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 ion with error c
317d0 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ode.**
317e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 [SQLITE_ERROR] a
317f0 6e 64 20 61 20 55 54 46 2d 38 20 65 72 72 6f 72 nd a UTF-8 error
31800 20 6d 65 73 73 61 67 65 20 63 6f 70 69 65 64 20 message copied
31810 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65 from V up to the
31820 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 72 .** fir
31830 73 74 20 7a 65 72 6f 20 62 79 74 65 20 6f 72 20 st zero byte or
31840 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 20 61 72 until N bytes ar
31850 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70 e read if N is p
31860 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b ositive..**.** {
31870 48 31 36 34 31 35 7d 20 54 68 65 20 5b 73 71 6c H16415} The [sql
31880 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
31890 72 31 36 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 r16(C,V,N)] inte
318a0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 rface changes th
318b0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 e return.**
318c0 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 value of fu
318d0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 nction C to be a
318e0 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 n exception with
318f0 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 error code.**
31900 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
31910 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 ERROR] and a UTF
31920 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 -16 native byte
31930 6f 72 64 65 72 20 65 72 72 6f 72 20 6d 65 73 73 order error mess
31940 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 age.**
31950 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 copied from V up
31960 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 to the first ze
31970 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 72 ro terminator or
31980 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 0a 2a until N bytes.*
31990 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 72 * are r
319a0 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 ead if N is posi
319b0 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 tive..**.** {H16
319c0 34 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 418} The [sqlite
319d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 3_result_error_t
319e0 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74 65 72 66 oobig(C)] interf
319f0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 ace changes the
31a00 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 return.**
31a10 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 value of the
31a20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 function C to be
31a30 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 an exception wi
31a40 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a th error code.**
31a50 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 [SQLIT
31a60 45 5f 54 4f 4f 42 49 47 5d 20 61 6e 64 20 61 6e E_TOOBIG] and an
31a70 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 appropriate err
31a80 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a or message..**.*
31a90 2a 20 7b 48 31 36 34 32 31 7d 20 54 68 65 20 5b * {H16421} The [
31aa0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
31ab0 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 rror_nomem(C)] i
31ac0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 nterface changes
31ad0 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 the return.**
31ae0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 value of
31af0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 the function C
31b00 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 to be an excepti
31b10 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f on with error co
31b20 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b de.** [
31b30 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e SQLITE_NOMEM] an
31b40 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 d an appropriate
31b50 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a error message..
31b60 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 34 7d 20 54 **.** {H16424} T
31b70 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 he [sqlite3_resu
31b80 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 43 2c lt_error_code(C,
31b90 45 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 E)] interface ch
31ba0 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e anges the return
31bb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c .** val
31bc0 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 ue of the functi
31bd0 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 on C to be an ex
31be0 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 ception with err
31bf0 6f 72 20 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 or code E..**
31c00 20 20 20 20 20 20 20 54 68 65 20 65 72 72 6f 72 The error
31c10 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 69 73 message text is
31c20 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a unchanged..**.*
31c30 2a 20 7b 48 31 36 34 32 37 7d 20 54 68 65 20 5b * {H16427} The [
31c40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 sqlite3_result_i
31c50 6e 74 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 nt(C,V)] interfa
31c60 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a ce changes the.*
31c70 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 * retur
31c80 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 n value of funct
31c90 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 ion C to be the
31ca0 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76 32-bit integer v
31cb0 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 alue V..**.** {H
31cc0 31 36 34 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 16430} The [sqli
31cd0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 te3_result_int64
31ce0 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 (C,V)] interface
31cf0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 changes the.**
31d00 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 return
31d10 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f value of functio
31d20 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 36 34 n C to be the 64
31d30 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c -bit integer val
31d40 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 ue V..**.** {H16
31d50 34 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 433} The [sqlite
31d60 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 3_result_null(C)
31d70 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e ] interface chan
31d80 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ges the.**
31d90 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 return value
31da0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 of function C t
31db0 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a o be NULL..**.**
31dc0 20 7b 48 31 36 34 33 36 7d 20 54 68 65 20 5b 73 {H16436} The [s
31dd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
31de0 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 xt(C,V,N,D)] int
31df0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 erface changes t
31e00 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 he.** r
31e10 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 eturn value of f
31e20 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 unction C to be
31e30 74 68 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67 the UTF-8 string
31e40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 56 20 75 .** V u
31e50 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a p to the first z
31e60 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 ero if N is nega
31e70 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 tive.**
31e80 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 or the first N
31e90 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 bytes of V if N
31ea0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e is non-negative.
31eb0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 39 7d 20 .**.** {H16439}
31ec0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
31ed0 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e ult_text16(C,V,N
31ee0 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 ,D)] interface c
31ef0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 hanges the.**
31f00 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 return va
31f10 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 lue of function
31f20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d C to be the UTF-
31f30 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 16 native byte o
31f40 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 rder.**
31f50 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 string V up to
31f60 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 the first zero i
31f70 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a f N is negative.
31f80 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 ** or t
31f90 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 he first N bytes
31fa0 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f of V if N is no
31fb0 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a n-negative..**.*
31fc0 2a 20 7b 48 31 36 34 34 32 7d 20 54 68 65 20 5b * {H16442} The [
31fd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
31fe0 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 ext16be(C,V,N,D)
31ff0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e ] interface chan
32000 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ges the.**
32010 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 return value
32020 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 of function C t
32030 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 36 20 o be the UTF-16
32040 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 big-endian.**
32050 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 string V
32060 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 up to the first
32070 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 zero if N is neg
32080 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 ative.**
32090 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e or the first N
320a0 20 62 79 74 65 73 20 6f 72 20 56 20 69 66 20 4e bytes or V if N
320b0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
320c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 35 7d ..**.** {H16445}
320d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 The [sqlite3_re
320e0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c sult_text16le(C,
320f0 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 V,N,D)] interfac
32100 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a e changes the.**
32110 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e return
32120 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 value of functi
32130 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 on C to be the U
32140 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 TF-16 little-end
32150 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ian.**
32160 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 string V up to t
32170 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 he first zero if
32180 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a N is negative.*
32190 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 * or th
321a0 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 e first N bytes
321b0 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e of V if N is non
321c0 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a -negative..**.**
321d0 20 7b 48 31 36 34 34 38 7d 20 54 68 65 20 5b 73 {H16448} The [s
321e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 qlite3_result_va
321f0 6c 75 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 lue(C,V)] interf
32200 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a ace changes the.
32210 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
32220 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 rn value of func
32230 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 tion C to be the
32240 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
32250 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 lite3_value].**
32260 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20 object
32270 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 31 V..**.** {H16451
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 7a 65 72 6f 62 6c 6f 62 28 43 esult_zeroblob(C
322a0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 ,N)] interface c
322b0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 hanges the.**
322c0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 return va
322d0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 lue of function
322e0 43 20 74 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74 C to be an N-byt
322f0 65 20 42 4c 4f 42 20 6f 66 20 61 6c 6c 20 7a 65 e BLOB of all ze
32300 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 ros..**.** {H164
32310 35 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 54} The [sqlite3
32320 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d _result_error()]
32330 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
32340 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a sult_error16()].
32350 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 ** inte
32360 72 66 61 63 65 73 20 6d 61 6b 65 20 61 20 63 6f rfaces make a co
32370 70 79 20 6f 66 20 74 68 65 69 72 20 65 72 72 6f py of their erro
32380 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 r message string
32390 73 20 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 s before.**
323a0 20 20 20 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a returning..
323b0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 37 7d 20 49 **.** {H16457} I
323c0 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74 f the D destruct
323d0 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 or parameter to
323e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
323f0 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a blob(C,V,N,D)],.
32400 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
32410 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
32420 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c (C,V,N,D)], [sql
32430 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
32440 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 16(C,V,N,D)],.**
32450 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
32460 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
32470 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 be(C,V,N,D)], or
32480 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
32490 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
324a0 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 t16le(C,V,N,D)]
324b0 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 20 is the constant
324c0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a [SQLITE_STATIC].
324d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e ** then
324e0 20 6e 6f 20 64 65 73 74 72 75 63 74 6f 72 20 69 no destructor i
324f0 73 20 65 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e s ever called on
32500 20 74 68 65 20 70 6f 69 6e 74 65 72 20 56 20 61 the pointer V a
32510 6e 64 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20 nd SQLite.**
32520 20 20 20 20 20 20 61 73 73 75 6d 65 73 20 74 68 assumes th
32530 61 74 20 56 20 69 73 20 69 6d 6d 75 74 61 62 6c at V is immutabl
32540 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 30 e..**.** {H16460
32550 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72 } If the D destr
32560 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 uctor parameter
32570 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 to [sqlite3_resu
32580 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 lt_blob(C,V,N,D)
32590 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ],.** [
325a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
325b0 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b ext(C,V,N,D)], [
325c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
325d0 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c ext16(C,V,N,D)],
325e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
325f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
32600 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c t16be(C,V,N,D)],
32610 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
32620 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
32630 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 text16le(C,V,N,D
32640 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61 )] is the consta
32650 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b nt.** [
32660 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
32670 5d 20 74 68 65 6e 20 74 68 65 20 69 6e 74 65 72 ] then the inter
32680 66 61 63 65 73 20 6d 61 6b 65 73 20 61 20 63 6f faces makes a co
32690 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 py of the.**
326a0 20 20 20 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66 content of
326b0 20 56 20 61 6e 64 20 72 65 74 61 69 6e 73 20 74 V and retains t
326c0 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b he copy..**.** {
326d0 48 31 36 34 36 33 7d 20 49 66 20 74 68 65 20 44 H16463} If the D
326e0 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 destructor para
326f0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
32700 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 3_result_blob(C,
32710 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 V,N,D)],.**
32720 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 [sqlite3_re
32730 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c sult_text(C,V,N,
32740 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 D)], [sqlite3_re
32750 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c sult_text16(C,V,
32760 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 N,D)],.**
32770 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 [sqlite3_resu
32780 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c lt_text16be(C,V,
32790 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 N,D)], or.**
327a0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 [sqlite3_r
327b0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 esult_text16le(C
327c0 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65 ,V,N,D)] is some
327d0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 value other tha
327e0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 n.** th
327f0 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c e constants [SQL
32800 49 54 45 5f 53 54 41 54 49 43 5d 20 61 6e 64 20 ITE_STATIC] and
32810 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e [SQLITE_TRANSIEN
32820 54 5d 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 T] then.**
32830 20 20 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 SQLite will
32840 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 invoke the destr
32850 75 63 74 6f 72 20 44 20 77 69 74 68 20 56 20 61 uctor D with V a
32860 73 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d s its only argum
32870 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ent.**
32880 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 when it has fini
32890 73 68 65 64 20 77 69 74 68 20 74 68 65 20 56 20 shed with the V
328a0 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 value..*/.void s
328b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
328c0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ob(sqlite3_conte
328d0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
328e0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
328f0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c oid*));.void sql
32900 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 ite3_result_doub
32910 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 le(sqlite3_conte
32920 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f xt*, double);.vo
32930 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
32940 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f t_error(sqlite3_
32950 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
32960 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 char*, int);.voi
32970 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
32980 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 _error16(sqlite3
32990 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
329a0 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f void*, int);.vo
329b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
329c0 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 t_error_toobig(s
329d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
329e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
329f0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 esult_error_nome
32a00 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 m(sqlite3_contex
32a10 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 t*);.void sqlite
32a20 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 3_result_error_c
32a30 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ode(sqlite3_cont
32a40 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 ext*, int);.void
32a50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
32a60 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 int(sqlite3_cont
32a70 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 ext*, int);.void
32a80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
32a90 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f int64(sqlite3_co
32aa0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f ntext*, sqlite3_
32ab0 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c int64);.void sql
32ac0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c ite3_result_null
32ad0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
32ae0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 *);.void sqlite3
32af0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c _result_text(sql
32b00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
32b10 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c onst char*, int,
32b20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
32b30 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
32b40 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c esult_text16(sql
32b50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
32b60 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
32b70 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
32b80 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
32b90 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 esult_text16le(s
32ba0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
32bb0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
32bc0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 t,void(*)(void*)
32bd0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
32be0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 result_text16be(
32bf0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
32c00 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
32c10 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a nt,void(*)(void*
32c20 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
32c30 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 _result_value(sq
32c40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
32c50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
32c60 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
32c70 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 sult_zeroblob(sq
32c80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
32c90 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int n);../*.** C
32ca0 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 API3REF: Define
32cb0 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 New Collating Se
32cc0 71 75 65 6e 63 65 73 20 7b 48 31 36 36 30 30 7d quences {H16600}
32cd0 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20300>.**.**
32ce0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 These functions
32cf0 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 are used to add
32d00 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 new collation se
32d10 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a quences to the.*
32d20 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
32d30 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 ection] specifie
32d40 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 d as the first a
32d50 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 rgument..**.** T
32d60 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e he name of the n
32d70 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 ew collation seq
32d80 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 uence is specifi
32d90 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 ed as a UTF-8 st
32da0 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 ring.** for sqli
32db0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
32dc0 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 tion() and sqlit
32dd0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
32de0 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 ion_v2().** and
32df0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 a UTF-16 string
32e00 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 for sqlite3_crea
32e10 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 te_collation16()
32e20 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a . In all cases.*
32e30 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 * the name is pa
32e40 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f ssed as the seco
32e50 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 nd function argu
32e60 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ment..**.** The
32e70 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d third argument m
32e80 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 ay be one of the
32e90 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 constants [SQLI
32ea0 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 TE_UTF8],.** [SQ
32eb0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 LITE_UTF16LE] or
32ec0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 [SQLITE_UTF16BE
32ed0 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 ], indicating th
32ee0 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 at the user-supp
32ef0 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 lied.** routine
32f00 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 expects to be pa
32f10 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f ssed pointers to
32f20 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 strings encoded
32f30 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a using UTF-8,.**
32f40 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 UTF-16 little-e
32f50 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 ndian, or UTF-16
32f60 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 big-endian, res
32f70 70 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a pectively. The.*
32f80 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 * third argument
32f90 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b might also be [
32fa0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 SQLITE_UTF16_ALI
32fb0 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61 74 GNED] to indicat
32fc0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f e that.** the ro
32fd0 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f utine expects po
32fe0 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74 inters to 16-bit
32ff0 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74 word aligned st
33000 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d rings.** of UTF-
33010 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 16 in the native
33020 20 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74 byte order of t
33030 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 he host computer
33040 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 ..**.** A pointe
33050 72 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 r to the user su
33060 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d pplied routine m
33070 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 ust be passed as
33080 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 the fifth.** ar
33090 67 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69 gument. If it i
330a0 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 s NULL, this is
330b0 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 the same as dele
330c0 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 ting the collati
330d0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 on.** sequence (
330e0 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 so that SQLite c
330f0 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e annot call it an
33100 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 ymore)..** Each
33110 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 time the applica
33120 74 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75 tion supplied fu
33130 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 nction is invoke
33140 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 0a d, it is passed.
33150 2a 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 20 ** as its first
33160 70 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79 parameter a copy
33170 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 of the void* pa
33180 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 ssed as the four
33190 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 th argument.** t
331a0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 o sqlite3_create
331b0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 _collation() or
331c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
331d0 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a ollation16()..**
331e0 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e .** The remainin
331f0 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 g arguments to t
33200 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 he application-s
33210 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 upplied routine
33220 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c are two strings,
33230 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 .** each represe
33240 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 nted by a (lengt
33250 68 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 6e h, data) pair an
33260 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 d encoded in the
33270 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 encoding.** tha
33280 74 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20 t was passed as
33290 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 the third argume
332a0 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c nt when the coll
332b0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 ation sequence w
332c0 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 as.** registered
332d0 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 61 70 70 . {END} The app
332e0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 lication defined
332f0 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 collation routi
33300 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 ne should.** ret
33310 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 urn negative, ze
33320 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 ro or positive i
33330 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 f the first stri
33340 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c ng is less than,
33350 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 .** equal to, or
33360 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 greater than th
33370 65 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e e second string.
33380 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d i.e. (STRING1 -
33390 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a STRING2)..**.**
333a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 The sqlite3_cre
333b0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
333c0 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 () works like sq
333d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
333e0 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 lation().** exce
333f0 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 pt that it takes
33400 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 an extra argume
33410 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65 nt which is a de
33420 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 structor for.**
33430 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 the collation.
33440 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 The destructor i
33450 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 s called when th
33460 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a e collation is.*
33470 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 * destroyed and
33480 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 is passed a copy
33490 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 of the fourth p
334a0 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 arameter void* p
334b0 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 ointer.** of the
334c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
334d0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a collation_v2()..
334e0 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 ** Collations ar
334f0 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e e destroyed when
33500 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 they are overri
33510 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 dden by later ca
33520 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f lls to the.** co
33530 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e llation creation
33540 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 functions or wh
33550 65 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 en the [database
33560 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 connection] is
33570 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 closed.** using
33580 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
33590 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 ]..**.** INVARIA
335a0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 NTS:.**.** {H166
335b0 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 03} A successful
335c0 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 call to the.**
335d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
335e0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
335f0 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c on_v2(B,X,E,P,F,
33600 44 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a D)] interface.**
33610 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 regist
33620 65 72 73 20 66 75 6e 63 74 69 6f 6e 20 46 20 61 ers function F a
33630 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e s the comparison
33640 20 66 75 6e 63 74 69 6f 6e 20 75 73 65 64 20 74 function used t
33650 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d o.** im
33660 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61 74 69 6f plement collatio
33670 6e 20 58 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 n X on the [data
33680 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
33690 20 42 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 B for.**
336a0 20 20 20 64 61 74 61 62 61 73 65 73 20 68 61 76 databases hav
336b0 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a ing encoding E..
336c0 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 34 7d 20 53 **.** {H16604} S
336d0 51 4c 69 74 65 20 75 6e 64 65 72 73 74 61 6e 64 QLite understand
336e0 73 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 s the X paramete
336f0 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 r to.**
33700 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
33710 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c _collation_v2(B,
33720 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61 X,E,P,F,D)] as a
33730 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
33740 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 .** UTF
33750 2d 38 20 73 74 72 69 6e 67 20 69 6e 20 77 68 69 -8 string in whi
33760 63 68 20 63 61 73 65 20 69 73 20 69 67 6e 6f 72 ch case is ignor
33770 65 64 20 66 6f 72 20 41 53 43 49 49 20 63 68 61 ed for ASCII cha
33780 72 61 63 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20 racters and.**
33790 20 20 20 20 20 20 20 20 69 73 20 73 69 67 6e 69 is signi
337a0 66 69 63 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 ficant for non-A
337b0 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73 2e SCII characters.
337c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 36 7d 20 .**.** {H16606}
337d0 53 75 63 63 65 73 73 69 76 65 20 63 61 6c 6c 73 Successive calls
337e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 to [sqlite3_cre
337f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
33800 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a (B,X,E,P,F,D)].*
33810 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 * with
33820 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20 the same values
33830 66 6f 72 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c for B, X, and E,
33840 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 override prior
33850 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 values.**
33860 20 20 20 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20 of P, F, and
33870 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 39 D..**.** {H16609
33880 7d 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 } If the destruc
33890 74 6f 72 20 44 20 69 6e 20 5b 73 71 6c 69 74 65 tor D in [sqlite
338a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
338b0 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c on_v2(B,X,E,P,F,
338c0 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 D)].**
338d0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e is not NULL then
338e0 20 69 74 20 69 73 20 63 61 6c 6c 65 64 20 77 69 it is called wi
338f0 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 th argument P wh
33900 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 en the.**
33910 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e collating fun
33920 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 ction is dropped
33930 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a by SQLite..**.*
33940 2a 20 7b 48 31 36 36 31 32 7d 20 41 20 63 6f 6c * {H16612} A col
33950 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 lating function
33960 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 is dropped when
33970 69 74 20 69 73 20 6f 76 65 72 6c 6f 61 64 65 64 it is overloaded
33980 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 35 7d ..**.** {H16615}
33990 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e A collating fun
339a0 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 ction is dropped
339b0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 when the databa
339c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
339d0 20 20 20 20 20 20 20 20 20 20 69 73 20 63 6c 6f is clo
339e0 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 sed using [sqlit
339f0 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a e3_close()]..**.
33a00 2a 2a 20 7b 48 31 36 36 31 38 7d 20 54 68 65 20 ** {H16618} The
33a10 70 6f 69 6e 74 65 72 20 50 20 69 6e 20 5b 73 71 pointer P in [sq
33a20 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
33a30 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c lation_v2(B,X,E,
33a40 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 P,F,D)].**
33a50 20 20 20 20 69 73 20 70 61 73 73 65 64 20 74 68 is passed th
33a60 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 rough as the fir
33a70 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
33a80 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a the comparison.*
33a90 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 * funct
33aa0 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 73 75 ion F for all su
33ab0 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 bsequent invocat
33ac0 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a ions of F..**.**
33ad0 20 7b 48 31 36 36 32 31 7d 20 41 20 63 61 6c 6c {H16621} A call
33ae0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 to [sqlite3_cre
33af0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c ate_collation(B,
33b00 58 2c 45 2c 50 2c 46 29 5d 20 69 73 20 65 78 61 X,E,P,F)] is exa
33b10 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 ctly.**
33b20 20 74 68 65 20 73 61 6d 65 20 61 73 20 61 20 63 the same as a c
33b30 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
33b40 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
33b50 5f 76 32 28 29 5d 20 77 69 74 68 0a 2a 2a 20 20 _v2()] with.**
33b60 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 the same
33b70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 parameters and
33b80 61 20 4e 55 4c 4c 20 64 65 73 74 72 75 63 74 6f a NULL destructo
33b90 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 34 r..**.** {H16624
33ba0 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 } Following a [s
33bb0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
33bc0 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 llation_v2(B,X,E
33bd0 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 ,P,F,D)],.**
33be0 20 20 20 20 20 20 53 51 4c 69 74 65 20 75 73 65 SQLite use
33bf0 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e s the comparison
33c00 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 function F for
33c10 61 6c 6c 20 74 65 78 74 20 63 6f 6d 70 61 72 69 all text compari
33c20 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 son.**
33c30 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 operations on th
33c40 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
33c50 65 63 74 69 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 ection] B on tex
33c60 74 20 76 61 6c 75 65 73 20 74 68 61 74 0a 2a 2a t values that.**
33c70 20 20 20 20 20 20 20 20 20 20 75 73 65 20 74 68 use th
33c80 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 e collating sequ
33c90 65 6e 63 65 20 6e 61 6d 65 64 20 58 2e 0a 2a 2a ence named X..**
33ca0 0a 2a 2a 20 7b 48 31 36 36 32 37 7d 20 54 68 65 .** {H16627} The
33cb0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
33cc0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58 _collation16(B,X
33cd0 2c 45 2c 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74 ,E,P,F)] works t
33ce0 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 he same.**
33cf0 20 20 20 20 61 73 20 5b 73 71 6c 69 74 65 33 5f as [sqlite3_
33d00 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
33d10 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63 (B,X,E,P,F)] exc
33d20 65 70 74 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 ept that the.**
33d30 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 collati
33d40 6f 6e 20 6e 61 6d 65 20 58 20 69 73 20 75 6e 64 on name X is und
33d50 65 72 73 74 6f 6f 64 20 61 73 20 55 54 46 2d 31 erstood as UTF-1
33d60 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 6 in native byte
33d70 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 order.**
33d80 20 20 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 instead of UT
33d90 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 F-8..**.** {H166
33da0 33 30 7d 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 30} When multipl
33db0 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e e comparison fun
33dc0 63 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c ctions are avail
33dd0 61 62 6c 65 20 66 6f 72 20 74 68 65 20 73 61 6d able for the sam
33de0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f e.** co
33df0 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 llating sequence
33e00 2c 20 53 51 4c 69 74 65 20 63 68 6f 6f 73 65 73 , SQLite chooses
33e10 20 74 68 65 20 6f 6e 65 20 77 68 6f 73 65 20 74 the one whose t
33e20 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 ext encoding.**
33e30 20 20 20 20 20 20 20 20 20 72 65 71 75 69 72 65 require
33e40 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 s the least amou
33e50 6e 74 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e nt of conversion
33e60 20 66 72 6f 6d 20 74 68 65 20 64 65 66 61 75 6c from the defaul
33e70 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 t.** te
33e80 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 xt encoding of t
33e90 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a he database..*/.
33ea0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 int sqlite3_crea
33eb0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 te_collation(.
33ec0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e sqlite3*, . con
33ed0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
33ee0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c . int eTextRep,
33ef0 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 . void*,. int
33f00 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 (*xCompare)(void
33f10 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 *,int,const void
33f20 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 *,int,const void
33f30 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *).);.int sqlite
33f40 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
33f50 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 on_v2(. sqlite3
33f60 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 *, . const char
33f70 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 *zName, . int
33f80 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 eTextRep, . voi
33f90 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 d*,. int(*xComp
33fa0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 are)(void*,int,c
33fb0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 onst void*,int,c
33fc0 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 onst void*),. v
33fd0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 oid(*xDestroy)(v
33fe0 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c oid*).);.int sql
33ff0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
34000 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 ation16(. sqlit
34010 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f e3*, . const vo
34020 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 id *zName,. int
34030 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f eTextRep, . vo
34040 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d id*,. int(*xCom
34050 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c pare)(void*,int,
34060 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c const void*,int,
34070 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a const void*).);.
34080 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
34090 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 Collation Neede
340a0 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 d Callbacks {H16
340b0 37 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 700} <S20300>.**
340c0 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 .** To avoid hav
340d0 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 ing to register
340e0 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 all collation se
340f0 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 quences before a
34100 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e database.** can
34110 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 be used, a sing
34120 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 le callback func
34130 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 tion may be regi
34140 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a stered with the.
34150 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
34160 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 nection] to be c
34170 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 alled whenever a
34180 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c n undefined coll
34190 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 ation.** sequenc
341a0 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a e is required..*
341b0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 *.** If the func
341c0 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 tion is register
341d0 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c ed using the sql
341e0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
341f0 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 eeded() API,.**
34200 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 then it is passe
34210 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 d the names of u
34220 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 ndefined collati
34230 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 on sequences as
34240 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 strings.** encod
34250 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31 ed in UTF-8. {H1
34260 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33 6703} If sqlite3
34270 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 _collation_neede
34280 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a d16() is used,.*
34290 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 * the names are
342a0 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 passed as UTF-16
342b0 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 in machine nati
342c0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a ve byte order..*
342d0 2a 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 * A call to eith
342e0 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c er function repl
342f0 61 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e aces any existin
34300 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a g callback..**.*
34310 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 * When the callb
34320 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 ack is invoked,
34330 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
34340 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 nt passed is a c
34350 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 opy.** of the se
34360 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
34370 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
34380 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a on_needed() or.*
34390 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 * sqlite3_collat
343a0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 ion_needed16().
343b0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
343c0 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 ment is the data
343d0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
343e0 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 on. The third a
343f0 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f rgument is one o
34400 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c f [SQLITE_UTF8],
34410 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 [SQLITE_UTF16BE
34420 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 ],.** or [SQLITE
34430 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 _UTF16LE], indic
34440 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 ating the most d
34450 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 esirable form of
34460 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a the collation.*
34470 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 * sequence funct
34480 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 ion required. T
34490 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
344a0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 ter is the name
344b0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 of the.** requir
344c0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 ed collation seq
344d0 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 uence..**.** The
344e0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
344f0 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 on should regist
34500 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 er the desired c
34510 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a ollation using.*
34520 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 * [sqlite3_creat
34530 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 e_collation()],
34540 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
34550 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 collation16()],
34560 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 or.** [sqlite3_c
34570 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
34580 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 v2()]..**.** INV
34590 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
345a0 48 31 36 37 30 32 7d 20 41 20 73 75 63 63 65 73 H16702} A succes
345b0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
345c0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
345d0 6e 65 65 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a needed(D,P,F)].*
345e0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 * or [s
345f0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
34600 5f 6e 65 65 64 65 64 31 36 28 44 2c 50 2c 46 29 _needed16(D,P,F)
34610 5d 20 63 61 75 73 65 73 0a 2a 2a 20 20 20 20 20 ] causes.**
34620 20 20 20 20 20 74 68 65 20 5b 64 61 74 61 62 61 the [databa
34630 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
34640 20 74 6f 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62 to invoke callb
34650 61 63 6b 20 46 20 77 69 74 68 20 66 69 72 73 74 ack F with first
34660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 .** par
34670 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65 ameter P wheneve
34680 72 20 69 74 20 6e 65 65 64 73 20 61 20 63 6f 6d r it needs a com
34690 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e parison function
346a0 20 66 6f 72 20 61 0a 2a 2a 20 20 20 20 20 20 20 for a.**
346b0 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 collating seq
346c0 75 65 6e 63 65 20 74 68 61 74 20 69 74 20 64 6f uence that it do
346d0 65 73 20 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75 es not know abou
346e0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 34 t..**.** {H16704
346f0 7d 20 45 61 63 68 20 73 75 63 63 65 73 73 66 75 } Each successfu
34700 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
34710 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
34720 64 65 64 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 ded()] or.**
34730 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 [sqlite3_c
34740 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 ollation_needed1
34750 36 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 6()] overrides t
34760 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 67 69 he callback regi
34770 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 stered.**
34780 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b on the same [
34790 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
347a0 69 6f 6e 5d 20 62 79 20 70 72 69 6f 72 20 63 61 ion] by prior ca
347b0 6c 6c 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a lls to either.**
347c0 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 interf
347d0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 ace..**.** {H167
347e0 30 36 7d 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 06} The name of
347f0 74 68 65 20 72 65 71 75 65 73 74 65 64 20 63 6f the requested co
34800 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
34810 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 0a 2a passed in the.*
34820 2a 20 20 20 20 20 20 20 20 20 20 34 74 68 20 70 * 4th p
34830 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
34840 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 20 55 callback is in U
34850 54 46 2d 38 20 69 66 20 74 68 65 20 63 61 6c 6c TF-8 if the call
34860 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 back.**
34870 20 77 61 73 20 72 65 67 69 73 74 65 72 65 64 20 was registered
34880 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 using [sqlite3_c
34890 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 ollation_needed(
348a0 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 )] and.**
348b0 20 20 20 69 73 20 69 6e 20 55 54 46 2d 31 36 20 is in UTF-16
348c0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
348d0 72 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63 r if the callbac
348e0 6b 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 k was.**
348f0 20 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 registered usi
34900 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c ng [sqlite3_coll
34910 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 ation_needed16()
34920 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 ]..*/.int sqlite
34930 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
34940 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 ed(. sqlite3*,
34950 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 . void*, . voi
34960 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 d(*)(void*,sqlit
34970 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 e3*,int eTextRep
34980 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b ,const char*).);
34990 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
349a0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 lation_needed16(
349b0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
349c0 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 void*,. void(*)
349d0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c (void*,sqlite3*,
349e0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e int eTextRep,con
349f0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a st void*).);../*
34a00 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 .** Specify the
34a10 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 key for an encry
34a20 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 pted database.
34a30 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f This routine sho
34a40 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 uld be.** called
34a50 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c right after sql
34a60 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a ite3_open()..**.
34a70 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 ** The code to i
34a80 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 mplement this AP
34a90 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 I is not availab
34aa0 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 le in the public
34ab0 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 release.** of S
34ac0 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 QLite..*/.int sq
34ad0 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c lite3_key(. sql
34ae0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
34af0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
34b00 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 atabase to be re
34b10 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 keyed */. const
34b20 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 void *pKey, int
34b30 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 nKey /* The
34b40 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a key */.);../*.*
34b50 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 * Change the key
34b60 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 on an open data
34b70 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 base. If the cu
34b80 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 rrent database i
34b90 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 s not.** encrypt
34ba0 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ed, this routine
34bb0 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 will encrypt it
34bc0 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 . If pNew==0 or
34bd0 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a nNew==0, the.**
34be0 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 database is dec
34bf0 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 rypted..**.** Th
34c00 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d e code to implem
34c10 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 ent this API is
34c20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e not available in
34c30 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 the public rele
34c40 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 ase.** of SQLite
34c50 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
34c60 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 _rekey(. sqlite
34c70 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
34c80 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
34c90 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 base to be rekey
34ca0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f ed */. const vo
34cb0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b id *pKey, int nK
34cc0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 ey /* The ne
34cd0 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a w key */.);../*.
34ce0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 ** CAPI3REF: Sus
34cf0 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 pend Execution F
34d00 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20 or A Short Time
34d10 7b 48 31 30 35 33 30 7d 20 3c 53 34 30 34 31 30 {H10530} <S40410
34d20 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
34d30 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 te3_sleep() func
34d40 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 tion causes the
34d50 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 current thread t
34d60 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 o suspend execut
34d70 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 ion.** for at le
34d80 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 ast a number of
34d90 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 milliseconds spe
34da0 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 cified in its pa
34db0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 rameter..**.** I
34dc0 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 f the operating
34dd0 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 system does not
34de0 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 support sleep re
34df0 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d quests with.** m
34e00 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 illisecond time
34e10 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e resolution, then
34e20 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 the time will b
34e30 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a e rounded up to.
34e40 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 ** the nearest s
34e50 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 econd. The numbe
34e60 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 r of millisecond
34e70 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 s of sleep actua
34e80 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 lly.** requested
34e90 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 from the operat
34ea0 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 ing system is re
34eb0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 turned..**.** SQ
34ec0 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 Lite implements
34ed0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 this interface b
34ee0 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 y calling the xS
34ef0 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 leep().** method
34f00 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 of the default
34f10 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
34f20 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 ject..**.** INVA
34f30 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
34f40 31 30 35 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 10533} The [sqli
34f50 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e te3_sleep(M)] in
34f60 74 65 72 66 61 63 65 20 69 6e 76 6f 6b 65 73 20 terface invokes
34f70 74 68 65 20 78 53 6c 65 65 70 0a 2a 2a 20 20 20 the xSleep.**
34f80 20 20 20 20 20 20 20 6d 65 74 68 6f 64 20 6f 66 method of
34f90 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 the default [sq
34fa0 6c 69 74 65 33 5f 76 66 73 7c 56 46 53 5d 20 69 lite3_vfs|VFS] i
34fb0 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 20 20 n order to.**
34fc0 20 20 20 20 20 20 20 73 75 73 70 65 6e 64 20 65 suspend e
34fd0 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 xecution of the
34fe0 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 66 current thread f
34ff0 6f 72 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 20 or at least.**
35000 20 20 20 20 20 20 20 20 4d 20 6d 69 6c 6c 69 73 M millis
35010 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 econds..**.** {H
35020 31 30 35 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 10536} The [sqli
35030 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e te3_sleep(M)] in
35040 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
35050 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
35060 20 20 20 20 20 20 20 20 20 20 6d 69 6c 6c 69 73 millis
35070 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 econds of sleep
35080 61 63 74 75 61 6c 6c 79 20 72 65 71 75 65 73 74 actually request
35090 65 64 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 ed of the operat
350a0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ing.**
350b0 73 79 73 74 65 6d 2c 20 77 68 69 63 68 20 6d 69 system, which mi
350c0 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 ght be larger th
350d0 61 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 an the parameter
350e0 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 M..*/.int sqlit
350f0 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a e3_sleep(int);..
35100 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
35110 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 Name Of The Fold
35120 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f er Holding Tempo
35130 72 61 72 79 20 46 69 6c 65 73 20 7b 48 31 30 33 rary Files {H103
35140 31 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 10} <S20000>.**.
35150 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61 ** If this globa
35160 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 l variable is ma
35170 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 de to point to a
35180 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 string which is
35190 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 .** the name of
351a0 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e a folder (a.k.a.
351b0 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 directory), the
351c0 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 n all temporary
351d0 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 files.** created
351e0 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 by SQLite will
351f0 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 be placed in tha
35200 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66 t directory. If
35210 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a this variable.*
35220 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e * is a NULL poin
35230 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ter, then SQLite
35240 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 performs a sear
35250 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 ch for an approp
35260 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 riate.** tempora
35270 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 ry file director
35280 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e y..**.** It is n
35290 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f 64 69 66 ot safe to modif
352a0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 y this variable
352b0 6f 6e 63 65 20 61 20 5b 64 61 74 61 62 61 73 65 once a [database
352c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 connection].**
352d0 68 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e has been opened.
352e0 20 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 It is intended
352f0 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 that this varia
35300 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a ble be set once.
35310 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 ** as part of pr
35320 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 ocess initializa
35330 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 tion and before
35340 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 any SQLite inter
35350 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 face.** routines
35360 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 have been call
35370 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 and remain uncha
35380 6e 67 65 64 20 74 68 65 72 65 61 66 74 65 72 2e nged thereafter.
35390 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 .*/.SQLITE_EXTER
353a0 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f N char *sqlite3_
353b0 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a temp_directory;.
353c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
353d0 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 Test For Auto-C
353e0 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 48 31 32 39 ommit Mode {H129
353f0 33 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 30} <S60200>.**
35400 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 KEYWORDS: {autoc
35410 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a ommit mode}.**.*
35420 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 * The sqlite3_ge
35430 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 t_autocommit() i
35440 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
35450 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 non-zero or.**
35460 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 zero if the give
35470 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 n database conne
35480 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e ction is or is n
35490 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 ot in autocommit
354a0 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 mode,.** respec
354b0 74 69 76 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d tively. Autocom
354c0 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 mit mode is on b
354d0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 y default..** Au
354e0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 tocommit mode is
354f0 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b disabled by a [
35500 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 BEGIN] statement
35510 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 ..** Autocommit
35520 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c mode is re-enabl
35530 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d ed by a [COMMIT]
35540 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a or [ROLLBACK]..
35550 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e **.** If certain
35560 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 kinds of errors
35570 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 occur on a stat
35580 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d ement within a m
35590 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a ulti-statement.*
355a0 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 * transaction (e
355b0 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 rrors including
355c0 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b [SQLITE_FULL], [
355d0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a SQLITE_IOERR],.*
355e0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d * [SQLITE_NOMEM]
355f0 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c , [SQLITE_BUSY],
35600 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 and [SQLITE_INT
35610 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 ERRUPT]) then th
35620 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e e.** transaction
35630 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 might be rolled
35640 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 back automatica
35650 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 lly. The only w
35660 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 ay to.** find ou
35670 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 t whether SQLite
35680 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 automatically r
35690 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 olled back the t
356a0 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 ransaction after
356b0 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 .** an error is
356c0 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 to use this func
356d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 tion..**.** INVA
356e0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
356f0 31 32 39 33 31 7d 20 54 68 65 20 5b 73 71 6c 69 12931} The [sqli
35700 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d te3_get_autocomm
35710 69 74 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 it(D)] interface
35720 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
35730 6f 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 o or.**
35740 20 7a 65 72 6f 20 69 66 20 74 68 65 20 5b 64 61 zero if the [da
35750 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
35760 6e 5d 20 44 20 69 73 20 6f 72 20 69 73 20 6e 6f n] D is or is no
35770 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a t in autocommit.
35780 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 64 65 ** mode
35790 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a , respectively..
357a0 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 32 7d 20 41 **.** {H12932} A
357b0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 utocommit mode i
357c0 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e s on by default.
357d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 33 7d 20 .**.** {H12933}
357e0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 Autocommit mode
357f0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 is disabled by a
35800 20 73 75 63 63 65 73 73 66 75 6c 20 5b 42 45 47 successful [BEG
35810 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a IN] statement..*
35820 2a 0a 2a 2a 20 7b 48 31 32 39 33 34 7d 20 41 75 *.** {H12934} Au
35830 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 tocommit mode is
35840 20 65 6e 61 62 6c 65 64 20 62 79 20 61 20 73 75 enabled by a su
35850 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d 4d 49 54 ccessful [COMMIT
35860 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a ] or [ROLLBACK].
35870 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74 ** stat
35880 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 ement..**.** ASS
35890 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 UMPTIONS:.**.**
358a0 7b 41 31 32 39 33 36 7d 20 49 66 20 61 6e 6f 74 {A12936} If anot
358b0 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 her thread chang
358c0 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 es the autocommi
358d0 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 t status of the
358e0 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 database.**
358f0 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 connection
35900 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 while this routi
35910 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 ne is running, t
35920 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 hen the return v
35930 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 alue.**
35940 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
35950 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 /.int sqlite3_ge
35960 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c t_autocommit(sql
35970 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
35980 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 API3REF: Find Th
35990 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c e Database Handl
359a0 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 e Of A Prepared
359b0 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 32 Statement {H1312
359c0 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 0} <S60600>.**.*
359d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 * The sqlite3_db
359e0 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 _handle interfac
359f0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 e returns the [d
35a00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
35a10 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f on] handle.** to
35a20 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 which a [prepar
35a30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 ed statement] be
35a40 6c 6f 6e 67 73 2e 20 20 54 68 65 20 64 61 74 61 longs. The data
35a50 62 61 73 65 20 68 61 6e 64 6c 65 20 72 65 74 75 base handle retu
35a60 72 6e 65 64 20 62 79 0a 2a 2a 20 73 71 6c 69 74 rned by.** sqlit
35a70 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 e3_db_handle is
35a80 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
35a90 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20 77 61 e handle that wa
35aa0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
35ab0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b ment.** to the [
35ac0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
35ad0 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 v2()] call (or i
35ae0 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 ts variants) tha
35af0 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a t was used to.**
35b00 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 create the stat
35b10 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 ement in the fir
35b20 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 st place..**.**
35b30 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
35b40 2a 20 7b 48 31 33 31 32 33 7d 20 54 68 65 20 5b * {H13123} The [
35b50 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c sqlite3_db_handl
35b60 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 e(S)] interface
35b70 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
35b80 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f r.** to
35b90 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
35ba0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 onnection] assoc
35bb0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 0a 2a iated with the.*
35bc0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 * [prep
35bd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
35be0 53 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 S..*/.sqlite3 *s
35bf0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 qlite3_db_handle
35c00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
35c10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
35c20 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 : Find the next
35c30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
35c40 6e 74 20 7b 48 31 33 31 34 30 7d 20 3c 53 36 30 nt {H13140} <S60
35c50 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 600>.**.** This
35c60 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
35c70 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
35c80 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 he next [prepare
35c90 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 d statement] aft
35ca0 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f er.** pStmt asso
35cb0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
35cc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
35cd0 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20 70 tion] pDb. If p
35ce0 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 Stmt is NULL.**
35cf0 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 then this interf
35d00 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
35d10 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 inter to the fir
35d20 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 st prepared stat
35d30 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 ement.** associa
35d40 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74 ted with the dat
35d50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
35d60 20 70 44 62 2e 20 20 49 66 20 6e 6f 20 70 72 65 pDb. If no pre
35d70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a pared statement.
35d80 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65 ** satisfies the
35d90 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 conditions of t
35da0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 his routine, it
35db0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a returns NULL..**
35dc0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
35dd0 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 33 7d 20 49 **.** {H13143} I
35de0 66 20 44 20 69 73 20 61 20 5b 64 61 74 61 62 61 f D is a [databa
35df0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
35e00 68 61 74 20 68 6f 6c 64 73 20 6f 6e 65 20 6f 72 hat holds one or
35e10 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 more.**
35e20 20 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 5b 70 unfinalized [p
35e30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
35e40 74 73 5d 20 61 6e 64 20 53 20 69 73 20 61 20 4e ts] and S is a N
35e50 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 0a 2a 2a 20 ULL pointer,.**
35e60 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 then [s
35e70 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 qlite3_next_stmt
35e80 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 (D, S)] routine
35e90 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 70 shall return a p
35ea0 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 ointer.**
35eb0 20 20 20 74 6f 20 6f 6e 65 20 6f 66 20 74 68 65 to one of the
35ec0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
35ed0 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 ents associated
35ee0 77 69 74 68 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 with D..**.** {H
35ef0 31 33 31 34 36 7d 20 49 66 20 44 20 69 73 20 61 13146} If D is a
35f00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
35f10 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64 ction] that hold
35f20 73 20 6e 6f 20 75 6e 66 69 6e 61 6c 69 7a 65 64 s no unfinalized
35f30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
35f40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
35f50 73 5d 20 61 6e 64 20 53 20 69 73 20 61 20 4e 55 s] and S is a NU
35f60 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e LL pointer, then
35f70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
35f80 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 lite3_next_stmt(
35f90 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 D, S)] routine s
35fa0 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 4e 55 hall return a NU
35fb0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
35fc0 2a 20 7b 48 31 33 31 34 39 7d 20 49 66 20 53 20 * {H13149} If S
35fd0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 is a [prepared s
35fe0 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65 tatement] in the
35ff0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
36000 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 ction] D.**
36010 20 20 20 20 20 61 6e 64 20 53 20 69 73 20 6e 6f and S is no
36020 74 20 74 68 65 20 6c 61 73 74 20 70 72 65 70 61 t the last prepa
36030 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 6e red statement in
36040 20 44 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 D, then.**
36050 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 [sqlite3_ne
36060 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 xt_stmt(D, S)] r
36070 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 outine shall ret
36080 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a urn a pointer.**
36090 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 to the
360a0 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73 next prepared s
360b0 74 61 74 65 6d 65 6e 74 20 69 6e 20 44 20 61 66 tatement in D af
360c0 74 65 72 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ter S..**.** {H1
360d0 33 31 35 32 7d 20 49 66 20 53 20 69 73 20 74 68 3152} If S is th
360e0 65 20 6c 61 73 74 20 5b 70 72 65 70 61 72 65 64 e last [prepared
360f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 74 statement] in t
36100 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
36110 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
36120 69 6f 6e 5d 20 44 20 74 68 65 6e 20 74 68 65 20 ion] D then the
36130 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 [sqlite3_next_st
36140 6d 74 28 44 2c 20 53 29 5d 0a 2a 2a 20 20 20 20 mt(D, S)].**
36150 20 20 20 20 20 20 72 6f 75 74 69 6e 65 20 73 68 routine sh
36160 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 4e 55 4c all return a NUL
36170 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
36180 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a ASSUMPTIONS:.**
36190 0a 2a 2a 20 7b 41 31 33 31 35 34 7d 20 54 68 65 .** {A13154} The
361a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
361b0 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 ction] pointer D
361c0 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a in a call to.**
361d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
361e0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 e3_next_stmt(D,S
361f0 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f )] must refer to
36200 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 an open databas
36210 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f e.** co
36220 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 nnection and in
36230 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 particular must
36240 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f not be a NULL po
36250 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 inter..*/.sqlite
36260 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 3_stmt *sqlite3_
36270 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 next_stmt(sqlite
36280 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 3 *pDb, sqlite3_
36290 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
362a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
362b0 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 ommit And Rollba
362c0 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 ck Notification
362d0 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 35 Callbacks {H1295
362e0 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 0} <S60400>.**.*
362f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
36300 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 mmit_hook() inte
36310 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 rface registers
36320 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 a callback.** fu
36330 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 nction to be inv
36340 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 oked whenever a
36350 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 transaction is c
36360 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 ommitted..** Any
36370 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 callback set by
36380 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c a previous call
36390 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d to sqlite3_comm
363a0 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 it_hook().** for
363b0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
363c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
363d0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 overridden..**
363e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c The sqlite3_roll
363f0 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 back_hook() inte
36400 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 rface registers
36410 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 a callback.** fu
36420 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 nction to be inv
36430 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 oked whenever a
36440 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 transaction is c
36450 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 ommitted..** Any
36460 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 callback set by
36470 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c a previous call
36480 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d to sqlite3_comm
36490 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 it_hook().** for
364a0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
364b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
364c0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 overridden..**
364d0 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e The pArg argumen
364e0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f t is passed thro
364f0 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 ugh to the callb
36500 61 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 ack..** If the c
36510 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d allback on a com
36520 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f mit hook functio
36530 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 n returns non-ze
36540 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 ro,.** then the
36550 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 commit is conver
36560 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 ted into a rollb
36570 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e ack..**.** If an
36580 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 other function w
36590 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 as previously re
365a0 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a gistered, its.**
365b0 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 pArg value is r
365c0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 eturned. Otherw
365d0 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 ise NULL is retu
365e0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 rned..**.** Regi
365f0 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 stering a NULL f
36600 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 unction disables
36610 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a the callback..*
36620 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 *.** For the pur
36630 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 poses of this AP
36640 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e I, a transaction
36650 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 is said to have
36660 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 been.** rolled
36670 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 back if an expli
36680 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 cit "ROLLBACK" s
36690 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 tatement is exec
366a0 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 uted, or.** an e
366b0 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 rror or constrai
366c0 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 nt causes an imp
366d0 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 licit rollback t
366e0 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 o occur..** The
366f0 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 rollback callbac
36700 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 k is not invoked
36710 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f if a transactio
36720 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 n is.** automati
36730 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 cally rolled bac
36740 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61 k because the da
36750 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
36760 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 n is closed..**
36770 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c The rollback cal
36780 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 lback is not inv
36790 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 oked if a transa
367a0 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c ction is.** roll
367b0 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 ed back because
367c0 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 a commit callbac
367d0 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a k returned non-z
367e0 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 ero..** <todo> C
367f0 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 heck on this </t
36800 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 odo>.**.** INVAR
36810 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
36820 32 39 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 2951} The [sqlit
36830 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 e3_commit_hook(D
36840 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 ,F,P)] interface
36850 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a registers the.*
36860 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 * callb
36870 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 ack function F t
36880 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 o be invoked wit
36890 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 h argument P whe
368a0 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 never.**
368b0 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 a transaction
368c0 63 6f 6d 6d 69 74 73 20 6f 6e 20 74 68 65 20 5b commits on the [
368d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
368e0 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ion] D..**.** {H
368f0 31 32 39 35 32 7d 20 54 68 65 20 5b 73 71 6c 69 12952} The [sqli
36900 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 te3_commit_hook(
36910 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 D,F,P)] interfac
36920 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 e returns the P
36930 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 argument.**
36940 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20 70 72 from the pr
36950 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 evious call with
36960 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 the same [datab
36970 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
36980 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f D,.** o
36990 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 r NULL on the fi
369a0 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 61 20 70 rst call for a p
369b0 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 articular databa
369c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e se connection D.
369d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 33 7d 20 .**.** {H12953}
369e0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 Each call to [sq
369f0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f lite3_commit_hoo
36a00 6b 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 k()] overwrites
36a10 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 the callback.**
36a20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 registe
36a30 72 65 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c red by prior cal
36a40 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 ls..**.** {H1295
36a50 34 7d 20 49 66 20 74 68 65 20 46 20 61 72 67 75 4} If the F argu
36a60 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
36a70 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 _commit_hook(D,F
36a80 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 ,P)] is NULL.**
36a90 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 then th
36aa0 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 e commit hook ca
36ab0 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c llback is cancel
36ac0 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 ed and no callba
36ad0 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 ck.** i
36ae0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 s invoked when a
36af0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d transaction com
36b00 6d 69 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 mits..**.** {H12
36b10 39 35 35 7d 20 49 66 20 74 68 65 20 63 6f 6d 6d 955} If the comm
36b20 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 it callback retu
36b30 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65 rns non-zero the
36b40 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 0a n the commit is.
36b50 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 76 ** conv
36b60 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c erted into a rol
36b70 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 lback..**.** {H1
36b80 32 39 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 2961} The [sqlit
36b90 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b e3_rollback_hook
36ba0 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 (D,F,P)] interfa
36bb0 63 65 20 72 65 67 69 73 74 65 72 73 20 74 68 65 ce registers the
36bc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c .** cal
36bd0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 lback function F
36be0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 to be invoked w
36bf0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 ith argument P w
36c00 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 henever.**
36c10 20 20 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f a transactio
36c20 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e 20 n rolls back on
36c30 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
36c40 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a nnection] D..**.
36c50 2a 2a 20 7b 48 31 32 39 36 32 7d 20 54 68 65 20 ** {H12962} The
36c60 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 [sqlite3_rollbac
36c70 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 k_hook(D,F,P)] i
36c80 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
36c90 20 74 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20 the P.**
36ca0 20 20 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d argument from
36cb0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 the previous ca
36cc0 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 ll with the same
36cd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 .** [da
36ce0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
36cf0 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e n] D, or NULL on
36d00 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 0a the first call.
36d10 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 ** for
36d20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 a particular dat
36d30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
36d40 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 D..**.** {H1296
36d50 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 3} Each call to
36d60 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 [sqlite3_rollbac
36d70 6b 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 k_hook()] overwr
36d80 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 ites the callbac
36d90 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 k.** re
36da0 67 69 73 74 65 72 65 64 20 62 79 20 70 72 69 6f gistered by prio
36db0 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b r calls..**.** {
36dc0 48 31 32 39 36 34 7d 20 49 66 20 74 68 65 20 46 H12964} If the F
36dd0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 argument to [sq
36de0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 lite3_rollback_h
36df0 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e ook(D,F,P)] is N
36e00 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ULL.**
36e10 74 68 65 6e 20 74 68 65 20 72 6f 6c 6c 62 61 63 then the rollbac
36e20 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 k hook callback
36e30 69 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 is canceled and
36e40 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 no callback.**
36e50 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b is invok
36e60 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 ed when a transa
36e70 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b ction rolls back
36e80 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ..*/.void *sqlit
36e90 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 e3_commit_hook(s
36ea0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 qlite3*, int(*)(
36eb0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a void*), void*);.
36ec0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f void *sqlite3_ro
36ed0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 llback_hook(sqli
36ee0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f te3*, void(*)(vo
36ef0 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a id *), void*);..
36f00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
36f10 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 Data Change Noti
36f20 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 fication Callbac
36f30 6b 73 20 7b 48 31 32 39 37 30 7d 20 3c 53 36 30 ks {H12970} <S60
36f40 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 400>.**.** The s
36f50 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f qlite3_update_ho
36f60 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ok() interface r
36f70 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 egisters a callb
36f80 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ack function.**
36f90 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 with the [databa
36fa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
36fb0 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 dentified by the
36fc0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a first argument.
36fd0 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 ** to be invoked
36fe0 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 whenever a row
36ff0 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 is updated, inse
37000 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e rted or deleted.
37010 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b .** Any callback
37020 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f set by a previo
37030 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 us call to this
37040 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 function.** for
37050 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
37060 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
37070 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a overridden..**.*
37080 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 * The second arg
37090 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
370a0 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 er to the functi
370b0 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 on to invoke whe
370c0 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 n a.** row is up
370d0 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 dated, inserted
370e0 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 54 or deleted..** T
370f0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
37100 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 t to the callbac
37110 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 k is a copy of t
37120 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
37130 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f t.** to sqlite3_
37140 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a update_hook()..*
37150 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c * The second cal
37160 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 lback argument i
37170 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 s one of [SQLITE
37180 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 _INSERT], [SQLIT
37190 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 E_DELETE],.** or
371a0 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d [SQLITE_UPDATE]
371b0 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 , depending on t
371c0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 he operation tha
371d0 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c t caused the cal
371e0 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 lback.** to be i
371f0 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74 nvoked..** The t
37200 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 hird and fourth
37210 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 arguments to the
37220 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 callback contai
37230 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 n pointers to th
37240 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e e.** database an
37250 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e d table name con
37260 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 taining the affe
37270 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 cted row..** The
37280 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 final callback
37290 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
372a0 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f rowid of the ro
372b0 77 2e 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f w. In the case o
372c0 66 0a 2a 2a 20 61 6e 20 75 70 64 61 74 65 2c 20 f.** an update,
372d0 74 68 69 73 20 69 73 20 74 68 65 20 72 6f 77 69 this is the rowi
372e0 64 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61 d after the upda
372f0 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a te takes place..
37300 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 **.** The update
37310 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 hook is not inv
37320 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e oked when intern
37330 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 al system tables
37340 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 are.** modified
37350 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 (i.e. sqlite_ma
37360 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f ster and sqlite_
37370 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a sequence)..**.**
37380 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 If another func
37390 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 tion was previou
373a0 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 sly registered,
373b0 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a its pArg value.*
373c0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 * is returned.
373d0 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 Otherwise NULL i
373e0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
373f0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
37400 0a 2a 2a 20 7b 48 31 32 39 37 31 7d 20 54 68 65 .** {H12971} The
37410 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 [sqlite3_update
37420 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e _hook(D,F,P)] in
37430 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 terface causes t
37440 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 he callback.**
37450 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e function
37460 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 F to be invoked
37470 20 77 69 74 68 20 66 69 72 73 74 20 70 61 72 61 with first para
37480 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 meter P whenever
37490 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 .** a t
374a0 61 62 6c 65 20 72 6f 77 20 69 73 20 6d 6f 64 69 able row is modi
374b0 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 2c 20 fied, inserted,
374c0 6f 72 20 64 65 6c 65 74 65 64 20 6f 6e 0a 2a 2a or deleted on.**
374d0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64 the [d
374e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
374f0 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 on] D..**.** {H1
37500 32 39 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 2973} The [sqlit
37510 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 e3_update_hook(D
37520 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 ,F,P)] interface
37530 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c returns the val
37540 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f ue.** o
37550 66 20 50 20 66 6f 72 20 74 68 65 20 70 72 65 76 f P for the prev
37560 69 6f 75 73 20 63 61 6c 6c 20 6f 6e 20 74 68 65 ious call on the
37570 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 same [database
37580 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a connection] D,.*
37590 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 * or NU
375a0 4c 4c 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 LL for the first
375b0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 call..**.** {H1
375c0 32 39 37 35 7d 20 49 66 20 74 68 65 20 75 70 64 2975} If the upd
375d0 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 ate hook callbac
375e0 6b 20 46 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f k F in [sqlite3_
375f0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c update_hook(D,F,
37600 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 P)].**
37610 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 is NULL then the
37620 20 6e 6f 20 75 70 64 61 74 65 20 63 61 6c 6c 62 no update callb
37630 61 63 6b 73 20 61 72 65 20 6d 61 64 65 2e 0a 2a acks are made..*
37640 2a 0a 2a 2a 20 7b 48 31 32 39 37 37 7d 20 45 61 *.** {H12977} Ea
37650 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ch call to [sqli
37660 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 te3_update_hook(
37670 44 2c 46 2c 50 29 5d 20 6f 76 65 72 72 69 64 65 D,F,P)] override
37680 73 20 70 72 69 6f 72 20 63 61 6c 6c 73 0a 2a 2a s prior calls.**
37690 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 to the
376a0 20 73 61 6d 65 20 69 6e 74 65 72 66 61 63 65 20 same interface
376b0 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 on the same [dat
376c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
376d0 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 ] D..**.** {H129
376e0 37 39 7d 20 54 68 65 20 75 70 64 61 74 65 20 68 79} The update h
376f0 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ook callback is
37700 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e not invoked when
37710 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d internal system
37720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 61 62 .** tab
37730 6c 65 73 20 73 75 63 68 20 61 73 20 73 71 6c 69 les such as sqli
37740 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 te_master and sq
37750 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 20 61 72 lite_sequence ar
37760 65 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a e modified..**.*
37770 2a 20 7b 48 31 32 39 38 31 7d 20 54 68 65 20 73 * {H12981} The s
37780 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
37790 74 6f 20 74 68 65 20 75 70 64 61 74 65 20 63 61 to the update ca
377a0 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 llback.**
377b0 20 20 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 is one of [SQ
377c0 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 LITE_INSERT], [S
377d0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72 QLITE_DELETE] or
377e0 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d [SQLITE_UPDATE]
377f0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 ,.** de
37800 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f pending on the o
37810 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 peration that ca
37820 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 used the callbac
37830 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e k to be invoked.
37840 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 38 33 7d 20 .**.** {H12983}
37850 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f The third and fo
37860 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 urth arguments t
37870 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 o the callback c
37880 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 0a ontain pointers.
37890 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 7a ** to z
378a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
378b0 54 46 2d 38 20 73 74 72 69 6e 67 73 20 77 68 69 TF-8 strings whi
378c0 63 68 20 61 72 65 20 74 68 65 20 6e 61 6d 65 73 ch are the names
378d0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 of the.**
378e0 20 20 20 20 64 61 74 61 62 61 73 65 20 61 6e 64 database and
378f0 20 74 61 62 6c 65 20 74 68 61 74 20 69 73 20 62 table that is b
37900 65 69 6e 67 20 75 70 64 61 74 65 64 2e 0a 0a 2a eing updated...*
37910 2a 20 7b 48 31 32 39 38 35 7d 20 54 68 65 20 66 * {H12985} The f
37920 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 inal callback pa
37930 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 72 rameter is the r
37940 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77 20 owid of the row
37950 61 66 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 after.**
37960 20 20 74 68 65 20 63 68 61 6e 67 65 20 6f 63 63 the change occ
37970 75 72 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 urs..*/.void *sq
37980 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f lite3_update_hoo
37990 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a k(. sqlite3*, .
379a0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a void(*)(void *
379b0 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 ,int ,char const
379c0 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c *,char const *,
379d0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a sqlite3_int64),.
379e0 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a void*.);../*.*
379f0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 * CAPI3REF: Enab
37a00 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 le Or Disable Sh
37a10 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 ared Pager Cache
37a20 20 7b 48 31 30 33 33 30 7d 20 3c 53 33 30 39 30 {H10330} <S3090
37a30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 0>.** KEYWORDS:
37a40 7b 73 68 61 72 65 64 20 63 61 63 68 65 7d 20 7b {shared cache} {
37a50 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 shared cache mod
37a60 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f e}.**.** This ro
37a70 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 utine enables or
37a80 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 disables the sh
37a90 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 aring of the dat
37aa0 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 abase cache.** a
37ab0 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 nd schema data s
37ac0 74 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65 tructures betwee
37ad0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
37ae0 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 ection | connect
37af0 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 ions].** to the
37b00 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 same database. S
37b10 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 haring is enable
37b20 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e d if the argumen
37b30 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 t is true.** and
37b40 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 disabled if the
37b50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c argument is fal
37b60 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 se..**.** Cache
37b70 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c sharing is enabl
37b80 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 ed and disabled
37b90 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 for an entire pr
37ba0 6f 63 65 73 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 ocess. {END}.**
37bb0 54 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 This is a change
37bc0 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 as of SQLite ve
37bd0 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 rsion 3.5.0. In
37be0 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f prior versions o
37bf0 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 f SQLite,.** sha
37c00 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64 ring was enabled
37c10 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 or disabled for
37c20 20 65 61 63 68 20 74 68 72 65 61 64 20 73 65 70 each thread sep
37c30 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 arately..**.** T
37c40 68 65 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 he cache sharing
37c50 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 mode set by thi
37c60 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 s interface effe
37c70 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 cts all subseque
37c80 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b nt.** calls to [
37c90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
37ca0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
37cb0 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 2()], and [sqlit
37cc0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a e3_open16()]..**
37cd0 20 45 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 Existing databa
37ce0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 se connections c
37cf0 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 ontinue use the
37d00 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 sharing mode.**
37d10 74 68 61 74 20 77 61 73 20 69 6e 20 65 66 66 65 that was in effe
37d20 63 74 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 ct at the time t
37d30 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e hey were opened.
37d40 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 .**.** Virtual t
37d50 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 ables cannot be
37d60 75 73 65 64 20 77 69 74 68 20 61 20 73 68 61 72 used with a shar
37d70 65 64 20 63 61 63 68 65 2e 20 20 57 68 65 6e 20 ed cache. When
37d80 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 shared.** cache
37d90 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 is enabled, the
37da0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
37db0 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49 20 75 73 module()] API us
37dc0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a ed to register.*
37dd0 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 * virtual tables
37de0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 will always ret
37df0 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a urn an error..**
37e00 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
37e10 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
37e20 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 _OK] if shared c
37e30 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 ache was enabled
37e40 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 or disabled.**
37e50 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 successfully. A
37e60 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
37e70 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 s returned other
37e80 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 wise..**.** Shar
37e90 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 ed cache is disa
37ea0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e bled by default.
37eb0 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 But this might
37ec0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 change in.** fut
37ed0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
37ee0 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 SQLite. Applica
37ef0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 tions that care
37f00 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 about shared.**
37f10 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 cache setting sh
37f20 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c ould set it expl
37f30 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e icitly..**.** IN
37f40 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
37f50 7b 48 31 30 33 33 31 7d 20 41 20 73 75 63 63 65 {H10331} A succe
37f60 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e ssful invocation
37f70 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 of [sqlite3_ena
37f80 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 ble_shared_cache
37f90 28 42 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 (B)].**
37fa0 20 77 69 6c 6c 20 65 6e 61 62 6c 65 20 6f 72 20 will enable or
37fb0 64 69 73 61 62 6c 65 20 73 68 61 72 65 64 20 63 disable shared c
37fc0 61 63 68 65 20 6d 6f 64 65 20 66 6f 72 20 61 6e ache mode for an
37fd0 79 20 73 75 62 73 65 71 75 65 6e 74 6c 79 0a 2a y subsequently.*
37fe0 2a 20 20 20 20 20 20 20 20 20 20 63 72 65 61 74 * creat
37ff0 65 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ed [database con
38000 6e 65 63 74 69 6f 6e 5d 20 69 6e 20 74 68 65 20 nection] in the
38010 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a same process..**
38020 0a 2a 2a 20 7b 48 31 30 33 33 36 7d 20 57 68 65 .** {H10336} Whe
38030 6e 20 73 68 61 72 65 64 20 63 61 63 68 65 20 69 n shared cache i
38040 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b s enabled, the [
38050 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d sqlite3_create_m
38060 6f 64 75 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 odule()].**
38070 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 77 interface w
38080 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 ill always retur
38090 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a n an error..**.*
380a0 2a 20 7b 48 31 30 33 33 37 7d 20 54 68 65 20 5b * {H10337} The [
380b0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 sqlite3_enable_s
380c0 68 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d 20 hared_cache(B)]
380d0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
380e0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 s.** [S
380f0 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 QLITE_OK] if sha
38100 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e red cache was en
38110 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 abled or disable
38120 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 0a d successfully..
38130 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33 39 7d 20 53 **.** {H10339} S
38140 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 hared cache is d
38150 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
38160 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 lt..*/.int sqlit
38170 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 e3_enable_shared
38180 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a _cache(int);../*
38190 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 .** CAPI3REF: At
381a0 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 tempt To Free He
381b0 61 70 20 4d 65 6d 6f 72 79 20 7b 48 31 37 33 34 ap Memory {H1734
381c0 30 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 0} <S30220>.**.*
381d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
381e0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 lease_memory() i
381f0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 nterface attempt
38200 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 s to free N byte
38210 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d s.** of heap mem
38220 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 ory by deallocat
38230 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 ing non-essentia
38240 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
38250 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 ions.** held by
38260 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 the database lib
38270 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d rary. {END} Mem
38280 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 ory used to cach
38290 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 e database.** pa
382a0 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 ges to improve p
382b0 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e erformance is an
382c0 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d example of non-
382d0 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 essential memory
382e0 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c ..** sqlite3_rel
382f0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 ease_memory() re
38300 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
38310 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c of bytes actual
38320 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 ly freed,.** whi
38330 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 ch might be more
38340 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 or less than th
38350 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 e amount request
38360 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 ed..**.** INVARI
38370 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 ANTS:.**.** {H17
38380 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 341} The [sqlite
38390 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 3_release_memory
383a0 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 (N)] interface a
383b0 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 20 20 ttempts to.**
383c0 20 20 20 20 20 20 20 66 72 65 65 20 4e 20 62 79 free N by
383d0 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f tes of heap memo
383e0 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 ry by deallocati
383f0 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c ng non-essential
38400 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d .** mem
38410 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 ory allocations
38420 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 held by the data
38430 62 61 73 65 20 6c 69 62 72 61 72 79 2e 0a 2a 2a base library..**
38440 0a 2a 2a 20 7b 48 31 36 33 34 32 7d 20 54 68 65 .** {H16342} The
38450 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 [sqlite3_releas
38460 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 72 65 74 e_memory(N)] ret
38470 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 0a urns the number.
38480 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 62 ** of b
38490 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 ytes actually fr
384a0 65 65 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74 eed, which might
384b0 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 be more or less
384c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 .** tha
384d0 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 n the amount req
384e0 75 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 uested..*/.int s
384f0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d qlite3_release_m
38500 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a emory(int);../*.
38510 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 ** CAPI3REF: Imp
38520 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 ose A Limit On H
38530 65 61 70 20 53 69 7a 65 20 7b 48 31 37 33 35 30 eap Size {H17350
38540 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a } <S30220>.**.**
38550 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 The sqlite3_sof
38560 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 t_heap_limit() i
38570 6e 74 65 72 66 61 63 65 20 70 6c 61 63 65 73 20 nterface places
38580 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a a "soft" limit.*
38590 2a 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 * on the amount
385a0 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 of heap memory t
385b0 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 hat may be alloc
385c0 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a ated by SQLite..
385d0 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 ** If an interna
385e0 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 l allocation is
385f0 72 65 71 75 65 73 74 65 64 20 74 68 61 74 20 77 requested that w
38600 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a ould exceed the.
38610 2a 2a 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d ** soft heap lim
38620 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c it, [sqlite3_rel
38630 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 ease_memory()] i
38640 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 s invoked one or
38650 0a 2a 2a 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 .** more times t
38660 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 o free up some s
38670 70 61 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 pace before the
38680 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 allocation is pe
38690 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 rformed..**.** T
386a0 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c he limit is call
386b0 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 ed "soft", becau
386c0 73 65 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 se if [sqlite3_r
386d0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d elease_memory()]
386e0 0a 2a 2a 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 .** cannot free
386f0 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 sufficient memor
38700 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 y to prevent the
38710 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e limit from bein
38720 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 g exceeded,.** t
38730 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c he memory is all
38740 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e ocated anyway an
38750 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 d the current op
38760 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 eration proceeds
38770 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 ..**.** A negati
38780 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 ve or zero value
38790 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 for N means tha
387a0 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f t there is no so
387b0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e ft heap limit an
387c0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 d.** [sqlite3_re
387d0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 lease_memory()]
387e0 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c will only be cal
387f0 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 led when memory
38800 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a is exhausted..**
38810 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c The default val
38820 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 ue for the soft
38830 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 heap limit is ze
38840 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ro..**.** SQLite
38850 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 makes a best ef
38860 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 fort to honor th
38870 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 e soft heap limi
38880 74 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 t..** But if the
38890 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
388a0 20 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 cannot be honor
388b0 65 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 ed, execution wi
388c0 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 ll.** continue w
388d0 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 ithout error or
388e0 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 notification. T
388f0 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c his is why the l
38900 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 imit is.** calle
38910 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 d a "soft" limit
38920 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 . It is advisor
38930 79 20 6f 6e 6c 79 2e 0a 2a